diff options
| -rw-r--r-- | Doc/library/json.rst | 48 | ||||
| -rw-r--r-- | Lib/json/__init__.py | 4 |
2 files changed, 28 insertions, 24 deletions
diff --git a/Doc/library/json.rst b/Doc/library/json.rst index e8c00e8..73824f8 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -102,7 +102,7 @@ Extending :class:`JSONEncoder`:: .. highlight:: bash -Using json.tool from the shell to validate and pretty-print:: +Using :mod:`json.tool` from the shell to validate and pretty-print:: $ echo '{"json":"obj"}' | python -m json.tool { @@ -135,7 +135,7 @@ Basic Usage :term:`file-like object`) using this :ref:`conversion table <py-to-json-table>`. - If *skipkeys* is ``True`` (default: ``False``), then dict keys that are not + If *skipkeys* is true (default: ``False``), then dict keys that are not of a basic type (:class:`str`, :class:`int`, :class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a :exc:`TypeError`. @@ -143,18 +143,19 @@ Basic Usage :class:`bytes` objects. Therefore, ``fp.write()`` must support :class:`str` input. - If *ensure_ascii* is ``True`` (the default), the output is guaranteed to + If *ensure_ascii* is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped. If *ensure_ascii* is - ``False``, these characters will be output as-is. + false, these characters will be output as-is. - If *check_circular* is ``False`` (default: ``True``), then the circular + 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 + 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 JSON specification, instead of - using the JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). + ``inf``, ``-inf``) in strict compliance of the JSON specification. + If *allow_nan* is true, their JavaScript equivalents (``NaN``, + ``Infinity``, ``-Infinity``) will be used. If *indent* is a non-negative integer or string, then JSON array elements and object members will be pretty-printed with that indent level. An indent level @@ -174,10 +175,12 @@ Basic Usage .. versionchanged:: 3.4 Use ``(',', ': ')`` as default if *indent* is not ``None``. - *default(obj)* is a function that should return a serializable version of - *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. + 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`. If not specified, :exc:`TypeError` + is raised. - If *sort_keys* is ``True`` (default: ``False``), then the output of + 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 @@ -339,7 +342,7 @@ 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 + 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'``. @@ -402,26 +405,26 @@ Encoders and Decoders for ``o`` if possible, otherwise it should call the superclass implementation (to raise :exc:`TypeError`). - If *skipkeys* is ``False`` (the default), then it is a :exc:`TypeError` to + If *skipkeys* is false (the default), then it is a :exc:`TypeError` to attempt encoding of keys that are not str, int, float or None. If - *skipkeys* is ``True``, such items are simply skipped. + *skipkeys* is true, such items are simply skipped. - If *ensure_ascii* is ``True`` (the default), the output is guaranteed to + If *ensure_ascii* is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped. If *ensure_ascii* is - ``False``, these characters will be output as-is. + false, these characters will be output as-is. - If *check_circular* is ``True`` (the default), then lists, dicts, and custom + If *check_circular* is true (the default), then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an :exc:`OverflowError`). Otherwise, no such check takes place. - If *allow_nan* is ``True`` (the default), then ``NaN``, ``Infinity``, and + If *allow_nan* is true (the default), then ``NaN``, ``Infinity``, and ``-Infinity`` will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode such floats. - If *sort_keys* is ``True`` (default ``False``), then the output of dictionaries + If *sort_keys* is true (default: ``False``), 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. @@ -443,9 +446,10 @@ Encoders and Decoders .. versionchanged:: 3.4 Use ``(',', ': ')`` as default if *indent* is not ``None``. - If specified, *default* is 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`. + 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`. If not specified, :exc:`TypeError` + is raised. .. versionchanged:: 3.6 All parameters are now :ref:`keyword-only <keyword-only_parameter>`. diff --git a/Lib/json/__init__.py b/Lib/json/__init__.py index 28057dd..f2c0d23 100644 --- a/Lib/json/__init__.py +++ b/Lib/json/__init__.py @@ -152,7 +152,7 @@ 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 + 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 @@ -214,7 +214,7 @@ 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 + 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 |