Update documentation for array_hook parameter

python · vstinner · Mar 27, 2026 · Mar 20, 2026 · Mar 24, 2026 · Mar 26, 2026
commit cdb6dcfa8f38009d0061f53613ee42636da013a7
diff --git a/Doc/library/json.rst b/Doc/library/json.rst
@@ -264,7 +264,7 @@ Basic Usage
 
 .. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, \
                    parse_int=None, parse_constant=None, \
-                   object_pairs_hook=None, **kw)
+                   object_pairs_hook=None, array_hook=None, **kw)
 
    Deserialize *fp* to a Python object
    using the :ref:`JSON-to-Python conversion table <json-to-py-table>`.
@@ -301,6 +301,15 @@ Basic Usage
       Default ``None``.
    :type object_pairs_hook: :term:`callable` | None
 
+   :param array_hook:
+      If set, a function that is called with the result of
+      any JSON array literal decoded with as a Python list.
+      The return value of this function will be used
+      instead of the :class:`list`.
+      This feature can be used to implement custom decoders.
+      Default ``None``.
+   :type array_hook: :term:`callable` | None
+
    :param parse_float:
       If set, a function that is called with
       the string of every JSON float to be decoded.
@@ -349,7 +358,10 @@ Basic Usage
       conversion length limitation <int_max_str_digits>` to help avoid denial
       of service attacks.
 
-.. function:: loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)
+   .. versionchanged:: 3.15
+       * Added the optional *array_hook* parameter.
+
+.. function:: loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, array_hook=None, **kw)
 
    Identical to :func:`load`, but instead of a file-like object,
    deserialize *s* (a :class:`str`, :class:`bytes` or :class:`bytearray`
@@ -412,6 +424,14 @@ Encoders and Decoders
    .. versionchanged:: 3.1
       Added support for *object_pairs_hook*.
 
+   *array_hook* is an optional function that will be called with the
+   result of every JSON array decoded as a list. The return value of
+   *array_hook* will be used instead of the :class:`list`. This feature can be
+   used to implement custom decoders.
+
+   .. versionchanged:: 3.15
+      Added support for *array_hook*.
+
    *parse_float* is an optional function that will be called with the string of
    every JSON float to be decoded.  By default, this is equivalent to
    ``float(num_str)``.  This can be used to use another datatype or parser for