Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 15287f8

Browse files
serhiy-storchakaserhiy-storchaka
committed
Issue #4945: Improved the documenting of boolean arguments in the json module.
Based on patch by Gabriel Genellina.
1 parent 0ab67df commit 15287f8

2 files changed

Lines changed: 28 additions & 24 deletions

File tree

‎Doc/library/json.rst‎

Lines changed: 26 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ Extending :class:`JSONEncoder`::
102102

103103
.. highlight:: bash
104104

105-
Using json.tool from the shell to validate and pretty-print::
105+
Using :mod:`json.tool` from the shell to validate and pretty-print::
106106

107107
$ echo '{"json":"obj"}' | python -m json.tool
108108
{
@@ -135,26 +135,27 @@ Basic Usage
135135
:term:`file-like object`) using this :ref:`conversion table
136136
<py-to-json-table>`.
137137

138-
If *skipkeys* is ``True`` (default: ``False``), then dict keys that are not
138+
If *skipkeys* is true (default: ``False``), then dict keys that are not
139139
of a basic type (:class:`str`, :class:`int`, :class:`float`, :class:`bool`,
140140
``None``) will be skipped instead of raising a :exc:`TypeError`.
141141

142142
The :mod:`json` module always produces :class:`str` objects, not
143143
:class:`bytes` objects. Therefore, ``fp.write()`` must support :class:`str`
144144
input.
145145

146-
If *ensure_ascii* is ``True`` (the default), the output is guaranteed to
146+
If *ensure_ascii* is true (the default), the output is guaranteed to
147147
have all incoming non-ASCII characters escaped. If *ensure_ascii* is
148-
``False``, these characters will be output as-is.
148+
false, these characters will be output as-is.
149149

150-
If *check_circular* is ``False`` (default: ``True``), then the circular
150+
If *check_circular* is false (default: ``True``), then the circular
151151
reference check for container types will be skipped and a circular reference
152152
will result in an :exc:`OverflowError` (or worse).
153153

154-
If *allow_nan* is ``False`` (default: ``True``), then it will be a
154+
If *allow_nan* is false (default: ``True``), then it will be a
155155
:exc:`ValueError` to serialize out of range :class:`float` values (``nan``,
156-
``inf``, ``-inf``) in strict compliance of the JSON specification, instead of
157-
using the JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
156+
``inf``, ``-inf``) in strict compliance of the JSON specification.
157+
If *allow_nan* is true, their JavaScript equivalents (``NaN``,
158+
``Infinity``, ``-Infinity``) will be used.
158159

159160
If *indent* is a non-negative integer or string, then JSON array elements and
160161
object members will be pretty-printed with that indent level. An indent level
@@ -174,10 +175,12 @@ Basic Usage
174175
.. versionchanged:: 3.4
175176
Use ``(',', ': ')`` as default if *indent* is not ``None``.
176177

177-
*default(obj)* is a function that should return a serializable version of
178-
*obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`.
178+
If specified, *default* should be a function that gets called for objects that
179+
can't otherwise be serialized. It should return a JSON encodable version of
180+
the object or raise a :exc:`TypeError`. If not specified, :exc:`TypeError`
181+
is raised.
179182

180-
If *sort_keys* is ``True`` (default: ``False``), then the output of
183+
If *sort_keys* is true (default: ``False``), then the output of
181184
dictionaries will be sorted by key.
182185

183186
To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
@@ -333,7 +336,7 @@ Encoders and Decoders
333336
``'false'``. This can be used to raise an exception if invalid JSON numbers
334337
are encountered.
335338

336-
If *strict* is ``False`` (``True`` is the default), then control characters
339+
If *strict* is false (``True`` is the default), then control characters
337340
will be allowed inside strings. Control characters in this context are
338341
those with character codes in the 0-31 range, including ``'\t'`` (tab),
339342
``'\n'``, ``'\r'`` and ``'\0'``.
@@ -393,26 +396,26 @@ Encoders and Decoders
393396
for ``o`` if possible, otherwise it should call the superclass implementation
394397
(to raise :exc:`TypeError`).
395398

396-
If *skipkeys* is ``False`` (the default), then it is a :exc:`TypeError` to
399+
If *skipkeys* is false (the default), then it is a :exc:`TypeError` to
397400
attempt encoding of keys that are not str, int, float or None. If
398-
*skipkeys* is ``True``, such items are simply skipped.
401+
*skipkeys* is true, such items are simply skipped.
399402

400-
If *ensure_ascii* is ``True`` (the default), the output is guaranteed to
403+
If *ensure_ascii* is true (the default), the output is guaranteed to
401404
have all incoming non-ASCII characters escaped. If *ensure_ascii* is
402-
``False``, these characters will be output as-is.
405+
false, these characters will be output as-is.
403406

404-
If *check_circular* is ``True`` (the default), then lists, dicts, and custom
407+
If *check_circular* is true (the default), then lists, dicts, and custom
405408
encoded objects will be checked for circular references during encoding to
406409
prevent an infinite recursion (which would cause an :exc:`OverflowError`).
407410
Otherwise, no such check takes place.
408411

409-
If *allow_nan* is ``True`` (the default), then ``NaN``, ``Infinity``, and
412+
If *allow_nan* is true (the default), then ``NaN``, ``Infinity``, and
410413
``-Infinity`` will be encoded as such. This behavior is not JSON
411414
specification compliant, but is consistent with most JavaScript based
412415
encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode
413416
such floats.
414417

415-
If *sort_keys* is ``True`` (default ``False``), then the output of dictionaries
418+
If *sort_keys* is true (default: ``False``), then the output of dictionaries
416419
will be sorted by key; this is useful for regression tests to ensure that
417420
JSON serializations can be compared on a day-to-day basis.
418421

@@ -434,9 +437,10 @@ Encoders and Decoders
434437
.. versionchanged:: 3.4
435438
Use ``(',', ': ')`` as default if *indent* is not ``None``.
436439

437-
If specified, *default* is a function that gets called for objects that can't
438-
otherwise be serialized. It should return a JSON encodable version of the
439-
object or raise a :exc:`TypeError`.
440+
If specified, *default* should be a function that gets called for objects that
441+
can't otherwise be serialized. It should return a JSON encodable version of
442+
the object or raise a :exc:`TypeError`. If not specified, :exc:`TypeError`
443+
is raised.
440444

441445

442446
.. method:: default(o)

‎Lib/json/__init__.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
152152
``default(obj)`` is a function that should return a serializable version
153153
of obj or raise TypeError. The default simply raises TypeError.
154154
155-
If *sort_keys* is ``True`` (default: ``False``), then the output of
155+
If *sort_keys* is true (default: ``False``), then the output of
156156
dictionaries will be sorted by key.
157157
158158
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,
214214
``default(obj)`` is a function that should return a serializable version
215215
of obj or raise TypeError. The default simply raises TypeError.
216216
217-
If *sort_keys* is ``True`` (default: ``False``), then the output of
217+
If *sort_keys* is true (default: ``False``), then the output of
218218
dictionaries will be sorted by key.
219219
220220
To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the

0 commit comments

Comments
 (0)