From db949b8fae924a852fc68fea9a01fc04fd868758 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 15 Oct 2010 17:04:45 +0000 Subject: [PATCH] Recorded merge of revisions 85543 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r85543 | georg.brandl | 2010-10-15 19:03:02 +0200 (Fr, 15 Okt 2010) | 1 line #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings. ........ --- Doc/library/json.rst | 11 ++++++++--- Lib/json/__init__.py | 24 ++++++++++++++++++++---- Lib/json/decoder.py | 14 ++++++++++++++ 3 files changed, 42 insertions(+), 7 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index f708052869c..bb26f3505c9 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -154,7 +154,7 @@ Basic Usage 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. + *cls* kwarg; otherwise :class:`JSONEncoder` is used. .. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]]) @@ -209,8 +209,8 @@ Basic Usage are encountered. 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. + kwarg; otherwise :class:`JSONDecoder` is used. Additional keyword arguments + will be passed to the constructor of the class. .. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]]) @@ -296,6 +296,11 @@ Encoders and decoders ``'false'``. This can be used to raise an exception if invalid JSON numbers are encountered. + If *strict* is ``False`` (``True`` is the default), then control characters + will be allowed inside strings. Control characters in this context are + those with character codes in the 0-31 range, including ``'\t'`` (tab), + ``'\n'``, ``'\r'`` and ``'\0'``. + .. method:: decode(s) diff --git a/Lib/json/__init__.py b/Lib/json/__init__.py index ba584a35241..414c702629c 100644 --- a/Lib/json/__init__.py +++ b/Lib/json/__init__.py @@ -160,7 +160,7 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the ``.default()`` method to serialize additional types), specify it with - the ``cls`` kwarg. + the ``cls`` kwarg; otherwise ``JSONEncoder`` is used. """ # cached encoder @@ -220,7 +220,7 @@ def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the ``.default()`` method to serialize additional types), specify it with - the ``cls`` kwarg. + the ``cls`` kwarg; otherwise ``JSONEncoder`` is used. """ # cached encoder @@ -259,8 +259,16 @@ def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None, ``object_hook`` will be used instead of the ``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 decoded with an ordered list of pairs. The + return value of ``object_pairs_hook`` will be used instead of the ``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, + collections.OrderedDict will remember the order of insertion). If + ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority. + To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` - kwarg. + kwarg; otherwise ``JSONDecoder`` is used. """ return loads(fp.read(), @@ -285,6 +293,14 @@ def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, ``object_hook`` will be used instead of the ``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 decoded with an ordered list of pairs. The + return value of ``object_pairs_hook`` will be used instead of the ``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, + 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 @@ -301,7 +317,7 @@ def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, are encountered. To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` - kwarg. + kwarg; otherwise ``JSONDecoder`` is used. """ if (cls is None and encoding is None and object_hook is None and diff --git a/Lib/json/decoder.py b/Lib/json/decoder.py index 73236ed4de9..b9745f78844 100644 --- a/Lib/json/decoder.py +++ b/Lib/json/decoder.py @@ -310,6 +310,15 @@ class JSONDecoder(object): place of the given ``dict``. This can be used to provide custom deserializations (e.g. to support JSON-RPC class hinting). + ``object_pairs_hook``, if specified will be called with the result of + every JSON object decoded with an ordered list of pairs. The return + value of ``object_pairs_hook`` will be used instead of the ``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, + 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 @@ -325,6 +334,11 @@ class JSONDecoder(object): This can be used to raise an exception if invalid JSON numbers are encountered. + If ``strict`` is false (true is the default), then control + characters will be allowed inside strings. Control characters in + this context are those with character codes in the 0-31 range, + including ``'\\t'`` (tab), ``'\\n'``, ``'\\r'`` and ``'\\0'``. + """ self.encoding = encoding self.object_hook = object_hook