diff options
author | Nick Babcock <nbabcock19@hotmail.com> | 2015-07-10 17:25:50 -0400 |
---|---|---|
committer | Nick Babcock <nbabcock19@hotmail.com> | 2015-07-10 17:25:50 -0400 |
commit | a9e5e7256c9fb27126813c9430be1dab5f27f7ba (patch) | |
tree | 488eb7357fd5e781395161b7aa6be5aabea6a8ed /index.rst | |
parent | 49724ee06f038d27ab3d4adbe4ed403692799aa1 (diff) | |
parent | 0bcdf20cc525c1343b796cb8f247ea5213c6557e (diff) | |
download | simplejson-a9e5e7256c9fb27126813c9430be1dab5f27f7ba.tar.gz |
Merge branch 'master' into iterable_as_array-gh1
Conflicts:
CHANGES.txt
conf.py
index.rst
setup.py
simplejson/__init__.py
simplejson/_speedups.c
simplejson/encoder.py
simplejson/tests/test_tuple.py
Diffstat (limited to 'index.rst')
-rw-r--r-- | index.rst | 546 |
1 files changed, 465 insertions, 81 deletions
@@ -6,15 +6,19 @@ .. 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:`7159` (which obsoletes :rfc:`4627`) and by +`ECMA-404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm>`_, +is a lightweight data interchange format inspired by +`JavaScript <http://en.wikipedia.org/wiki/JavaScript>`_ object literal syntax +(although it is not a strict subset of JavaScript [#rfc-errata]_ ). :mod:`simplejson` exposes an API familiar to users of the standard library :mod:`marshal` and :mod:`pickle` modules. It is the externally maintained version of the :mod:`json` library contained in Python 2.6, but maintains compatibility with Python 2.5 and (currently) has significant performance advantages, even without using the optional C -extension for speedups. +extension for speedups. :mod:`simplejson` is also supported on Python 3.3+. Development of simplejson happens on Github: http://github.com/simplejson/simplejson @@ -24,15 +28,15 @@ Encoding basic Python object hierarchies:: >>> import simplejson as json >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) '["foo", {"bar": ["baz", null, 1.0, 2]}]' - >>> print json.dumps("\"foo\bar") + >>> print(json.dumps("\"foo\bar")) "\"foo\bar" - >>> print json.dumps(u'\u1234') + >>> print(json.dumps(u'\u1234')) "\u1234" - >>> print json.dumps('\\') + >>> print(json.dumps('\\')) "\\" - >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True) + >>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)) {"a": 0, "b": 0, "c": 0} - >>> from StringIO import StringIO + >>> from simplejson.compat import StringIO >>> io = StringIO() >>> json.dump(['streaming API'], io) >>> io.getvalue() @@ -41,14 +45,14 @@ Encoding basic Python object hierarchies:: Compact encoding:: >>> import simplejson as json - >>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':')) + >>> obj = [1,2,3,{'4': 5, '6': 7}] + >>> json.dumps(obj, separators=(',', ':'), sort_keys=True) '[1,2,3,{"4":5,"6":7}]' Pretty printing:: >>> import simplejson as json - >>> s = json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4 * ' ') - >>> print '\n'.join([l.rstrip() for l in s.splitlines()]) + >>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4 * ' ')) { "4": 5, "6": 7 @@ -62,7 +66,7 @@ Decoding JSON:: True >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar' True - >>> from StringIO import StringIO + >>> from simplejson.compat import StringIO >>> io = StringIO('["streaming API"]') >>> json.load(io)[0] == 'streaming API' True @@ -97,7 +101,7 @@ Specializing JSON object encoding:: >>> def encode_complex(obj): ... if isinstance(obj, complex): ... return [obj.real, obj.imag] - ... raise TypeError(repr(o) + " is not JSON serializable") + ... raise TypeError(repr(obj) + " is not JSON serializable") ... >>> json.dumps(2 + 1j, default=encode_complex) '[2.0, 1.0]' @@ -107,7 +111,7 @@ Specializing JSON object encoding:: '[2.0, 1.0]' -.. highlight:: none +.. highlight:: bash Using :mod:`simplejson.tool` from the shell to validate and pretty-print:: @@ -116,29 +120,42 @@ Using :mod:`simplejson.tool` from the shell to validate and pretty-print:: "json": "obj" } $ echo '{ 1.2:3.4}' | python -m simplejson.tool - Expecting property name: line 1 column 2 (char 2) + Expecting property name enclosed in double quotes: line 1 column 3 (char 2) .. highlight:: python .. 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 ----------- -.. function:: dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, iterable_as_array[, **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, iterable_as_array=False, **kw) 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`. + 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()`` @@ -152,9 +169,10 @@ Basic Usage If *allow_nan* is false (default: ``True``), then it will be a :exc:`ValueError` to serialize out of range :class:`float` values (``nan``, - ``inf``, ``-inf``) in strict compliance of the JSON specification. + ``inf``, ``-inf``) in strict compliance of the original JSON specification. If *allow_nan* is true, their JavaScript equivalents will be used - (``NaN``, ``Infinity``, ``-Infinity``). + (``NaN``, ``Infinity``, ``-Infinity``). See also *ignore_nan* for ECMA-262 + compliant behavior. If *indent* is a string, then JSON array elements and object members will be pretty-printed with a newline followed by that string repeated @@ -166,20 +184,29 @@ Basic Usage .. versionchanged:: 2.1.0 Changed *indent* from an integer number of spaces to a string. - If specified, *separators* should be an ``(item_separator, dict_separator)`` - tuple. By default, ``(', ', ': ')`` are used. To get the most compact JSON - representation, you should specify ``(',', ':')`` to eliminate whitespace. + If specified, *separators* should be an ``(item_separator, key_separator)`` + tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and + ``(',', ': ')`` otherwise. To get the most compact JSON representation, + you should specify ``(',', ':')`` to eliminate whitespace. + + .. versionchanged:: 2.1.4 + Use ``(',', ': ')`` as default if *indent* is not ``None``. *encoding* is the character encoding for str instances, default is ``'utf-8'``. *default(obj)* is a function that should return a serializable version of - *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. + *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the :meth:`default` method to serialize additional types), specify it with the *cls* kwarg. + .. note:: + + Subclassing is not recommended. Use the *default* kwarg + or *for_json* instead. This is faster and more portable. + If *use_decimal* is true (default: ``True``) then :class:`decimal.Decimal` will be natively serialized to JSON with full precision. @@ -189,48 +216,119 @@ Basic Usage .. versionchanged:: 2.2.0 The default of *use_decimal* changed to ``True`` in 2.2.0. - If *namedtuple_as_object* is true (default: ``True``), - :class:`tuple` subclasses with ``_asdict()`` methods will be encoded - as JSON objects. + If *namedtuple_as_object* is true (default: ``True``), + objects with ``_asdict()`` methods will be encoded + as JSON objects. - .. versionchanged:: 2.2.0 - *namedtuple_as_object* is new in 2.2.0. + .. versionchanged:: 2.2.0 + *namedtuple_as_object* is new in 2.2.0. - If *tuple_as_array* is true (default: ``True``), - :class:`tuple` (and subclasses) will be encoded as JSON arrays. + .. versionchanged:: 2.3.0 + *namedtuple_as_object* no longer requires that these objects be + subclasses of :class:`tuple`. - .. versionchanged:: 2.2.0 - *tuple_as_array* is new in 2.2.0. + If *tuple_as_array* is true (default: ``True``), + :class:`tuple` (and subclasses) will be encoded as JSON arrays. If *iterable_as_array* is true (default: ``False``), any object not in the above table that implements ``__iter__()`` will be encoded as a JSON array. - .. versionchanged:: 2.3.0 - *iterable_as_array* is new in 2.3.0. + .. versionchanged:: 3.7.4 + *iterable_as_array* is new in 3.7.4. + .. versionchanged:: 2.2.0 + *tuple_as_array* is new in 2.2.0. - .. note:: + If *bigint_as_string* is true (default: ``False``), :class:`int` ``2**53`` + and higher or lower than ``-2**53`` 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. + See also *int_as_string_bitcount*. + + .. versionchanged:: 2.4.0 + *bigint_as_string* is new in 2.4.0. + + If *sort_keys* is true (not the default), then the output of dictionaries + will be sorted by key; this is useful for regression tests to ensure that + JSON serializations can be compared on a day-to-day basis. + + .. versionchanged:: 3.0.0 + Sorting now happens after the keys have been coerced to + strings, to avoid comparison of heterogeneously typed objects + (since this does not work in Python 3.3+) + + If *item_sort_key* is a callable (not the default), then the output of + dictionaries will be sorted with it. The callable will be used like this: + ``sorted(dct.items(), key=item_sort_key)``. This option takes precedence + over *sort_keys*. + + .. versionchanged:: 2.5.0 + *item_sort_key* is new in 2.5.0. + + .. versionchanged:: 3.0.0 + Sorting now happens after the keys have been coerced to + strings, to avoid comparison of heterogeneously typed objects + (since this does not work in Python 3.3+) + + If *for_json* is true (not the default), objects with a ``for_json()`` + method will use the return value of that method for encoding as JSON instead + of the object. + + .. versionchanged:: 3.2.0 + *for_json* is new in 3.2.0. + + If *ignore_nan* is true (default: ``False``), then out of range + :class:`float` values (``nan``, ``inf``, ``-inf``) will be serialized as + ``null`` in compliance with the ECMA-262 specification. If true, this will + override *allow_nan*. + + .. versionchanged:: 3.2.0 + *ignore_nan* is new in 3.2.0. + + 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. + See also *bigint_as_string* (which is equivalent to `int_as_string_bitcount=53`). + + .. versionchanged:: 3.5.0 + *int_as_string_bitcount* is new in 3.5.0. + + .. note:: JSON is not a framed protocol so unlike :mod:`pickle` or :mod:`marshal` it does not make sense to serialize more than one JSON document without some 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[, iterable_as_array[, **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, iterable_as_array=False, **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 - better performance. + better performance in Python 2. + 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 - 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 @@ -248,7 +346,8 @@ Basic Usage *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 @@ -292,7 +391,12 @@ Basic Usage To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls`` kwarg. Additional keyword arguments will be passed to the constructor of the - class. + class. You probably shouldn't do this. + + .. note:: + + Subclassing is not recommended. You should use *object_hook* or + *object_pairs_hook*. This is faster and more portable than subclassing. .. note:: @@ -303,7 +407,10 @@ Basic Usage 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 @@ -325,31 +432,35 @@ Basic Usage 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: - +---------------+-------------------+ - | 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. @@ -410,24 +521,35 @@ Encoders and decoders :exc:`JSONDecodeError` will be raised if the given JSON document is not valid. - .. method:: raw_decode(s) + .. method:: raw_decode(s[, idx=0]) Decode a JSON document from *s* (a :class:`str` or :class:`unicode` - beginning with a JSON document) and return a 2-tuple of the Python - representation and the index in *s* where the document ended. + beginning with a JSON document) starting from the index *idx* and return + a 2-tuple of the Python representation and the index in *s* where the + document ended. This can be used to decode a JSON document from a string that may have - extraneous data at the end. + extraneous data at the end, or to decode a string that has a series of + JSON objects. :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[, iterable_as_array]]]]]]]]]]]]]) +.. 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, iterable_as_array=False) Extensible JSON encoder for Python data structures. Supports the following objects and types by default: + .. _py-to-json-table: + +-------------------+---------------+ | Python | JSON | +===================+===============+ @@ -446,6 +568,18 @@ Encoders and decoders | None | null | +-------------------+---------------+ + .. note:: The JSON format only permits strings to be used as object + keys, thus any Python dicts to be encoded should only have string keys. + For backwards compatibility, several other types are automatically + coerced to strings: int, long, float, Decimal, bool, and None. + It is error-prone to rely on this behavior, so avoid it when possible. + Dictionaries with other types used as keys should be pre-processed or + wrapped in another type with an appropriate `for_json` method to + transform the keys during encoding. + + 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. @@ -454,29 +588,52 @@ Encoders and decoders for ``o`` if possible, otherwise it should call the superclass implementation (to raise :exc:`TypeError`). + .. note:: + + Subclassing is not recommended. You should use the *default* + or *for_json* kwarg. This is faster and more portable than subclassing. + If *skipkeys* is false (the default), then it is a :exc:`TypeError` to - attempt encoding of keys that are not str, int, long, float or None. If - *skipkeys* is true, such items are simply skipped. + attempt encoding of keys that are not str, int, long, float, Decimal, bool, + or None. If *skipkeys* is true, such items are simply skipped. If *ensure_ascii* is true (the default), the output is guaranteed to be :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. If *allow_nan* is true (the default), then ``NaN``, ``Infinity``, and - ``-Infinity`` will be encoded as such. This behavior is not JSON + ``-Infinity`` will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode - such floats. + such floats. See also *ignore_nan* for ECMA-262 compliant behavior. If *sort_keys* is true (not the default), then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis. + .. versionchanged:: 3.0.0 + Sorting now happens after the keys have been coerced to + strings, to avoid comparison of heterogeneously typed objects + (since this does not work in Python 3.3+) + + If *item_sort_key* is a callable (not the default), then the output of + dictionaries will be sorted with it. The callable will be used like this: + ``sorted(dct.items(), key=item_sort_key)``. This option takes precedence + over *sort_keys*. + + .. versionchanged:: 2.5.0 + *item_sort_key* is new in 2.5.0. + + .. versionchanged:: 3.0.0 + Sorting now happens after the keys have been coerced to + strings, to avoid comparison of heterogeneously typed objects + (since this does not work in Python 3.3+) + If *indent* is a string, then JSON array elements and object members will be pretty-printed with a newline followed by that string repeated for each level of nesting. ``None`` (the default) selects the most compact @@ -488,8 +645,12 @@ Encoders and decoders Changed *indent* from an integer number of spaces to a string. If specified, *separators* should be an ``(item_separator, key_separator)`` - tuple. By default, ``(', ', ': ')`` are used. To get the most compact JSON - representation, you should specify ``(',', ':')`` to eliminate whitespace. + tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and + ``(',', ': ')`` otherwise. To get the most compact JSON representation, + you should specify ``(',', ':')`` to eliminate whitespace. + + .. versionchanged:: 2.1.4 + Use ``(',', ': ')`` as default if *indent* is not ``None``. If specified, *default* should be a function that gets called for objects that can't otherwise be serialized. It should return a JSON encodable @@ -500,12 +661,16 @@ Encoders and decoders ``'utf-8'``. If *namedtuple_as_object* is true (default: ``True``), - :class:`tuple` subclasses with ``_asdict()`` methods will be encoded + objects with ``_asdict()`` methods will be encoded as JSON objects. .. versionchanged:: 2.2.0 *namedtuple_as_object* is new in 2.2.0. + .. versionchanged:: 2.3.0 + *namedtuple_as_object* no longer requires that these objects be + subclasses of :class:`tuple`. + If *tuple_as_array* is true (default: ``True``), :class:`tuple` (and subclasses) will be encoded as JSON arrays. @@ -516,8 +681,31 @@ Encoders and decoders any object not in the above table that implements ``__iter__()`` will be encoded as a JSON array. - .. versionchanged:: 2.3.0 - *iterable_as_array* is new in 2.3.0. + .. versionchanged:: 3.7.4 + *iterable_as_array* is new in 3.7.4. + + If *bigint_as_string* is true (default: ``False``), :class:`int`` ``2**53`` + and higher or lower than ``-2**53`` 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. + + .. versionchanged:: 2.4.0 + *bigint_as_string* is new in 2.4.0. + + If *for_json* is true (default: ``False``), objects with a ``for_json()`` + method will use the return value of that method for encoding as JSON instead + of the object. + + .. versionchanged:: 3.2.0 + *for_json* is new in 3.2.0. + + If *ignore_nan* is true (default: ``False``), then out of range + :class:`float` values (``nan``, ``inf``, ``-inf``) will be serialized as + ``null`` in compliance with the ECMA-262 specification. If true, this will + override *allow_nan*. + + .. versionchanged:: 3.2.0 + *ignore_nan* is new in 3.2.0. .. method:: default(o) @@ -537,6 +725,13 @@ Encoders and decoders return list(iterable) return JSONEncoder.default(self, o) + .. note:: + + Subclassing is not recommended. You should implement this + as a function and pass it to the *default* kwarg of :func:`dumps`. + This is faster and more portable than subclassing. The + semantics are the same, but without the self argument or the + call to the super implementation. .. method:: encode(o) @@ -559,7 +754,16 @@ Encoders and decoders 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]]]]]]]]]) +.. 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. @@ -569,7 +773,7 @@ Encoders and decoders Exceptions ---------- -.. exception:: JSONDecodeError(msg, doc, pos[, end]) +.. exception:: JSONDecodeError(msg, doc, pos, end=None) Subclass of :exc:`ValueError` with the following additional attributes: @@ -604,3 +808,183 @@ Exceptions .. attribute:: endcolno The column corresponding to end (may be ``None``) + + +Standard Compliance and Interoperability +---------------------------------------- + +The JSON format is specified by :rfc:`7159` and by +`ECMA-404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm>`_. +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: + +- 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 recommended default for maximum interoperability. + +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 directly address +the issue of character encodings. + +The RFC prohibits adding a byte order mark (BOM) to the start of a JSON text, +and this module's serializer does not add a BOM to its output. +The RFC permits, but does not require, JSON deserializers to ignore an initial +BOM in their input. This module's deserializer will ignore an initial BOM, if +present. + +.. versionchanged:: 3.6.0 + Older versions would raise :exc:`ValueError` when an initial BOM is present + +The RFC does not explicitly forbid JSON strings which contain byte sequences +that don't correspond to valid Unicode characters (e.g. unpaired UTF-16 +surrogates), but it does note that they may cause interoperability problems. +By default, this module accepts and outputs (when present in the original +:class:`str`) codepoints for such sequences. + +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 mandate 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. + + +Top-level Non-Object, Non-Array Values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The old version of JSON specified by the obsolete :rfc:`4627` required that +the top-level value of a JSON text must be either a JSON object or array +(Python :class:`dict` or :class:`list`), and could not be a JSON null, +boolean, number, or string value. :rfc:`7159` removed that restriction, and +this module does not and has never implemented that restriction in either its +serializer or its deserializer. + +Regardless, for maximum interoperability, you may wish to voluntarily adhere +to the restriction yourself. + + +Implementation Limitations +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some JSON deserializer implementations may set limits on: + +* the size of accepted JSON texts +* the maximum level of nesting of JSON objects and arrays +* the range and precision of JSON numbers +* the content and maximum length of JSON strings + +This module does not impose any such limits beyond those of the relevant +Python datatypes themselves or the Python interpreter itself. + +When serializing to JSON, beware any such limitations in applications that may +consume your JSON. In particular, it is common for JSON numbers to be +deserialized into IEEE 754 double precision numbers and thus subject to that +representation's range and precision limitations. This is especially relevant +when serializing Python :class:`int` values of extremely large magnitude, or +when serializing instances of "exotic" numerical types such as +:class:`decimal.Decimal`. + +.. 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`. + +.. rubric:: Footnotes + +.. [#rfc-errata] As noted in `the errata for RFC 7159 + <http://www.rfc-editor.org/errata_search.php?rfc=7159>`_, + JSON permits literal U+2028 (LINE SEPARATOR) and + U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript + (as of ECMAScript Edition 5.1) does not. |