From 98ba5d520e5b3aed92d63f876f840762f3f1185d Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Fri, 8 Aug 2025 15:39:51 +0800 Subject: [PATCH 01/18] gh-137533:Add a note under `function:: loads()` to Improve visibility of key type coercion limitation in json module docs --- Doc/library/json.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 12a5a96a3c56f3..9f1b837dce77f3 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -364,6 +364,10 @@ Basic Usage .. versionchanged:: 3.9 The keyword argument *encoding* has been removed. + .. note:: + + As mandated by RFC 8259,the key in key-value pairs in JSON is always of type of :class:`str`,so the key of the dictionary that is got by serializing a JSON object is always a string. + Example:``json.loads('{"42":"value"}')`` will get a dictionary ``{'42':'value'}`` Encoders and Decoders --------------------- From 1161ad038042776132cea87f21b1ecf353a80f89 Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Fri, 8 Aug 2025 16:22:48 +0800 Subject: [PATCH 02/18] gh-137533:fix:warp line 396 to 6 lines --- Doc/library/json.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 9f1b837dce77f3..1c0272102cea24 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -366,8 +366,12 @@ Basic Usage .. note:: - As mandated by RFC 8259,the key in key-value pairs in JSON is always of type of :class:`str`,so the key of the dictionary that is got by serializing a JSON object is always a string. - Example:``json.loads('{"42":"value"}')`` will get a dictionary ``{'42':'value'}`` + As mandated by RFC 8259, keys in JSON key-value pairs are always of + type :class:`str`. Therefore, dictionary keys obtained by + deserializing JSON objects will always be strings. + For Example, + ``json.loads('{"42":"value"}')`` returns the dictionary + ``{'42': 'value'}``. Encoders and Decoders --------------------- From 56dfcfd72427fb7b665819bed02a43b631d728d3 Mon Sep 17 00:00:00 2001 From: xiaole233 Date: Fri, 8 Aug 2025 16:39:55 +0800 Subject: [PATCH 03/18] gh-137533:add a link for RFC8259 Thanks for StanFromIreland's suggestion Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/json.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 1c0272102cea24..d49ea3a4dd72c3 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -366,7 +366,7 @@ Basic Usage .. note:: - As mandated by RFC 8259, keys in JSON key-value pairs are always of + As mandated by :rfc:`8259`, keys in JSON key-value pairs are always of type :class:`str`. Therefore, dictionary keys obtained by deserializing JSON objects will always be strings. For Example, From 40d0cd1dd642c7ffbfc68b70eeac940bff124f71 Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Sat, 9 Aug 2025 15:17:22 +0800 Subject: [PATCH 04/18] gh-137533:make up more example to explain json.loads --- Doc/library/json.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index d49ea3a4dd72c3..f86bf3caadcf74 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -370,8 +370,10 @@ Basic Usage type :class:`str`. Therefore, dictionary keys obtained by deserializing JSON objects will always be strings. For Example, - ``json.loads('{"42":"value"}')`` returns the dictionary - ``{'42': 'value'}``. + ``json.loads('{"42":"spam"}')`` returns the dictionary + ``{'42': 'spam'}`,but ``json.loads('{42:"spam"}')`` + will raise a exception,because it is not a correct + JSON text Encoders and Decoders --------------------- From 9b6732b290c13f6e431a16ef13047a0d37df7881 Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Sat, 9 Aug 2025 15:24:34 +0800 Subject: [PATCH 05/18] gh-137533:make up more example to explain json.loads yes,i made a silly mistake and wasted some CI resource --- Doc/library/json.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index f86bf3caadcf74..67a9aa0333969b 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -371,7 +371,7 @@ Basic Usage deserializing JSON objects will always be strings. For Example, ``json.loads('{"42":"spam"}')`` returns the dictionary - ``{'42': 'spam'}`,but ``json.loads('{42:"spam"}')`` + ``{'42': 'spam'}``,but ``json.loads('{42:"spam"}')`` will raise a exception,because it is not a correct JSON text From 8c9d81b11ef494aeaed7f0d903d032236cb37fff Mon Sep 17 00:00:00 2001 From: xiaole233 Date: Sat, 9 Aug 2025 16:29:48 +0800 Subject: [PATCH 06/18] gh-137533:just restate the key of json must be string MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/json.rst | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 67a9aa0333969b..1bbc34bf7b50e8 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -366,14 +366,10 @@ Basic Usage .. note:: - As mandated by :rfc:`8259`, keys in JSON key-value pairs are always of - type :class:`str`. Therefore, dictionary keys obtained by - deserializing JSON objects will always be strings. - For Example, - ``json.loads('{"42":"spam"}')`` returns the dictionary - ``{'42': 'spam'}``,but ``json.loads('{42:"spam"}')`` - will raise a exception,because it is not a correct - JSON text + As mandated by :rfc:`8259`, 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 --------------------- From 40c5678515fb2412037caa3c0ffbe47c1cd0ddf3 Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Sat, 9 Aug 2025 17:14:35 +0800 Subject: [PATCH 07/18] gh-137533:restate that keys in JSON must be strings at module-level docs --- Doc/library/json.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 1bbc34bf7b50e8..d56d1a359d9a44 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -22,7 +22,6 @@ is a lightweight data interchange format inspired by The term "object" in the context of JSON processing in Python can be ambiguous. All values in Python are objects. In JSON, an object refers to any data wrapped in curly braces, similar to a Python dictionary. - .. warning:: Be cautious when parsing JSON data from untrusted sources. A malicious JSON string may cause the decoder to consume considerable CPU and memory @@ -146,6 +145,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. + 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 Basic Usage ----------- From 541878a578b7cef883cee6667af7f6d40ebeff50 Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Sat, 9 Aug 2025 17:31:27 +0800 Subject: [PATCH 08/18] gh-137533:add RFC link ,then fix a RFC link at line 376 --- Doc/library/json.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index d56d1a359d9a44..9c08eefba7a6a2 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -22,6 +22,7 @@ is a lightweight data interchange format inspired by The term "object" in the context of JSON processing in Python can be ambiguous. All values in Python are objects. In JSON, an object refers to any data wrapped in curly braces, similar to a Python dictionary. + .. warning:: Be cautious when parsing JSON data from untrusted sources. A malicious JSON string may cause the decoder to consume considerable CPU and memory @@ -146,7 +147,7 @@ See :ref:`json-commandline` for detailed documentation. 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. + According to :rfc:`7159`, the keys of all objects in JSON are strings. 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 @@ -372,7 +373,7 @@ Basic Usage .. note:: - As mandated by :rfc:`8259`, JSON keys must be :class:`str` objects. + 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. From e0dc7eb6a672a0a50f3184ad2f451cf8a7890a61 Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Sun, 10 Aug 2025 15:24:30 +0800 Subject: [PATCH 09/18] gh-137533:nuked new note under function:: loads() --- Doc/library/json.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 9c08eefba7a6a2..6e8bcf1bc2015e 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -371,13 +371,6 @@ 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 --------------------- From 1814bfa1f58b2896cdf0cef5c60ce1e27c2f2d0e Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Sun, 10 Aug 2025 15:30:47 +0800 Subject: [PATCH 10/18] gh-137533:shorten the sentence of this note,maybe its too short : ( --- Doc/library/json.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 6e8bcf1bc2015e..11fcd5d21516dd 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -147,12 +147,9 @@ See :ref:`json-commandline` for detailed documentation. 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. - 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 + Per RFC 7159, JSON keys are strings. + This module's encoder converts dictionary keys to strings, + and its decoder produces dictionaries with string keys. Basic Usage ----------- From f17de691066a0eb4ad0b4140c99e850c750f5b14 Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Sun, 10 Aug 2025 15:35:33 +0800 Subject: [PATCH 11/18] gh-137533:correct expression --- Doc/library/json.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 11fcd5d21516dd..47c738be8dbfb7 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -147,9 +147,9 @@ See :ref:`json-commandline` for detailed documentation. default. Order is only lost if the underlying containers are unordered. .. note:: - Per RFC 7159, JSON keys are strings. - This module's encoder converts dictionary keys to strings, - and its decoder produces dictionaries with string keys. + Per :rfc:`7159`, JSON objects' keys must be strings. + This module's encoder converts Python dictionary's keys to strings, + and its decoder produces Python dictionaries with string keys. Basic Usage ----------- From a4b82406f7965d54793deebf701b272248829715 Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Sun, 10 Aug 2025 15:48:22 +0800 Subject: [PATCH 12/18] gh-137533:move notes under json.dumps() to module-level documents --- Doc/library/json.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 47c738be8dbfb7..062b5e10ab70be 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -147,9 +147,10 @@ See :ref:`json-commandline` for detailed documentation. default. Order is only lost if the underlying containers are unordered. .. note:: - Per :rfc:`7159`, JSON objects' keys must be strings. - This module's encoder converts Python dictionary's keys to strings, - and its decoder produces Python dictionaries with string keys. + :rfc:`7159` requires that keys in key/value pairs of JSON are always of the + type :class:`str`. When a dictionary is converted into JSON, all the keys + of the dictionary arecoerced to strings.When a JSON object is converted into + dictionaries,all the keys of the dictionary are strings. Basic Usage ----------- From 1a715274220ab873ac74bb5161ca1d2a02c3279f Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Sun, 10 Aug 2025 15:57:38 +0800 Subject: [PATCH 13/18] gh-137533:fix the note in json.dump() --- Doc/library/json.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 062b5e10ab70be..429b255a77b2ce 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -261,12 +261,10 @@ Basic Usage .. note:: - Keys in key/value pairs of JSON are always of the type :class:`str`. When - a dictionary is converted into JSON, all the keys of the dictionary are - coerced to strings. As a result of this, if a dictionary is converted - into JSON and then back into a dictionary, the dictionary may not equal - the original one. That is, ``loads(dumps(x)) != x`` if x has non-string - keys. + The encoder will convert all non-string keys in dictionaries into string, + if a dictionary is converted into JSON and then back into a dictionary, + the dictionary may not equal the original one. + That is, ``loads(dumps(x)) != x`` if x has non-string keys. .. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, \ parse_int=None, parse_constant=None, \ From da6e6554e351156149a0b3eac8dbd68f7982c965 Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Sun, 10 Aug 2025 16:08:14 +0800 Subject: [PATCH 14/18] gh-137533:make a example in json.loads() --- Doc/library/json.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 429b255a77b2ce..cc9daee48bf76b 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -367,6 +367,12 @@ Basic Usage .. versionchanged:: 3.9 The keyword argument *encoding* has been removed. + .. note:: + + The decoder will convert all JSON objects' keys into string as + the key of dictionaries,for example, + ``json.loads('{"spam":"foo"}')`` returns ``{'spam':'foo'}`` + Encoders and Decoders --------------------- From 3d0b304fc675abac11129f8032363f43293ea6ae Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Sun, 10 Aug 2025 16:35:34 +0800 Subject: [PATCH 15/18] gh-137533:nuked notes in json.dumps() and json.loads() --- Doc/library/json.rst | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index cc9daee48bf76b..e7ac5e8488f733 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -259,13 +259,6 @@ Basic Usage table `. The arguments have the same meaning as in :func:`dump`. - .. note:: - - The encoder will convert all non-string keys in dictionaries into string, - if a dictionary is converted into JSON and then back into a dictionary, - the dictionary may not equal the original one. - That is, ``loads(dumps(x)) != x`` if x has non-string keys. - .. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, \ parse_int=None, parse_constant=None, \ object_pairs_hook=None, **kw) @@ -367,11 +360,6 @@ Basic Usage .. versionchanged:: 3.9 The keyword argument *encoding* has been removed. - .. note:: - - The decoder will convert all JSON objects' keys into string as - the key of dictionaries,for example, - ``json.loads('{"spam":"foo"}')`` returns ``{'spam':'foo'}`` Encoders and Decoders --------------------- From d61e84bd222f36d660c4d53b13fb7f71da806c34 Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Mon, 11 Aug 2025 08:59:08 +0800 Subject: [PATCH 16/18] gh-137533:make a section about json key convertion,then make some ref --- Doc/library/json.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index e7ac5e8488f733..47b6fc564ae064 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -259,6 +259,10 @@ Basic Usage table `. The arguments have the same meaning as in :func:`dump`. + .. note:: + + The encoder dose not preserve the types of dictionary keys in Python.Read more at :ref:`json-key-convertion` + .. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, \ parse_int=None, parse_constant=None, \ object_pairs_hook=None, **kw) @@ -360,6 +364,10 @@ Basic Usage .. versionchanged:: 3.9 The keyword argument *encoding* has been removed. + .. note:: + + The decoder preserves the keys in JSON text as :class:`str`.Read more at :ref:`json-key-convertion` + Encoders and Decoders --------------------- @@ -573,6 +581,28 @@ Encoders and Decoders for chunk in json.JSONEncoder().iterencode(bigobject): mysocket.write(chunk) +.. _json-key-convertion: + +JSON Key Convertion +^^^^^^^^^^^^^^^^^^^ + +:rfc:`7159` requires that keys in key/value pairs of JSON are always of the +type :class:`str`. When a dictionary is converted into JSON, all the keys +of the dictionary arecoerced to strings.When a JSON object is converted into +dictionaries,all the keys of the dictionary are strings. +For example: + + >>> import json + >>> foo={1:"spam"} + >>> result=json.dumps(foo) + >>> print(result) + {"1": "spam"} + >>> print(foo) + {1: 'spam'} + >>> print(foo==result) + False + +It can be seen that non-string keys are converted into strings after being encoded as JSON Exceptions ---------- From 96f54a72b5d64eb64033998a6c3a172f54fa5321 Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Mon, 11 Aug 2025 08:59:48 +0800 Subject: [PATCH 17/18] gh-137533:remove the notes above part basic usage --- Doc/library/json.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 47b6fc564ae064..87cc95b87c311f 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -146,12 +146,6 @@ 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:: - :rfc:`7159` requires that keys in key/value pairs of JSON are always of the - type :class:`str`. When a dictionary is converted into JSON, all the keys - of the dictionary arecoerced to strings.When a JSON object is converted into - dictionaries,all the keys of the dictionary are strings. - Basic Usage ----------- From 9bbdb5aa49067db345ed469fa8d47d71933258fe Mon Sep 17 00:00:00 2001 From: Rov_Waff <2710182206@qq.com> Date: Mon, 11 Aug 2025 09:18:28 +0800 Subject: [PATCH 18/18] gh-137533:warp too long lines --- Doc/library/json.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 87cc95b87c311f..7066fcd124fa53 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -255,7 +255,8 @@ Basic Usage .. note:: - The encoder dose not preserve the types of dictionary keys in Python.Read more at :ref:`json-key-convertion` + The encoder dose not preserve the types of dictionary keys in Python. + Read more at :ref:`json-key-convertion` .. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, \ parse_int=None, parse_constant=None, \ @@ -360,7 +361,8 @@ Basic Usage .. note:: - The decoder preserves the keys in JSON text as :class:`str`.Read more at :ref:`json-key-convertion` + The decoder preserves the keys in JSON text as :class:`str`. + Read more at :ref:`json-key-convertion` Encoders and Decoders