mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-27 10:50:04 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

Docs: mark up json.load() using parameter list (#128488)

Browse source
This commit is contained in:
Erlend E. Aasland 2025-01-07 22:07:17 +01:00 • committed by GitHub
parent 8f93dd8a8f
commit a21e31ec54
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 69 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

113
Doc/library/json.rst
View file

@ -258,36 +258,82 @@ Basic Usage
the original one. That is, ``loads(dumps(x)) != x`` if x has non-string the original one. That is, ``loads(dumps(x)) != x`` if x has non-string
keys. keys.
.. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw) .. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, \
parse_int=None, parse_constant=None, \
object_pairs_hook=None, **kw)
Deserialize *fp* (a ``.read()``-supporting :term:`text file` or Deserialize *fp* to a Python object
:term:`binary file` containing a JSON document) to a Python object using using the :ref:`JSON-to-Python conversion table <json-to-py-table>`.
this :ref:`conversion table <json-to-py-table>`.
*object_hook* is an optional function that will be called with the result of :param fp:
any object literal decoded (a :class:`dict`). The return value of A ``.read()``-supporting :term:`text file` or :term:`binary file`
*object_hook* will be used instead of the :class:`dict`. This feature can containing the JSON document to be deserialized.
be used to implement custom decoders (e.g. `JSON-RPC :type fp: :term:`file-like object`
<https://www.jsonrpc.org>`_ class hinting).
*object_pairs_hook* is an optional function that will be called with the :param cls:
result of any object literal decoded with an ordered list of pairs. The If set, a custom JSON decoder.
return value of *object_pairs_hook* will be used instead of the Additional keyword arguments to :func:`!load`
:class:`dict`. This feature can be used to implement custom decoders. If will be passed to the constructor of *cls*.
*object_hook* is also defined, the *object_pairs_hook* takes priority. If ``None`` (the default), :class:`!JSONDecoder` is used.
:type cls: a :class:`JSONDecoder` subclass
:param object_hook:
If set, a function that is called with the result of
any object literal decoded (a :class:`dict`).
The return value of this function will be used
instead of the :class:`dict`.
This feature can be used to implement custom decoders,
for example `JSON-RPC <https://www.jsonrpc.org>`_ class hinting.
Default ``None``.
:type object_hook: :term:`callable` | None
:param object_pairs_hook:
If set, a function that is called with the result of
any object literal decoded with an ordered list of pairs.
The return value of this function will be used
instead of the :class:`dict`.
This feature can be used to implement custom decoders.
If *object_hook* is also set, *object_pairs_hook* takes priority.
Default ``None``.
:type object_pairs_hook: :term:`callable` | None
:param parse_float:
If set, a function that is called with
the string of every JSON float to be decoded.
If ``None`` (the default), it is equivalent to ``float(num_str)``.
This can be used to parse JSON floats into custom datatypes,
for example :class:`decimal.Decimal`.
:type parse_float: :term:`callable` | None
:param parse_int:
If set, a function that is called with
the string of every JSON int to be decoded.
If ``None`` (the default), it is equivalent to ``int(num_str)``.
This can be used to parse JSON integers into custom datatypes,
for example :class:`float`.
:type parse_int: :term:`callable` | None
:param parse_constant:
If set, a function that is called with one of the following strings:
``'-Infinity'``, ``'Infinity'``, or ``'NaN'``.
This can be used to raise an exception
if invalid JSON numbers are encountered.
Default ``None``.
:type parse_constant: :term:`callable` | None
:raises JSONDecodeError:
When the data being deserialized is not a valid JSON document.
.. versionchanged:: 3.1 .. versionchanged:: 3.1
Added support for *object_pairs_hook*.
*parse_float* is an optional function that will be called with the string of * Added the optional *object_pairs_hook* parameter.
every JSON float to be decoded. By default, this is equivalent to * *parse_constant* doesn't get called on 'null', 'true', 'false' anymore.
``float(num_str)``. This can be used to use another datatype or parser for
JSON floats (e.g. :class:`decimal.Decimal`).
*parse_int* is an optional function that will be called with the string of .. versionchanged:: 3.6
every JSON int to be decoded. By default, this is equivalent to
``int(num_str)``. This can be used to use another datatype or parser for * All optional parameters are now :ref:`keyword-only <keyword-only_parameter>`.
JSON integers (e.g. :class:`float`). * *fp* can now be a :term:`binary file`.
The input encoding should be UTF-8, UTF-16 or UTF-32.
.. versionchanged:: 3.11 .. versionchanged:: 3.11
The default *parse_int* of :func:`int` now limits the maximum length of The default *parse_int* of :func:`int` now limits the maximum length of
@ -295,27 +341,6 @@ Basic Usage
conversion length limitation <int_max_str_digits>` to help avoid denial conversion length limitation <int_max_str_digits>` to help avoid denial
of service attacks. of service attacks.
*parse_constant* is an optional function that will be called with one of the
following strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This can be
used to raise an exception if invalid JSON numbers are encountered.
.. versionchanged:: 3.1
*parse_constant* doesn't get called on 'null', 'true', 'false' anymore.
To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls``
kwarg; otherwise :class:`JSONDecoder` is used. Additional keyword arguments
will be passed to the constructor of the class.
If the data being deserialized is not a valid JSON document, a
:exc:`JSONDecodeError` will be raised.
.. versionchanged:: 3.6
All optional parameters are now :ref:`keyword-only <keyword-only_parameter>`.
.. versionchanged:: 3.6
*fp* can now be a :term:`binary file`. The input encoding should be
UTF-8, UTF-16 or UTF-32.
.. function:: loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw) .. function:: loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)
Deserialize *s* (a :class:`str`, :class:`bytes` or :class:`bytearray` Deserialize *s* (a :class:`str`, :class:`bytes` or :class:`bytearray`