Skip to content
Snippets Groups Projects
Commit 3bfe32988a3c authored by Bob Ippolito's avatar Bob Ippolito
Browse files

update documentation per #102

parent efd37532e4e9
No related branches found
No related tags found
No related merge requests found
Version 3.6.1 released 2014-08-09
* Documentation updates
https://github.com/simplejson/simplejson/issues/102
Version 3.6.0 released 2014-07-21
* Automatically strip any UTF-8 BOM from input to more closely
......
......@@ -44,7 +44,7 @@
# The short X.Y version.
version = '3.6'
# The full version, including alpha/beta/rc tags.
release = '3.6.0'
release = '3.6.1'
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
......
......@@ -6,8 +6,10 @@
.. moduleauthor:: Bob Ippolito <bob@redivi.com>
.. sectionauthor:: Bob Ippolito <bob@redivi.com>
JSON (JavaScript Object Notation) <http://json.org> is a subset of JavaScript
syntax (ECMA-262 3rd edition) used as a lightweight data interchange format.
`JSON (JavaScript Object Notation) <http://json.org>`_, specified by
:rfc:`4627`, is a lightweight data interchange format based on a subset of
`JavaScript <http://en.wikipedia.org/wiki/JavaScript>`_ syntax (`ECMA-262 3rd
edition <http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdf>`_).
:mod:`simplejson` exposes an API familiar to users of the standard library
:mod:`marshal` and :mod:`pickle` modules. It is the externally maintained
......@@ -107,7 +109,7 @@
'[2.0, 1.0]'
.. highlight:: none
.. highlight:: bash
Using :mod:`simplejson.tool` from the shell to validate and pretty-print::
......@@ -122,10 +124,12 @@
.. note::
The JSON produced by this module's default settings is a subset of
YAML, so it may be used as a serializer for that as well.
JSON is a subset of `YAML <http://yaml.org/>`_ 1.2. The JSON produced by
this module's default settings (in particular, the default *separators*
value) is also a subset of YAML 1.0 and 1.1. This module can thus also be
used as a YAML serializer.
Basic Usage
-----------
......@@ -127,8 +131,15 @@
Basic Usage
-----------
.. function:: dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, sort_keys[, item_sort_key[, [for_json[, ignore_nan[, int_as_string_bitcount[, **kw]]]]]]]]]]]]]]]]]]])
.. function:: dump(obj, fp, skipkeys=False, ensure_ascii=True, \
check_circular=True, allow_nan=True, cls=None, \
indent=None, separators=None, encoding='utf-8', \
default=None, use_decimal=True, \
namedtuple_as_object=True, tuple_as_array=True, \
bigint_as_string=False, sort_keys=False, \
item_sort_key=None, for_json=None, ignore_nan=False, \
int_as_string_bitcount=None, **kw)
Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
......@@ -133,9 +144,9 @@
Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
file-like object).
file-like object) using this :ref:`conversion table <py-to-json-table>`.
If *skipkeys* is true (default: ``False``), then dict keys that are not
of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`,
:class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a
:exc:`TypeError`.
......@@ -136,9 +147,13 @@
If *skipkeys* is true (default: ``False``), then dict keys that are not
of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`,
:class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a
:exc:`TypeError`.
The :mod:`simplejson` module will produce :class:`str` objects in Python 3,
not :class:`bytes` objects. Therefore, ``fp.write()`` must support
:class:`str` input.
If *ensure_ascii* is false (default: ``True``), then some chunks written
to *fp* may be :class:`unicode` instances, subject to normal Python
:class:`str` to :class:`unicode` coercion rules. Unless ``fp.write()``
......@@ -262,7 +277,7 @@
.. versionchanged:: 3.2.0
*ignore_nan* is new in 3.2.0.
If *int_as_string_bitcount* is a positive number ``n`` (default: ``False``),
If *int_as_string_bitcount* is a positive number ``n`` (default: ``None``),
:class:`int` ``2**n`` and higher or lower than ``-2**n`` will be encoded as strings. This is to
avoid the rounding that happens in Javascript otherwise. Note that this
option loses type information, so use with extreme caution.
......@@ -278,10 +293,17 @@
container protocol to delimit them.
.. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, sort_keys[, item_sort_key[, for_json[, ignore_nan[, int_as_string_bitcount[, **kw]]]]]]]]]]]]]]]]]])
.. function:: dumps(obj, skipkeys=False, ensure_ascii=True, \
check_circular=True, allow_nan=True, cls=None, \
indent=None, separators=None, encoding='utf-8', \
default=None, use_decimal=True, \
namedtuple_as_object=True, tuple_as_array=True, \
bigint_as_string=False, sort_keys=False, \
item_sort_key=None, for_json=None, ignore_nan=False, \
int_as_string_bitcount=None, **kw)
Serialize *obj* to a JSON formatted :class:`str`.
If *ensure_ascii* is false, then the return value will be a
:class:`unicode` instance. The other arguments have the same meaning as in
:func:`dump`. Note that the default *ensure_ascii* setting has much
......@@ -282,11 +304,11 @@
Serialize *obj* to a JSON formatted :class:`str`.
If *ensure_ascii* is false, then the return value will be a
:class:`unicode` instance. The other arguments have the same meaning as in
:func:`dump`. Note that the default *ensure_ascii* setting has much
better performance.
better performance in Python 2.
The other options have the same meaning as in :func:`dump`.
......@@ -289,7 +311,10 @@
The other options have the same meaning as in :func:`dump`.
.. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, use_decimal[, **kw]]]]]]]]])
.. function:: load(fp, encoding='utf-8', cls=None, object_hook=None, \
parse_float=None, parse_int=None, \
parse_constant=None, object_pairs_hook=None, \
use_decimal=None, **kw)
Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON
......@@ -294,6 +319,7 @@
Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON
document) to a Python object. :exc:`JSONDecodeError` will be
document) to a Python object using this
:ref:`conversion table <json-to-py-table>`. :exc:`JSONDecodeError` will be
raised if the given JSON document is not valid.
If the contents of *fp* are encoded with an ASCII based encoding other than
......@@ -311,7 +337,8 @@
*object_hook* is an optional function that will be called with the result of
any object literal decode (a :class:`dict`). The return value of
*object_hook* will be used instead of the :class:`dict`. This feature can be used
to implement custom decoders (e.g. JSON-RPC class hinting).
to implement custom decoders (e.g. `JSON-RPC <http://www.jsonrpc.org>`_
class hinting).
*object_pairs_hook* is an optional function that will be called with the
result of any object literal decode with an ordered list of pairs. The
......@@ -363,7 +390,10 @@
only one JSON document, it is recommended to use :func:`loads`.
.. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, use_decimal[, **kw]]]]]]]]])
.. function:: loads(fp, encoding='utf-8', cls=None, object_hook=None, \
parse_float=None, parse_int=None, \
parse_constant=None, object_pairs_hook=None, \
use_decimal=None, **kw)
Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON
document) to a Python object. :exc:`JSONDecodeError` will be
......@@ -385,9 +415,11 @@
Encoders and decoders
---------------------
.. class:: JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, strict]]]]]]])
.. class:: JSONDecoder(encoding='utf-8', object_hook=None, parse_float=None, \
parse_int=None, parse_constant=None, \
object_pairs_hook=None, strict=True)
Simple JSON decoder.
Performs the following translations in decoding by default:
......@@ -389,27 +421,29 @@
Simple JSON decoder.
Performs the following translations in decoding by default:
+---------------+-------------------+
| JSON | Python |
+===============+===================+
| object | dict |
+---------------+-------------------+
| array | list |
+---------------+-------------------+
| string | unicode |
+---------------+-------------------+
| number (int) | int, long |
+---------------+-------------------+
| number (real) | float |
+---------------+-------------------+
| true | True |
+---------------+-------------------+
| false | False |
+---------------+-------------------+
| null | None |
+---------------+-------------------+
.. _json-to-py-table:
+---------------+-----------+-----------+
| JSON | Python 2 | Python 3 |
+===============+===========+===========+
| object | dict | dict |
+---------------+-----------+-----------+
| array | list | list |
+---------------+-----------+-----------+
| string | unicode | str |
+---------------+-----------+-----------+
| number (int) | int, long | int |
+---------------+-----------+-----------+
| number (real) | float | float |
+---------------+-----------+-----------+
| true | True | True |
+---------------+-----------+-----------+
| false | False | False |
+---------------+-----------+-----------+
| null | None | None |
+---------------+-----------+-----------+
It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
corresponding ``float`` values, which is outside the JSON spec.
......@@ -484,9 +518,16 @@
:exc:`JSONDecodeError` will be raised if the given JSON
document is not valid.
.. class:: JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, item_sort_key[, for_json[, ignore_nan]]]]]]]]]]]]]]]])
.. class:: JSONEncoder(skipkeys=False, ensure_ascii=True, \
check_circular=True, allow_nan=True, sort_keys=False, \
indent=None, separators=None, encoding='utf-8', \
default=None, use_decimal=True, \
namedtuple_as_object=True, tuple_as_array=True, \
bigint_as_string=False, item_sort_key=None, \
for_json=True, ignore_nan=False, \
int_as_string_bitcount=None)
Extensible JSON encoder for Python data structures.
Supports the following objects and types by default:
......@@ -488,8 +529,10 @@
Extensible JSON encoder for Python data structures.
Supports the following objects and types by default:
.. _py-to-json-table:
+-------------------+---------------+
| Python | JSON |
+===================+===============+
......@@ -508,6 +551,9 @@
| None | null |
+-------------------+---------------+
It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
corresponding ``float`` values, which is outside the JSON spec.
.. versionchanged:: 2.2.0
Changed *namedtuple* encoding from JSON array to object.
......@@ -529,7 +575,7 @@
:class:`str` objects with all incoming unicode characters escaped. If
*ensure_ascii* is false, the output will be a unicode object.
If *check_circular* is false (the default), then lists, dicts, and custom
If *check_circular* is true (the default), then lists, dicts, and custom
encoded objects will be checked for circular references during encoding to
prevent an infinite recursion (which would cause an :exc:`OverflowError`).
Otherwise, no such check takes place.
......@@ -675,7 +721,16 @@
Note that :meth:`encode` has much better performance than
:meth:`iterencode`.
.. class:: JSONEncoderForHTML([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, item_sort_key[, for_json[, ignore_nan]]]]]]]]]]]]]]]])
.. class:: JSONEncoderForHTML(skipkeys=False, ensure_ascii=True, \
check_circular=True, allow_nan=True, \
sort_keys=False, indent=None, separators=None, \
encoding='utf-8', \
default=None, use_decimal=True, \
namedtuple_as_object=True, \
tuple_as_array=True, \
bigint_as_string=False, item_sort_key=None, \
for_json=True, ignore_nan=False, \
int_as_string_bitcount=None)
Subclass of :class:`JSONEncoder` that escapes &, <, and > for embedding in HTML.
......@@ -685,7 +740,7 @@
Exceptions
----------
.. exception:: JSONDecodeError(msg, doc, pos[, end])
.. exception:: JSONDecodeError(msg, doc, pos, end=None)
Subclass of :exc:`ValueError` with the following additional attributes:
......@@ -720,3 +775,125 @@
.. attribute:: endcolno
The column corresponding to end (may be ``None``)
Standard Compliance
-------------------
The JSON format is specified by :rfc:`4627`. This section details this
module's level of compliance with the RFC. For simplicity,
:class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and parameters other
than those explicitly mentioned, are not considered.
This module does not comply with the RFC in a strict fashion, implementing some
extensions that are valid JavaScript but not valid JSON. In particular:
- Top-level non-object, non-array values are accepted and output;
- Infinite and NaN number values are accepted and output;
- Repeated names within an object are accepted, and only the value of the last
name-value pair is used.
Since the RFC permits RFC-compliant parsers to accept input texts that are not
RFC-compliant, this module's deserializer is technically RFC-compliant under
default settings.
Character Encodings
^^^^^^^^^^^^^^^^^^^
The RFC recommends that JSON be represented using either UTF-8, UTF-16, or
UTF-32, with UTF-8 being the default.
As permitted, though not required, by the RFC, this module's serializer sets
*ensure_ascii=True* by default, thus escaping the output so that the resulting
strings only contain ASCII characters.
Other than the *ensure_ascii* parameter, this module is defined strictly in
terms of conversion between Python objects and
:class:`Unicode strings <str>`, and thus does not otherwise address the issue
of character encodings.
Infinite and NaN Number Values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The RFC does not permit the representation of infinite or NaN number values.
Despite that, by default, this module accepts and outputs ``Infinity``,
``-Infinity``, and ``NaN`` as if they were valid JSON number literal values::
>>> # Neither of these calls raises an exception, but the results are not valid JSON
>>> json.dumps(float('-inf'))
'-Infinity'
>>> json.dumps(float('nan'))
'NaN'
>>> # Same when deserializing
>>> json.loads('-Infinity')
-inf
>>> json.loads('NaN')
nan
In the serializer, the *allow_nan* parameter can be used to alter this
behavior. In the deserializer, the *parse_constant* parameter can be used to
alter this behavior.
Repeated Names Within an Object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The RFC specifies that the names within a JSON object should be unique, but
does not specify how repeated names in JSON objects should be handled. By
default, this module does not raise an exception; instead, it ignores all but
the last name-value pair for a given name::
>>> weird_json = '{"x": 1, "x": 2, "x": 3}'
>>> json.loads(weird_json) == {'x': 3}
True
The *object_pairs_hook* parameter can be used to alter this behavior.
.. highlight:: bash
.. _json-commandline:
Command Line Interface
----------------------
The :mod:`simplejson.tool` module provides a simple command line interface to
validate and pretty-print JSON.
If the optional :option:`infile` and :option:`outfile` arguments are not
specified, :attr:`sys.stdin` and :attr:`sys.stdout` will be used respectively::
$ echo '{"json": "obj"}' | python -m simplejson.tool
{
"json": "obj"
}
$ echo '{1.2:3.4}' | python -m simplejson.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
Command line options
^^^^^^^^^^^^^^^^^^^^
.. cmdoption:: infile
The JSON file to be validated or pretty-printed::
$ python -m simplejson.tool mp_films.json
[
{
"title": "And Now for Something Completely Different",
"year": 1971
},
{
"title": "Monty Python and the Holy Grail",
"year": 1975
}
]
If *infile* is not specified, read from :attr:`sys.stdin`.
.. cmdoption:: outfile
Write the output of the *infile* to the given *outfile*. Otherwise, write it
to :attr:`sys.stdout`.
......@@ -11,7 +11,7 @@
DistutilsPlatformError
IS_PYPY = hasattr(sys, 'pypy_translation_info')
VERSION = '3.6.0'
VERSION = '3.6.1'
DESCRIPTION = "Simple, fast, extensible JSON encoder/decoder for Python"
with open('README.rst', 'r') as f:
......
......@@ -98,7 +98,7 @@
Expecting property name: line 1 column 3 (char 2)
"""
from __future__ import absolute_import
__version__ = '3.6.0'
__version__ = '3.6.1'
__all__ = [
'dump', 'dumps', 'load', 'loads',
'JSONDecoder', 'JSONDecodeError', 'JSONEncoder',
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment