gh-146440: Add "array_hook" parameter to JSON decoders by jsbueno · Pull Request #146441 · python/cpython

jsbueno · 2026-03-26T02:00:50Z

Add array_hook parameter to json.load and json.loads

gh-146440: Add "array_hook" parameter to JSON decoder

📚 Documentation preview 📚: https://cpython-previews--146441.org.readthedocs.build/

Add array_hook parameter, to both Python and C implementations

bedevere-app · 2026-03-26T02:00:55Z

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

Misc/NEWS.d/next/Library/2026-03-26-02-06-52.gh-issue-146440.HXjhQO.rst

serhiy-storchaka

This change is simple enough, and I have no strong objections, although I do not see an immerse need of this feature.

Please add a What's New entry.

Doc/library/json.rst

serhiy-storchaka · 2026-03-26T08:42:32Z

Lib/json/__init__.py



-_default_decoder = JSONDecoder(object_hook=None, object_pairs_hook=None)
+_default_decoder = JSONDecoder(object_hook=None, object_pairs_hook=None, array_hook=None)


This is not needed. Actually, passing object_hook and object_pairs_hook is also not needed.

I've removed the ther default parameters, then.

Doc/library/json.rst

Misc/NEWS.d/next/Library/2026-03-26-02-06-52.gh-issue-146440.HXjhQO.rst

Doc/whatsnew/3.15.rst

vstinner · 2026-03-26T21:10:28Z

Lib/json/__init__.py

 def loads(s, *, cls=None, object_hook=None, parse_float=None,
-        parse_int=None, parse_constant=None, object_pairs_hook=None, **kw):
+        parse_int=None, parse_constant=None, object_pairs_hook=None,
+        array_hook=None, **kw):


Can you take this opportunity to fix the indentation? Add 2 spaces.

vstinner · 2026-03-26T21:11:54Z

Lib/json/decoder.py

            raise JSONDecodeError("Illegal trailing comma before end of array", s, comma_idx)

+    if array_hook is not None:
+        return array_hook(values), end


I would prefer to have a single return statement, so reuse your code from below:

Suggested change

return array_hook(values), end

values = array_hook(values)

vstinner · 2026-03-26T21:13:02Z

Lib/json/decoder.py

+        ``array_hook`` is an optional function that will be called with the result
+        of any literal array decode (a ``list``). The return value of this function will
+        be used instead of the ``list``. This feature can be used along
+        ``object_pairs_hook`` to customize the resulting data structure - for example,
+        by setting that to ``frozendict`` and ``array_hook`` to ``tuple``, one can get
+        a deep immutable data structute from any JSON data.


Reformatted to fit into 80 columns:

Suggested change

``array_hook`` is an optional function that will be called with the result

of any literal array decode (a ``list``). The return value of this function will

be used instead of the ``list``. This feature can be used along

``object_pairs_hook`` to customize the resulting data structure - for example,

by setting that to ``frozendict`` and ``array_hook`` to ``tuple``, one can get

a deep immutable data structute from any JSON data.

``array_hook`` is an optional function that will be called with the

result of any literal array decode (a ``list``). The return value of

this function will be used instead of the ``list``. This feature can

be used along ``object_pairs_hook`` to customize the resulting data

structure - for example, by setting that to ``frozendict`` and

``array_hook`` to ``tuple``, one can get a deep immutable data

structute from any JSON data.

vstinner · 2026-03-26T21:13:55Z

Misc/NEWS.d/next/Library/2026-03-26-02-06-52.gh-issue-146440.HXjhQO.rst

@@ -0,0 +1,6 @@
+:mod:`json`: Add the *array_hook* parameter to  :func:`~json.load` and
+:func:`~json.loads` functions:
+Allow a callback for JSON literal array types to customize Python lists in the


Suggested change

Allow a callback for JSON literal array types to customize Python lists in the

allow a callback for JSON literal array types to customize Python lists in the

vstinner · 2026-03-26T21:15:07Z

Modules/_json.c

        goto bail;
    }
    *next_idx_ptr = idx + 1;
+    /* if array_hook is not None: rval = array_hook(rval) */


Your pseudo-code doesn't describe correctly the code below:

Suggested change

/* if array_hook is not None: rval = array_hook(rval) */

/* if array_hook is not None: return array_hook(rval) */

vstinner · 2026-03-26T21:15:45Z

Modules/_json.c

    }
    *next_idx_ptr = idx + 1;
