diff options
author | Bob Ippolito <bob@redivi.com> | 2019-11-17 18:40:05 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-11-17 18:40:05 -0800 |
commit | 2e0c0e4de3cb50fe3e354c738575cdd75ec09ff3 (patch) | |
tree | a5d854d2a559f416dd4a6e42ff372f81005b5ce1 | |
parent | 2928fff79b09a9a7165ef34abd69fc2ee1ec341a (diff) | |
parent | de2192b371a752638822be5c70b5fac17ac23b4e (diff) | |
download | simplejson-2e0c0e4de3cb50fe3e354c738575cdd75ec09ff3.tar.gz |
Merge pull request #257 from simplejson/python3-doc-updates
Start transitioning docs to be Python 3 centric
-rw-r--r-- | CHANGES.txt | 11 | ||||
-rw-r--r-- | README.rst | 12 | ||||
-rw-r--r-- | conf.py | 4 | ||||
-rw-r--r-- | index.rst | 527 | ||||
-rw-r--r-- | simplejson/__init__.py | 47 |
5 files changed, 261 insertions, 340 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 40083a8..c1caa23 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,3 +1,14 @@ +Version 3.17.0 released 2019-11-17 + +* Updated documentation to be Python 3 first, and + have removed documentation notes about version changes + that occurred more than five years ago. + https://github.com/simplejson/simplejson/pull/257 + https://github.com/simplejson/simplejson/pull/254 +* Update build matrix for Python 3.8 + https://github.com/simplejson/simplejson/pull/255 + https://github.com/simplejson/simplejson/pull/256 + Version 3.16.1 released 2018-09-07 * Added examples for JSON lines use cases @@ -8,16 +8,18 @@ simplejson :target: https://ci.appveyor.com/project/etrepum/simplejson/branch/master simplejson is a simple, fast, complete, correct and extensible -JSON <http://json.org> encoder and decoder for Python 2.5+ -and Python 3.3+. It is pure Python code with no dependencies, -but includes an optional C extension for a serious speed boost. +JSON <http://json.org> encoder and decoder for Python 3.3+ +with legacy support for Python 2.5+. It is pure Python code +with no dependencies, but includes an optional C extension +for a serious speed boost. The latest documentation for simplejson can be read online here: https://simplejson.readthedocs.io/ simplejson is the externally maintained development version of the -json library included with Python 2.6 and Python 3.0, but maintains -backwards compatibility with Python 2.5. +json library included with Python (since 2.6). This version is tested +with the latest Python 3.8 and maintains backwards compatibility +with Python 3.3+ and the legacy Python 2.5 - Python 2.7 releases. The encoder can be specialized to provide serialization in any kind of situation, without any special support by the objects to be serialized @@ -42,9 +42,9 @@ copyright = '2018, Bob Ippolito' # other places throughout the built documents. # # The short X.Y version. -version = '3.16' +version = '3.17' # The full version, including alpha/beta/rc tags. -release = '3.16.1' +release = '3.17.0' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -13,12 +13,16 @@ 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` is a simple, fast, complete, correct and extensible +JSON encoder and decoder for Python. It is pure Python code +with no dependencies, but includes an optional C extension +for a serious speed boost. + :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. :mod:`simplejson` is also supported on Python 3.3+. +version of the :mod:`json` library, but maintains +compatibility with the latest Python 3.8+ releases back to Python 3.3 +as well as the legacy Python 2.5 - Python 2.7 releases. Development of simplejson happens on Github: http://github.com/simplejson/simplejson @@ -61,10 +65,10 @@ Pretty printing:: Decoding JSON:: >>> import simplejson as json - >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}] + >>> obj = ['foo', {'bar': ['baz', None, 1.0, 2]}] >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj True - >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar' + >>> json.loads('"\\"foo\\bar"') == '"foo\x08ar' True >>> from simplejson.compat import StringIO >>> io = StringIO('["streaming API"]') @@ -164,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 <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. + Serialize *obj* as a JSON formatted stream to *fp* + (a ``.write()``-supporting file-like object) using this + :ref:`conversion table <py-to-json-table>`. - 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. + 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 *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). + 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 *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. + .. note:: - 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. + 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.1.0 - Changed *indent* from an integer number of spaces to a string. +.. 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 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. + Serialize *obj* to a JSON formatted :class:`str`. - .. versionchanged:: 2.1.4 - Use ``(',', ': ')`` as default if *indent* is not ``None``. + 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`. - 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 + .. note:: - .. versionchanged:: 3.15.0 - ``encoding=None`` disables serializing :class:`bytes` by default in - Python 3. + When using Python 2, both :class:`str` and :class:`unicode` are + considered to be basic types that represent text. + 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. - *default(obj)* is a function that should return a serializable version of - *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. + .. note:: - 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. + 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. - .. note:: + .. 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. + If *use_decimal* is true (default: ``True``) then :class:`decimal.Decimal` + will be natively serialized to JSON with full precision. - .. versionchanged:: 2.1.0 - *use_decimal* is new in 2.1.0. + If *namedtuple_as_object* is true (default: ``True``), + objects with ``_asdict()`` methods will be encoded + as JSON objects. - .. versionchanged:: 2.2.0 - The default of *use_decimal* changed to ``True`` in 2.2.0. + If *tuple_as_array* is true (default: ``True``), + :class:`tuple` (and subclasses) will be encoded as JSON arrays. - If *namedtuple_as_object* is true (default: ``True``), - objects with ``_asdict()`` methods will be encoded - as JSON objects. + 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.2.0 - *namedtuple_as_object* is new in 2.2.0. + .. versionchanged:: 3.8.0 + *iterable_as_array* is new in 3.8.0. - .. versionchanged:: 2.3.0 - *namedtuple_as_object* no longer requires that these objects be - subclasses of :class:`tuple`. + 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*. - If *tuple_as_array* is true (default: ``True``), - :class:`tuple` (and subclasses) will be encoded as JSON arrays. + 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 *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 *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.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. - .. versionchanged:: 2.2.0 - *tuple_as_array* is new in 2.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*. - 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 *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.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:: + .. 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, \ @@ -359,72 +331,8 @@ Basic Usage :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 - 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 <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 - 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:: @@ -434,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 <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 + 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 --------------------- @@ -513,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 @@ -537,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]) @@ -608,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 @@ -644,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 @@ -669,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`. @@ -698,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. @@ -723,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: @@ -806,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 ---------- @@ -891,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. diff --git a/simplejson/__init__.py b/simplejson/__init__.py index 9d9b737..7b5687c 100644 --- a/simplejson/__init__.py +++ b/simplejson/__init__.py @@ -118,7 +118,7 @@ Serializing multiple objects to JSON lines (newline-delimited JSON):: """ from __future__ import absolute_import -__version__ = '3.16.1' +__version__ = '3.17.0' __all__ = [ 'dump', 'dumps', 'load', 'loads', 'JSONDecoder', 'JSONDecodeError', 'JSONEncoder', @@ -180,18 +180,12 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, ``.write()``-supporting file-like object). If *skipkeys* is true then ``dict`` keys that are not basic types - (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) + (``str``, ``int``, ``long``, ``float``, ``bool``, ``None``) will be skipped instead of raising a ``TypeError``. - If *ensure_ascii* is false, then the some chunks written to ``fp`` - may be ``unicode`` instances, subject to normal Python ``str`` to - ``unicode`` coercion rules. Unless ``fp.write()`` explicitly - understands ``unicode`` (as in ``codecs.getwriter()``) this is likely - to cause an error. - - If *check_circular* is false, then the circular reference check - for container types will be skipped and a circular reference will - result in an ``OverflowError`` (or worse). + 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. If *allow_nan* is false, then it will be a ``ValueError`` to serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) @@ -202,9 +196,7 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, 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. + representation without any newlines. If specified, *separators* should be an ``(item_separator, key_separator)`` tuple. The default is ``(', ', ': ')`` @@ -309,12 +301,12 @@ def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, """Serialize ``obj`` to a JSON formatted ``str``. If ``skipkeys`` is false then ``dict`` keys that are not basic types - (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) + (``str``, ``int``, ``long``, ``float``, ``bool``, ``None``) will be skipped instead of raising a ``TypeError``. - If ``ensure_ascii`` is false, then the return value will be a - ``unicode`` instance subject to normal Python ``str`` to ``unicode`` - coercion rules instead of being escaped to an ASCII ``str``. + 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. If ``check_circular`` is false, then the circular reference check for container types will be skipped and a circular reference will @@ -338,7 +330,8 @@ def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, compact JSON representation, you should specify ``(',', ':')`` to eliminate whitespace. - ``encoding`` is the character encoding for str instances, default is UTF-8. + ``encoding`` is the character encoding for bytes instances, default is + UTF-8. ``default(obj)`` is a function that should return a serializable version of obj or raise TypeError. The default simply raises TypeError. @@ -428,14 +421,11 @@ def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None, use_decimal=False, namedtuple_as_object=True, tuple_as_array=True, **kw): """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing - a JSON document) to a Python object. + a JSON document as `str` or `bytes`) to a Python object. *encoding* determines the encoding used to interpret any - :class:`str` objects decoded by this instance (``'utf-8'`` by - default). It has no effect when decoding :class:`unicode` objects. - - Note that currently only encodings that are a superset of ASCII work, - strings of other encodings should be passed in as :class:`unicode`. + `bytes` objects decoded by this instance (``'utf-8'`` by + default). It has no effect when decoding `str` objects. *object_hook*, if specified, will be called with the result of every JSON object decoded and its return value will be used in place of the @@ -488,11 +478,8 @@ def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, document) to a Python object. *encoding* determines the encoding used to interpret any - :class:`str` objects decoded by this instance (``'utf-8'`` by - default). It has no effect when decoding :class:`unicode` objects. - - Note that currently only encodings that are a superset of ASCII work, - strings of other encodings should be passed in as :class:`unicode`. + :class:`bytes` objects decoded by this instance (``'utf-8'`` by + default). It has no effect when decoding :class:`unicode` objects. *object_hook*, if specified, will be called with the result of every JSON object decoded and its return value will be used in place of the |