mirror of https://github.com/python/cpython
Issue #14570: Document json sort_keys parameter properly.
Patch by Chris Rebert.
This commit is contained in:
parent
f4712d4a82
commit
41c25ba451
|
@ -117,7 +117,10 @@ Using json.tool from the shell to validate and pretty-print::
|
||||||
Basic Usage
|
Basic Usage
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
.. function:: dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])
|
.. function:: dump(obj, fp, skipkeys=False, ensure_ascii=True, \
|
||||||
|
check_circular=True, allow_nan=True, cls=None, \
|
||||||
|
indent=None, separators=None, encoding="utf-8", \
|
||||||
|
default=None, sort_keys=False, **kw)
|
||||||
|
|
||||||
Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
|
Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
|
||||||
:term:`file-like object`).
|
:term:`file-like object`).
|
||||||
|
@ -159,6 +162,9 @@ Basic Usage
|
||||||
*default(obj)* is a function that should return a serializable version of
|
*default(obj)* is a function that should return a serializable version of
|
||||||
*obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`.
|
*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
|
To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
|
||||||
:meth:`default` method to serialize additional types), specify it with the
|
:meth:`default` method to serialize additional types), specify it with the
|
||||||
*cls* kwarg; otherwise :class:`JSONEncoder` is used.
|
*cls* kwarg; otherwise :class:`JSONEncoder` is used.
|
||||||
|
@ -169,7 +175,10 @@ Basic Usage
|
||||||
trying to serialize more objects with repeated calls to :func:`dump` and
|
trying to serialize more objects with repeated calls to :func:`dump` and
|
||||||
the same *fp* will result in an invalid JSON file.
|
the same *fp* will result in an invalid JSON file.
|
||||||
|
|
||||||
.. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])
|
.. 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, sort_keys=False, **kw)
|
||||||
|
|
||||||
Serialize *obj* to a JSON formatted :class:`str`. If *ensure_ascii* is
|
Serialize *obj* to a JSON formatted :class:`str`. If *ensure_ascii* is
|
||||||
``False``, the result may contain non-ASCII characters and the return value
|
``False``, the result may contain non-ASCII characters and the return value
|
||||||
|
|
|
@ -121,7 +121,7 @@ _default_encoder = JSONEncoder(
|
||||||
|
|
||||||
def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
|
def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
|
||||||
allow_nan=True, cls=None, indent=None, separators=None,
|
allow_nan=True, cls=None, indent=None, separators=None,
|
||||||
encoding='utf-8', default=None, **kw):
|
encoding='utf-8', default=None, sort_keys=False, **kw):
|
||||||
"""Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
|
"""Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
|
||||||
``.write()``-supporting file-like object).
|
``.write()``-supporting file-like object).
|
||||||
|
|
||||||
|
@ -161,6 +161,9 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
|
||||||
``default(obj)`` is a function that should return a serializable version
|
``default(obj)`` is a function that should return a serializable version
|
||||||
of obj or raise TypeError. The default simply raises TypeError.
|
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
|
To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
|
||||||
``.default()`` method to serialize additional types), specify it with
|
``.default()`` method to serialize additional types), specify it with
|
||||||
the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
|
the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
|
||||||
|
@ -170,7 +173,7 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
|
||||||
if (not skipkeys and ensure_ascii and
|
if (not skipkeys and ensure_ascii and
|
||||||
check_circular and allow_nan and
|
check_circular and allow_nan and
|
||||||
cls is None and indent is None and separators is None and
|
cls is None and indent is None and separators is None and
|
||||||
encoding == 'utf-8' and default is None and not kw):
|
encoding == 'utf-8' and default is None and not sort_keys and not kw):
|
||||||
iterable = _default_encoder.iterencode(obj)
|
iterable = _default_encoder.iterencode(obj)
|
||||||
else:
|
else:
|
||||||
if cls is None:
|
if cls is None:
|
||||||
|
@ -178,7 +181,7 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
|
||||||
iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
|
iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
|
||||||
check_circular=check_circular, allow_nan=allow_nan, indent=indent,
|
check_circular=check_circular, allow_nan=allow_nan, indent=indent,
|
||||||
separators=separators, encoding=encoding,
|
separators=separators, encoding=encoding,
|
||||||
default=default, **kw).iterencode(obj)
|
default=default, sort_keys=sort_keys, **kw).iterencode(obj)
|
||||||
# could accelerate with writelines in some versions of Python, at
|
# could accelerate with writelines in some versions of Python, at
|
||||||
# a debuggability cost
|
# a debuggability cost
|
||||||
for chunk in iterable:
|
for chunk in iterable:
|
||||||
|
@ -187,7 +190,7 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
|
||||||
|
|
||||||
def dumps(obj, 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,
|
allow_nan=True, cls=None, indent=None, separators=None,
|
||||||
encoding='utf-8', default=None, **kw):
|
encoding='utf-8', default=None, sort_keys=False, **kw):
|
||||||
"""Serialize ``obj`` to a JSON formatted ``str``.
|
"""Serialize ``obj`` to a JSON formatted ``str``.
|
||||||
|
|
||||||
If ``skipkeys`` is false then ``dict`` keys that are not basic types
|
If ``skipkeys`` is false then ``dict`` keys that are not basic types
|
||||||
|
@ -220,6 +223,9 @@ def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
|
||||||
``default(obj)`` is a function that should return a serializable version
|
``default(obj)`` is a function that should return a serializable version
|
||||||
of obj or raise TypeError. The default simply raises TypeError.
|
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
|
To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
|
||||||
``.default()`` method to serialize additional types), specify it with
|
``.default()`` method to serialize additional types), specify it with
|
||||||
the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
|
the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
|
||||||
|
@ -229,7 +235,7 @@ def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
|
||||||
if (not skipkeys and ensure_ascii and
|
if (not skipkeys and ensure_ascii and
|
||||||
check_circular and allow_nan and
|
check_circular and allow_nan and
|
||||||
cls is None and indent is None and separators is None and
|
cls is None and indent is None and separators is None and
|
||||||
encoding == 'utf-8' and default is None and not kw):
|
encoding == 'utf-8' and default is None and not sort_keys and not kw):
|
||||||
return _default_encoder.encode(obj)
|
return _default_encoder.encode(obj)
|
||||||
if cls is None:
|
if cls is None:
|
||||||
cls = JSONEncoder
|
cls = JSONEncoder
|
||||||
|
@ -237,7 +243,7 @@ def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
|
||||||
skipkeys=skipkeys, ensure_ascii=ensure_ascii,
|
skipkeys=skipkeys, ensure_ascii=ensure_ascii,
|
||||||
check_circular=check_circular, allow_nan=allow_nan, indent=indent,
|
check_circular=check_circular, allow_nan=allow_nan, indent=indent,
|
||||||
separators=separators, encoding=encoding, default=default,
|
separators=separators, encoding=encoding, default=default,
|
||||||
**kw).encode(obj)
|
sort_keys=sort_keys, **kw).encode(obj)
|
||||||
|
|
||||||
|
|
||||||
_default_decoder = JSONDecoder(encoding=None, object_hook=None,
|
_default_decoder = JSONDecoder(encoding=None, object_hook=None,
|
||||||
|
|
Loading…
Reference in New Issue