+    /* if array_hook is not None: rval = array_hook(rval) */
+    if (s->array_hook != Py_None) {


Suggested change

if (s->array_hook != Py_None) {

if (!Py_IsNone(s->array_hook)) {

vstinner · 2026-03-26T21:16:09Z

Modules/_json.c

+    if (s->array_hook == NULL)
+        goto bail;


New code should follow PEP 7:

Suggested change

if (s->array_hook == NULL)

goto bail;

if (s->array_hook == NULL) {

goto bail;

}

vstinner · 2026-03-26T21:22:40Z

Lib/test/test_json/test_decode.py

+    def test_array_hook(self):
+        s = '[1, 2, 3]'
+
+        t = self.loads(s, array_hook=tuple)
+        self.assertEqual(t, (1, 2, 3))
+        self.assertEqual(type(t), tuple)
+        # Array in inner structure
+        s = '{"xkd": [1, 2, 3]}'
+        p = {"xkd": (1, 2, 3)}
+        data = self.loads(s, array_hook=tuple)
+        self.assertEqual(data, p)
+        self.assertEqual(type(data["xkd"]), tuple)
+
+        self.assertEqual(self.loads('[]', array_hook=tuple), ())


The new documentation suggests object_hook=frozendict with array_hook=tuple, so IMO it's is a good opportunity to test them. I suggest a more elaborated test also with nested lists:

Suggested change

def test_array_hook(self):

s = '[1, 2, 3]'

t = self.loads(s, array_hook=tuple)

self.assertEqual(t, (1, 2, 3))

self.assertEqual(type(t), tuple)

# Array in inner structure

s = '{"xkd": [1, 2, 3]}'

p = {"xkd": (1, 2, 3)}

data = self.loads(s, array_hook=tuple)

self.assertEqual(data, p)

self.assertEqual(type(data["xkd"]), tuple)

self.assertEqual(self.loads('[]', array_hook=tuple), ())

def test_array_hook(self):

s = '[1, 2, 3]'

t = self.loads(s, array_hook=tuple)

self.assertEqual(t, (1, 2, 3))

self.assertEqual(type(t), tuple)

# Nested array in inner structure with object_hook

s = '{"xkd": [[1], [2], [3]]}'

p = frozendict(xkd=((1,), (2,), (3,)))

data = self.loads(s, object_hook=frozendict, array_hook=tuple)

self.assertEqual(data, p)

self.assertEqual(type(data), frozendict)

self.assertEqual(type(data["xkd"]), tuple)

for item in data["xkd"]:

self.assertEqual(type(item), tuple)

self.assertEqual(self.loads('[]', array_hook=tuple), ())

vstinner · 2026-03-26T21:23:24Z

Doc/library/json.rst

      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


Suggested change

.. versionchanged:: 3.15

.. versionchanged:: next

Co-authored-by: Victor Stinner <vstinner@python.org>

jsbueno added 2 commits March 25, 2026 22:55

array_hook for JSON decoder

ced66ad

Add array_hook parameter, to both Python and C implementations

Update documentation for array_hook parameter

cdb6dcf

bedevere-app bot added the awaiting review label Mar 26, 2026

jsbueno changed the title ~~Add json_array parameter to json.load and json.loads~~ gh-146440: Add "array_hook" parameter to JSON decoders Mar 26, 2026

bedevere-app bot mentioned this pull request Mar 26, 2026

Add "array_hook" parameter to JSON decoder #146440

Open

blurb-it bot and others added 2 commits March 26, 2026 02:06

📜🤖 Added by blurb_it.

c7b77ee

Fix typo in news blurb

be6cb37

mpkocher reviewed Mar 26, 2026

View reviewed changes

Misc/NEWS.d/next/Library/2026-03-26-02-06-52.gh-issue-146440.HXjhQO.rst Outdated Show resolved Hide resolved

jsbueno added 2 commits March 26, 2026 01:33

Fix doc formatting

2820503

Doc typo

b079384

serhiy-storchaka reviewed Mar 26, 2026

View reviewed changes

brianschubert reviewed Mar 26, 2026

View reviewed changes

Misc/NEWS.d/next/Library/2026-03-26-02-06-52.gh-issue-146440.HXjhQO.rst Outdated Show resolved Hide resolved

vstinner reviewed Mar 26, 2026

View reviewed changes

Misc/NEWS.d/next/Library/2026-03-26-02-06-52.gh-issue-146440.HXjhQO.rst Outdated Show resolved Hide resolved

jsbueno added 5 commits March 26, 2026 15:06

'What's New' entry

7ff9a73

Remove redundant default parameters

47072c3

Fix blurb content + formatting

9cd60a5

Formatting and missing parameter to JSONDecoder

6e48297

Reformat blurb

0eed2fb

jsbueno requested a review from AA-Turner as a code owner March 26, 2026 18:26

Merge branch 'main' into feature-json-array-hook

ee285ae

vstinner reviewed Mar 26, 2026

View reviewed changes

Update Doc/whatsnew/3.15.rst

2942826

Co-authored-by: Victor Stinner <vstinner@python.org>



		_default_decoder = JSONDecoder(object_hook=None, object_pairs_hook=None)
		_default_decoder = JSONDecoder(object_hook=None, object_pairs_hook=None, array_hook=None)

	Allow a callback for JSON literal array types to customize Python lists in the
	allow a callback for JSON literal array types to customize Python lists in the

	/* if array_hook is not None: rval = array_hook(rval) */
	/* if array_hook is not None: return array_hook(rval) */

	if (s->array_hook != Py_None) {
	if (!Py_IsNone(s->array_hook)) {

Uh oh!

Conversation

jsbueno commented Mar 26, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add array_hook parameter to json.load and json.loads

Uh oh!

bedevere-app bot commented Mar 26, 2026

Uh oh!

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jsbueno commented Mar 26, 2026 •

edited by github-actions bot

Loading