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.
........
diff --git a/Doc/library/json.rst b/Doc/library/json.rst
index f708052..bb26f35 100644
--- a/Doc/library/json.rst
+++ b/Doc/library/json.rst
@@ -154,7 +154,7 @@
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 @@
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 @@
``'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 ba584a3..414c702 100644
--- a/Lib/json/__init__.py
+++ b/Lib/json/__init__.py
@@ -160,7 +160,7 @@
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 @@
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 @@
``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 @@
``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 @@
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 73236ed..b9745f7 100644
--- a/Lib/json/decoder.py
+++ b/Lib/json/decoder.py
@@ -310,6 +310,15 @@
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 @@
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