summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAndrew Svetlov <andrew.svetlov@gmail.com>2012-10-28 12:11:00 (GMT)
committerAndrew Svetlov <andrew.svetlov@gmail.com>2012-10-28 12:11:00 (GMT)
commit6d50a5447af687e2a1303876a3c7867734477762 (patch)
tree2bab21197a6795ed8871af2a5b3710a08554fd2e
parent2a83f16e5e06f3ba27e3cc0d7819a16c40f9a9cb (diff)
parent2ec53be2e272bbe475b2c8173a03dbb29d1413ba (diff)
downloadcpython-6d50a5447af687e2a1303876a3c7867734477762.zip
cpython-6d50a5447af687e2a1303876a3c7867734477762.tar.gz
cpython-6d50a5447af687e2a1303876a3c7867734477762.tar.bz2
Merge issue #14570: Document json sort_keys parameter properly.
Patch by Chris Rebert.
-rw-r--r--Doc/library/json.rst13
-rw-r--r--Lib/json/__init__.py18
2 files changed, 23 insertions, 8 deletions
diff --git a/Doc/library/json.rst b/Doc/library/json.rst
index 95f120c..f9547cb 100644
--- a/Doc/library/json.rst
+++ b/Doc/library/json.rst
@@ -116,7 +116,10 @@ Using json.tool from the shell to validate and pretty-print::
Basic Usage
-----------
-.. function:: dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, **kw)
+.. function:: dump(obj, fp, skipkeys=False, ensure_ascii=True, \
+ check_circular=True, allow_nan=True, cls=None, \
+ indent=None, separators=None, default=None, \
+ sort_keys=False, **kw)
Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
:term:`file-like object`).
@@ -159,12 +162,18 @@ Basic Usage
*default(obj)* is a function that should return a serializable version of
*obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`.
+ If *sort_keys* is ``True`` (default: ``False``), then the output of
+ dictionaries will be sorted by key.
+
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; otherwise :class:`JSONEncoder` is used.
-.. function:: dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, **kw)
+.. function:: dumps(obj, skipkeys=False, ensure_ascii=True, \
+ check_circular=True, allow_nan=True, cls=None, \
+ indent=None, separators=None, default=None, \
+ sort_keys=False, **kw)
Serialize *obj* to a JSON formatted :class:`str`. The arguments have the
same meaning as in :func:`dump`.
diff --git a/Lib/json/__init__.py b/Lib/json/__init__.py
index 725b5cd..86a7a3e 100644
--- a/Lib/json/__init__.py
+++ b/Lib/json/__init__.py
@@ -122,7 +122,7 @@ _default_encoder = JSONEncoder(
def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
allow_nan=True, cls=None, indent=None, separators=None,
- default=None, **kw):
+ default=None, sort_keys=False, **kw):
"""Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
``.write()``-supporting file-like object).
@@ -155,6 +155,9 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
``default(obj)`` is a function that should return a serializable version
of obj or raise TypeError. The default simply raises TypeError.
+ If *sort_keys* is ``True`` (default: ``False``), then the output of
+ dictionaries will be sorted by key.
+
To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
``.default()`` method to serialize additional types), specify it with
the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
@@ -164,7 +167,7 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
if (not skipkeys and ensure_ascii and
check_circular and allow_nan and
cls is None and indent is None and separators is None and
- default is None and not kw):
+ default is None and not sort_keys and not kw):
iterable = _default_encoder.iterencode(obj)
else:
if cls is None:
@@ -172,7 +175,7 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
check_circular=check_circular, allow_nan=allow_nan, indent=indent,
separators=separators,
- default=default, **kw).iterencode(obj)
+ default=default, sort_keys=sort_keys, **kw).iterencode(obj)
# could accelerate with writelines in some versions of Python, at
# a debuggability cost
for chunk in iterable:
@@ -181,7 +184,7 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
allow_nan=True, cls=None, indent=None, separators=None,
- default=None, **kw):
+ default=None, sort_keys=False, **kw):
"""Serialize ``obj`` to a JSON formatted ``str``.
If ``skipkeys`` is false then ``dict`` keys that are not basic types
@@ -213,6 +216,9 @@ def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
``default(obj)`` is a function that should return a serializable version
of obj or raise TypeError. The default simply raises TypeError.
+ If *sort_keys* is ``True`` (default: ``False``), then the output of
+ dictionaries will be sorted by key.
+
To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
``.default()`` method to serialize additional types), specify it with
the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
@@ -222,14 +228,14 @@ def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
if (not skipkeys and ensure_ascii and
check_circular and allow_nan and
cls is None and indent is None and separators is None and
- default is None and not kw):
+ default is None and not sort_keys and not kw):
return _default_encoder.encode(obj)
if cls is None:
cls = JSONEncoder
return cls(
skipkeys=skipkeys, ensure_ascii=ensure_ascii,
check_circular=check_circular, allow_nan=allow_nan, indent=indent,
- separators=separators, default=default,
+ separators=separators, default=default, sort_keys=sort_keys,
**kw).encode(obj)