gh-134150: Clarify distinction between JSON and Python objects (#134154)

MichaByte · web-flow · commit fa4e088668d4 · 2025-05-17T21:47:37.000-04:00
* gh-134150: Clarify distinction between JSON objects and Python objects in json module docs * Revert change to JSON introduction * Clarify occurrences of "object literal" as JSON
diff --git a/Doc/library/json.rst b/Doc/library/json.rst
@@ -18,12 +18,17 @@ is a lightweight data interchange format inspired by
 `JavaScript <https://en.wikipedia.org/wiki/JavaScript>`_ object literal syntax
 (although it is not a strict subset of JavaScript [#rfc-errata]_ ).
 
+.. note::
+   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
    resources. Limiting the size of data to be parsed is recommended.
 
-:mod:`json` exposes an API familiar to users of the standard library
+This module exposes an API familiar to users of the standard library
 :mod:`marshal` and :mod:`pickle` modules.
 
 Encoding basic Python object hierarchies::
@@ -60,7 +65,7 @@ Pretty printing::
         "6": 7
     }
 
-Specializing JSON object encoding::
+Customizing JSON object encoding::
 
    >>> import json
    >>> def custom_json(obj):
@@ -83,7 +88,7 @@ Decoding JSON::
     >>> json.load(io)
     ['streaming API']
 
-Specializing JSON object decoding::
+Customizing JSON object decoding::
 
     >>> import json
     >>> def as_complex(dct):
@@ -279,7 +284,7 @@ Basic Usage
 
    :param object_hook:
       If set, a function that is called with the result of
-      any object literal decoded (a :class:`dict`).
+      any JSON 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,
@@ -289,7 +294,7 @@ Basic Usage
 
    :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.
+      any JSON 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.
