1berry/cpython
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Issue #4945: Improved the documenting of boolean arguments in the json module.

Browse Source 
Based on patch by Gabriel Genellina.
This commit is contained in:
Serhiy Storchaka 2016-06-30 13:59:12 +03:00
parent 0ab67dfb7c
commit 15287f8bcc
2 changed files with 28 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
Doc/library/json.rst
View File

@ -102,7 +102,7 @@ Extending :class:`JSONEncoder`::
.. highlight:: bash .. 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 $ echo '{"json":"obj"}' | python -m json.tool
{ {
@ -135,7 +135,7 @@ Basic Usage
:term:`file-like object`) using this :ref:`conversion table :term:`file-like object`) using this :ref:`conversion table
<py-to-json-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`, of a basic type (:class:`str`, :class:`int`, :class:`float`, :class:`bool`,
``None``) will be skipped instead of raising a :exc:`TypeError`. ``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` :class:`bytes` objects. Therefore, ``fp.write()`` must support :class:`str`
input. 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 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 reference check for container types will be skipped and a circular reference
will result in an :exc:`OverflowError` (or worse). 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``, :exc:`ValueError` to serialize out of range :class:`float` values (``nan``,
``inf``, ``-inf``) in strict compliance of the JSON specification, instead of ``inf``, ``-inf``) in strict compliance of the JSON specification.
using the JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). 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 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 object members will be pretty-printed with that indent level. An indent level
@ -174,10 +175,12 @@ Basic Usage
.. versionchanged:: 3.4 .. versionchanged:: 3.4
Use ``(',', ': ')`` as default if *indent* is not ``None``. Use ``(',', ': ')`` as default if *indent* is not ``None``.
*default(obj)* is a function that should return a serializable version of If specified, *default* should be a function that gets called for objects that
*obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. 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. 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
@ -333,7 +336,7 @@ Encoders and Decoders
``'false'``. This can be used to raise an exception if invalid JSON numbers ``'false'``. This can be used to raise an exception if invalid JSON numbers
are encountered. 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 will be allowed inside strings. Control characters in this context are
those with character codes in the 0-31 range, including ``'\t'`` (tab), those with character codes in the 0-31 range, including ``'\t'`` (tab),
``'\n'``, ``'\r'`` and ``'\0'``. ``'\n'``, ``'\r'`` and ``'\0'``.
@ -393,26 +396,26 @@ Encoders and Decoders
for ``o`` if possible, otherwise it should call the superclass implementation for ``o`` if possible, otherwise it should call the superclass implementation
(to raise :exc:`TypeError`). (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 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 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 encoded objects will be checked for circular references during encoding to
prevent an infinite recursion (which would cause an :exc:`OverflowError`). prevent an infinite recursion (which would cause an :exc:`OverflowError`).
Otherwise, no such check takes place. 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 ``-Infinity`` will be encoded as such. This behavior is not JSON
specification compliant, but is consistent with most JavaScript based specification compliant, but is consistent with most JavaScript based
encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode
such floats. 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 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. JSON serializations can be compared on a day-to-day basis.
@ -434,9 +437,10 @@ Encoders and Decoders
.. versionchanged:: 3.4 .. versionchanged:: 3.4
Use ``(',', ': ')`` as default if *indent* is not ``None``. Use ``(',', ': ')`` as default if *indent* is not ``None``.
If specified, *default* is a function that gets called for objects that can't If specified, *default* should be a function that gets called for objects that
otherwise be serialized. It should return a JSON encodable version of the can't otherwise be serialized. It should return a JSON encodable version of
object or raise a :exc:`TypeError`. the object or raise a :exc:`TypeError`. If not specified, :exc:`TypeError`
is raised.
.. method:: default(o) .. method:: default(o)

4
Lib/json/__init__.py
View File

@ -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 ``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 If *sort_keys* is true (default: ``False``), then the output of
dictionaries will be sorted by key. 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
@ -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 ``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 If *sort_keys* is true (default: ``False``), then the output of
dictionaries will be sorted by key. 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