diff --git a/Doc/library/json.rst b/Doc/library/json.rst index fb5c891579a7c1..949f191edeff1b 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -178,8 +178,8 @@ Basic Usage ``JSON.stringify``. If *allow_nan* is true but not equal to ``'as_null'`` then NaNs and infinities are converted to non-quote-delimited strings ``NaN``, ``Infinity`` and ``-Infinity`` in the JSON output. Note that this - represents an extension of the JSON specification, and is not compliant with - standard JSON. + represents an extension of the JSON specification, and that the generated + output may not be accepted as valid JSON by third party JSON parsers. 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 @@ -216,7 +216,7 @@ Basic Usage .. versionchanged:: 3.14 Added support for ``allow_nan='as_null'``. Passing any string value - other than ``'as_null'`` for ``allow_nan`` now raises a + other than ``'as_null'`` for ``allow_nan`` now triggers a :warning:`DeprecationWarning`. .. note:: @@ -225,7 +225,6 @@ Basic Usage so trying to serialize multiple objects with repeated calls to :func:`dump` using the same *fp* will result in an invalid JSON file. - .. function:: dumps(obj, *, skipkeys=False, ensure_ascii=True, \ check_circular=True, allow_nan=True, cls=None, \ indent=None, separators=None, default=None, \ @@ -461,15 +460,16 @@ Encoders and Decoders prevent an infinite recursion (which would cause a :exc:`RecursionError`). Otherwise, no such check takes place. - If *allow_nan* is the string ``'as_null'``, then NaNs and infinities are - encoded as JSON ``null`` values. This matches the behavior of JavaScript's - ``JSON.stringify``. If *allow_nan* is true but not equal to ``'as_null'``, - then ``NaN``, ``Infinity``, and ``-Infinity`` will be encoded as - corresponding non-quote-delimited strings in the JSON output. This is the - default behavior. This behavior represents an extension of the JSON - specification, but is consistent with some JavaScript based encoders and - decoders (as well as Python's own decoder). If *allow_nan* is false, it - will be a :exc:`ValueError` to encode such floats. + 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 with the JSON specification. If + *allow_nan* is the string ``'as_null'``, NaNs and infinities will be + converted to a JSON ``null``, matching the behavior of JavaScript's + ``JSON.stringify``. If *allow_nan* is true but not equal to ``'as_null'`` + then NaNs and infinities are converted to non-quote-delimited strings + ``NaN``, ``Infinity`` and ``-Infinity`` in the JSON output. Note that this + represents an extension of the JSON specification, and that the generated + output may not be accepted as valid JSON by third party JSON parsers. 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 @@ -503,7 +503,7 @@ Encoders and Decoders .. versionchanged:: 3.14 Added support for ``allow_nan='as_null'``. Passing any string value - other than ``'as_null'`` for *allow_nan* now raises a + other than ``'as_null'`` for *allow_nan* now triggers a :warning:`DeprecationWarning`. .. method:: default(o) diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index 6a3f9420c3379d..3e302347657f6e 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -90,7 +90,7 @@ json ---- * Add support for ``allow_nan='as_null'`` when encoding to JSON. This converts - floating-point infinities and NaNs to a JSON ``null``, for compatibility + floating-point infinities and NaNs to a JSON ``null``, for alignment with ECMAScript's ``JSON.stringify``. (Contributed by Mark Dickinson in :gh:`115246`.)