From de2192b371a752638822be5c70b5fac17ac23b4e Mon Sep 17 00:00:00 2001 From: Bob Ippolito Date: Sun, 17 Nov 2019 18:22:29 -0800 Subject: Finish updating docs to be Python 3-centric --- index.rst | 515 ++++++++++++++++++++++++++------------------------------------ 1 file changed, 216 insertions(+), 299 deletions(-) (limited to 'index.rst') diff --git a/index.rst b/index.rst index 66596a4..fbb52b5 100644 --- a/index.rst +++ b/index.rst @@ -168,191 +168,159 @@ Basic Usage 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) using this :ref:`conversion 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()`` - explicitly understands :class:`unicode` (as in :func:`codecs.getwriter`) this - is likely to cause an error. It's best to leave the default settings, because - they are safe and it is highly optimized. - - If *check_circular* is false (default: ``True``), then the circular - reference check for container types will be skipped and a circular reference - will result in an :exc:`OverflowError` (or worse). - - 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 original JSON specification. - If *allow_nan* is true, their JavaScript equivalents will be used - (``NaN``, ``Infinity``, ``-Infinity``). See also *ignore_nan* for ECMA-262 - compliant behavior. + Serialize *obj* as a JSON formatted stream to *fp* + (a ``.write()``-supporting file-like object) using this + :ref:`conversion table `. - 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 - representation without any newlines. For backwards compatibility with - versions of simplejson earlier than 2.1.0, an integer is also accepted - and is converted to a string with that many spaces. + The :mod:`simplejson` module will produce :class:`str` objects in + Python 3, not :class:`bytes` objects. Therefore, ``fp.write()`` must + support :class:`str` input. - .. versionchanged:: 2.1.0 - Changed *indent* from an integer number of spaces to a string. + See :func:`dumps` for a description of each argument. The only difference + is that this function writes the resulting JSON document to *fp* instead + of returning it. - 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``. - - If *encoding* is not ``None``, then all input :class:`bytes` objects in - Python 3 and 8-bit strings in Python 2 will be transformed - into unicode using that encoding prior to JSON-encoding. The default is - ``'utf-8'``. If *encoding* is ``None``, then all :class:`bytes` objects - will be passed to the *default* function in Python 3 - - .. versionchanged:: 3.15.0 - ``encoding=None`` disables serializing :class:`bytes` by default in - Python 3. - - - *default(obj)* is a function that should return a serializable version of - *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. + .. note:: - .. versionchanged:: 2.1.0 - *use_decimal* is new in 2.1.0. + When using Python 2, if *ensure_ascii* is set to false, + some chunks written to *fp* may be :class:`unicode` instances, subject + to normal Python :class:`str` to :class:`unicode` coercion rules. + Unless ``fp.write()`` explicitly understands :class:`unicode` + (as in :func:`codecs.getwriter`) this is likely to cause an error. + It's best to leave the default settings, because they are safe and it + is highly optimized. - .. versionchanged:: 2.2.0 - The default of *use_decimal* changed to ``True`` in 2.2.0. +.. 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) - If *namedtuple_as_object* is true (default: ``True``), - objects with ``_asdict()`` methods will be encoded - as JSON objects. + Serialize *obj* to a JSON formatted :class:`str`. - .. versionchanged:: 2.2.0 - *namedtuple_as_object* is new in 2.2.0. + If *skipkeys* is true (default: ``False``), then dict keys that are not + of a basic type (:class:`str`, :class:`int`, :class:`long`, + :class:`float`, :class:`bool`, ``None``) will be skipped instead of + raising a :exc:`TypeError`. - .. versionchanged:: 2.3.0 - *namedtuple_as_object* no longer requires that these objects be - subclasses of :class:`tuple`. + .. note:: - If *tuple_as_array* is true (default: ``True``), - :class:`tuple` (and subclasses) will be encoded as JSON arrays. + When using Python 2, both :class:`str` and :class:`unicode` are + considered to be basic types that represent text. - 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. + If *ensure_ascii* is false (default: ``True``), then the output may + contain non-ASCII characters, so long as they do not need to be escaped + by JSON. When it is true, all non-ASCII characters are escaped. - .. versionchanged:: 3.8.0 - *iterable_as_array* is new in 3.8.0. + .. note:: - .. versionchanged:: 2.2.0 - *tuple_as_array* is new in 2.2.0. + When using Python 2, if *ensure_ascii* is set to false, + the result may be a :class:`unicode` object. By default, as a memory + optimization, the result would be a :class:`str` object. + + If *check_circular* is false (default: ``True``), then the circular + reference check for container types will be skipped and a circular + reference will result in an :exc:`OverflowError` (or worse). + + 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 original + JSON specification. If *allow_nan* is true, their JavaScript equivalents + will be used (``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 + for each level of nesting. ``None`` (the default) selects the most compact + representation without any newlines. For backwards compatibility with + versions of simplejson earlier than 2.1.0, an integer is also accepted + and is converted to a string with that many spaces. + + 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. + + If *encoding* is not ``None``, then all input :class:`bytes` objects in + Python 3 and 8-bit strings in Python 2 will be transformed + into unicode using that encoding prior to JSON-encoding. The default is + ``'utf-8'``. If *encoding* is ``None``, then all :class:`bytes` objects + will be passed to the *default* function in Python 3 + + .. versionchanged:: 3.15.0 + ``encoding=None`` disables serializing :class:`bytes` by default in + Python 3. + + *default(obj)* is a function that should return a serializable version of + *obj* or raise :exc:`TypeError`. The default implementation always 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. - 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*. + .. note:: - .. versionchanged:: 2.4.0 - *bigint_as_string* is new in 2.4.0. + Subclassing is not recommended. Use the *default* kwarg + or *for_json* instead. This is faster and more portable. - 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. + If *use_decimal* is true (default: ``True``) then :class:`decimal.Decimal` + will be natively serialized to JSON with full precision. - .. 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 *namedtuple_as_object* is true (default: ``True``), + objects with ``_asdict()`` methods will be encoded + as JSON objects. - 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*. + If *tuple_as_array* is true (default: ``True``), + :class:`tuple` (and subclasses) will be encoded as JSON arrays. - .. versionchanged:: 2.5.0 - *item_sort_key* is new in 2.5.0. + 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:: 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+) + .. versionchanged:: 3.8.0 + *iterable_as_array* is new in 3.8.0. - 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. + 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:: 3.2.0 - *for_json* is new in 3.2.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. - 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*. + 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:: 3.2.0 - *ignore_nan* is new in 3.2.0. + 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. - 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`). + 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.5.0 - *int_as_string_bitcount* is new in 3.5.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`). - .. note:: + .. 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=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 in Python 2. - - The other options have the same meaning as in :func:`dump`. - - .. function:: load(fp, encoding='utf-8', cls=None, object_hook=None, \ parse_float=None, parse_int=None, \ parse_constant=None, object_pairs_hook=None, \ @@ -363,72 +331,8 @@ Basic Usage :ref:`conversion 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 - UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be specified. - Encodings that are not ASCII based (such as UCS-2) are not allowed, and - should be wrapped with ``codecs.getreader(fp)(encoding)``, or simply decoded - to a :class:`unicode` object and passed to :func:`loads`. The default - setting of ``'utf-8'`` is fastest and should be using whenever possible. - - If *fp.read()* returns :class:`str` then decoded JSON strings that contain - only ASCII characters may be parsed as :class:`str` for performance and - memory reasons. If your code expects only :class:`unicode` the appropriate - solution is to wrap fp with a reader as demonstrated above. - - *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). - - *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 - return value of *object_pairs_hook* will be used instead of the - :class:`dict`. This feature can be used to implement custom decoders that - rely on the order that the key and value pairs are decoded (for example, - :class:`collections.OrderedDict` will remember the order of insertion). If - *object_hook* is also defined, the *object_pairs_hook* takes priority. - - .. versionchanged:: 2.1.0 - Added support for *object_pairs_hook*. - - *parse_float*, if specified, will be called with the string of every JSON - float to be decoded. By default, this is equivalent to ``float(num_str)``. - This can be used to use another datatype or parser for JSON floats - (e.g. :class:`decimal.Decimal`). - - *parse_int*, if specified, will be called with the string of every JSON int - to be decoded. By default, this is equivalent to ``int(num_str)``. This can - be used to use another datatype or parser for JSON integers - (e.g. :class:`float`). - - *parse_constant*, if specified, will be called with one of the following - strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This can be used to - raise an exception if invalid JSON numbers are encountered. - - If *use_decimal* is true (default: ``False``) then *parse_float* is set to - :class:`decimal.Decimal`. This is a convenience for parity with the - :func:`dump` parameter. - - .. versionchanged:: 2.1.0 - *use_decimal* is new in 2.1.0. - - 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:: 3.8.0 - *iterable_as_array* is new in 3.8.0. - - - 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. 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. + If *fp.read()* returns :class:`bytes`, such as a file opened in binary mode, + then an appropriate *encoding* should be specified (the default is UTF-8). .. note:: @@ -438,28 +342,99 @@ Basic Usage other than whitespace after the document. Except for files containing only one JSON document, it is recommended to use :func:`loads`. + .. note:: + + In Python 2, :class:`str` is considered to be :class:`bytes` and this + is the default behavior of all :class:`file` objects. If the contents + of *fp* are encoded with an ASCII based encoding other than UTF-8 + (e.g. latin-1), then an appropriate *encoding* name must be specified. + Encodings that are not ASCII based (such as UCS-2) are not allowed, + and should be wrapped with ``codecs.getreader(fp)(encoding)``, or + decoded to a :class:`unicode` object and passed to :func:`loads`. + The default setting of ``'utf-8'`` is fastest and should be using + whenever possible. + + If *fp.read()* returns :class:`str` then decoded JSON strings that + contain only ASCII characters may be parsed as :class:`str` for + performance and memory reasons. If your code expects only + :class:`unicode` the appropriate solution is to wrap fp with a + reader as demonstrated above. + + See :func:`loads` for a description of each argument. The only difference + is that this function reads the JSON document from a file-like object *fp* + instead of a :class:`str` or :class:`bytes`. .. function:: loads(s, 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 - raised if the given JSON document is not valid. + Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON + document) to a Python object. :exc:`JSONDecodeError` will be + raised if the given JSON document is not valid. - If *s* is a :class:`str` instance and is encoded with an ASCII based encoding - other than UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be - specified. Encodings that are not ASCII based (such as UCS-2) are not - allowed and should be decoded to :class:`unicode` first. + .. note:: - If *s* is a :class:`str` then decoded JSON strings that contain - only ASCII characters may be parsed as :class:`str` for performance and - memory reasons. If your code expects only :class:`unicode` the appropriate - solution is decode *s* to :class:`unicode` prior to calling loads. + In Python 2, :class:`str` is considered to be :class:`bytes` as above, + if your JSON is using an encoding that is not ASCII based, then you must + decode to :class:`unicode` first. + + If *s* is a :class:`str` instance and is encoded with an ASCII based encoding + other than UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be + specified. Encodings that are not ASCII based (such as UCS-2) are not + allowed and should be decoded to :class:`unicode` first. Additionally, + decoded JSON strings that contain only ASCII characters may be parsed as + :class:`str` instead of :class:`unicode` for performance and memory + reasons. If your code expects only :class:`unicode` the appropriate + solution is decode *s* to :class:`unicode` prior to calling :func:`loads`. + + *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). + + *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 + return value of *object_pairs_hook* will be used instead of the + :class:`dict`. This feature can be used to implement custom decoders that + rely on the order that the key and value pairs are decoded (for example, + :class:`collections.OrderedDict` will remember the order of insertion). If + *object_hook* is also defined, the *object_pairs_hook* takes priority. + + *parse_float*, if specified, will be called with the string of every JSON + float to be decoded. By default, this is equivalent to ``float(num_str)``. + This can be used to use another datatype or parser for JSON floats + (e.g. :class:`decimal.Decimal`). + + *parse_int*, if specified, will be called with the string of every JSON int + to be decoded. By default, this is equivalent to ``int(num_str)``. This can + be used to use another datatype or parser for JSON integers + (e.g. :class:`float`). + + *parse_constant*, if specified, will be called with one of the following + strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This can be used to + raise an exception if invalid JSON numbers are encountered. + + If *use_decimal* is true (default: ``False``) then *parse_float* is set to + :class:`decimal.Decimal`. This is a convenience for parity with the + :func:`dump` parameter. + + 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:: 3.8.0 + *iterable_as_array* is new in 3.8.0. + + 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. You probably shouldn't do this. - The other arguments have the same meaning as in :func:`load`. + .. note:: + Subclassing is not recommended. You should use *object_hook* or + *object_pairs_hook*. This is faster and more portable than subclassing. Encoders and decoders --------------------- @@ -517,9 +492,6 @@ Encoders and decoders :class:`collections.OrderedDict` will remember the order of insertion). If *object_hook* is also defined, the *object_pairs_hook* takes priority. - .. versionchanged:: 2.1.0 - Added support for *object_pairs_hook*. - *parse_float*, if specified, will be called with the string of every JSON float to be decoded. By default, this is equivalent to ``float(num_str)``. This can be used to use another datatype or parser for JSON floats @@ -541,17 +513,9 @@ Encoders and decoders .. method:: decode(s) - Return the Python representation of *s* (a :class:`str` or - :class:`unicode` instance containing a JSON document) - - If *s* is a :class:`str` then decoded JSON strings that contain - only ASCII characters may be parsed as :class:`str` for performance and - memory reasons. If your code expects only :class:`unicode` the - appropriate solution is decode *s* to :class:`unicode` prior to calling - decode. - - :exc:`JSONDecodeError` will be raised if the given JSON - document is not valid. + Return the Python representation of the JSON document *s*. See + :func:`loads` for details. It is preferable to use that rather + than this class. .. method:: raw_decode(s[, idx=0]) @@ -612,9 +576,6 @@ Encoders and decoders 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. - To extend this to recognize other objects, subclass and implement a :meth:`default` method with another method that returns a serializable object for ``o`` if possible, otherwise it should call the superclass implementation @@ -648,24 +609,11 @@ Encoders and decoders 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 @@ -673,17 +621,11 @@ Encoders and decoders versions of simplejson earlier than 2.1.0, an integer is also accepted and is converted to a string with that many spaces. - .. versionchanged:: 2.1.0 - Changed *indent* from an integer number of spaces to a string. - 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``. - If specified, *default* should be a function that gets called for objects that can't otherwise be serialized. It should return a JSON encodable version of the object or raise a :exc:`TypeError`. @@ -702,19 +644,9 @@ Encoders and decoders 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. - .. versionchanged:: 2.2.0 - *tuple_as_array* is new in 2.2.0. - 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. @@ -727,34 +659,25 @@ Encoders and decoders 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) - Implement this method in a subclass such that it returns a serializable - object for *o*, or calls the base implementation (to raise a - :exc:`TypeError`). + Implement this method in a subclass such that it returns a serializable + object for *o*, or calls the base implementation (to raise a + :exc:`TypeError`). - For example, to support arbitrary iterators, you could implement default - like this:: + For example, to support arbitrary iterators, you could implement default + like this:: - def default(self, o): + def default(self, o): try: iterable = iter(o) except TypeError: @@ -810,9 +733,6 @@ Encoders and decoders as these characters are not valid in JavaScript strings (see http://timelessrepo.com/json-isnt-a-javascript-subset). - .. versionchanged:: 2.1.0 - New in 2.1.0 - Exceptions ---------- @@ -895,9 +815,6 @@ 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. -- cgit v1.2.1