Skip to content

gh-137533: document key type coercion limitations in json.loads #137545

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 19 commits into
base: main
Choose a base branch
from
Open

gh-137533: document key type coercion limitations in json.loads #137545

Changes from 9 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
98ba5d5
gh-137533:Add a note under `function:: loads()` to Improve visibility…
Rov-Waff Aug 8, 2025
dcfd3f3
Merge branch 'main' into fix-issue-137533
Rov-Waff Aug 8, 2025
1161ad0
gh-137533:fix:warp line 396 to 6 lines
Rov-Waff Aug 8, 2025
56dfcfd
gh-137533:add a link for RFC8259
Rov-Waff Aug 8, 2025
40d0cd1
gh-137533:make up more example to explain json.loads
Rov-Waff Aug 9, 2025
9b6732b
gh-137533:make up more example to explain json.loads
Rov-Waff Aug 9, 2025
8c9d81b
gh-137533:just restate the key of json must be string
Rov-Waff Aug 9, 2025
40c5678
gh-137533:restate that keys in JSON must be strings at module-level docs
Rov-Waff Aug 9, 2025
541878a
gh-137533:add RFC link ,then fix a RFC link at line 376
Rov-Waff Aug 9, 2025
e0dc7eb
gh-137533:nuked new note under function:: loads()
Rov-Waff Aug 10, 2025
1814bfa
gh-137533:shorten the sentence of this note,maybe its too short : (
Rov-Waff Aug 10, 2025
f17de69
gh-137533:correct expression
Rov-Waff Aug 10, 2025
a4b8240
gh-137533:move notes under json.dumps() to module-level documents
Rov-Waff Aug 10, 2025
1a71527
gh-137533:fix the note in json.dump()
Rov-Waff Aug 10, 2025
da6e655
gh-137533:make a example in json.loads()
Rov-Waff Aug 10, 2025
3d0b304
gh-137533:nuked notes in json.dumps() and json.loads()
Rov-Waff Aug 10, 2025
d61e84b
gh-137533:make a section about json key convertion,then make some ref
Rov-Waff Aug 11, 2025
96f54a7
gh-137533:remove the notes above part basic usage
Rov-Waff Aug 11, 2025
9bbdb5a
gh-137533:warp too long lines
Rov-Waff Aug 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions Doc/library/json.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,13 @@ See :ref:`json-commandline` for detailed documentation.
This module's encoders and decoders preserve input and output order by
default. Order is only lost if the underlying containers are unordered.

.. note::
According to :rfc:`7159`, the keys of all objects in JSON are strings.
Copy link
Member

@picnixz picnixz Aug 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is too long and we have now three places where this kind of mention occurs. Here, in json.dumps() and in json.loads(). Let's avoid three different formulations and let's do as follows:

  • Remove the new note in json.loads().
  • Remove the note in json.dumps() and move it here (you can start this note by "RFC ... requires JSON keys to be strings".
  • You can add an example for json.dumps() and json.loads() which shows what happens when we dump or load something with an numeric python key.

Under normal circumstances,the encoder of this module
will convert the keys of all Python dictionaries into strings as the
keys of JSON objects, and the decoder of this module will
decode the keys of all JSON objects into strings as the keys
of Python dictionaries

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Revert unrelated changes.

Basic Usage
-----------
Expand Down Expand Up @@ -364,6 +371,12 @@ Basic Usage
.. versionchanged:: 3.9
The keyword argument *encoding* has been removed.

.. note::

As mandated by :rfc:`7159`, JSON keys must be :class:`str` objects.
In particular, ``json.loads('{"42": "spam"}')`` returns ``{'42': 'spam'}``,
but ``json.loads('{42: "spam"}')`` fails since ``42`` is not a valid JSON key.


Encoders and Decoders
---------------------
Expand Down
Loading