Skip to content

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

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

Merged
merged 3 commits into from
May 18, 2025
Merged

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

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7fedbb6
gh-134150: Clarify distinction between JSON objects and Python object…
MichaByte May 17, 2025
9cfc2d6
Revert change to JSON introduction
MichaByte May 18, 2025
1225eb7
Clarify occurrences of "object literal" as JSON
MichaByte May 18, 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
15 changes: 10 additions & 5 deletions Doc/library/json.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

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

Glossary link to Python object?

Copy link
Member

Choose a reason for hiding this comment

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

In this case, I don't think a glossary link will help here. The reader in this case will know what a Python object is.

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
Copy link
Member

Choose a reason for hiding this comment

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

Again unrelated, please revert and do not make a mess of this pr.

though it should be changed to

:mod:`!json`

Copy link
Member

Choose a reason for hiding this comment

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

do not make a mess of this pr.

@StanFromIreland Please be aware that this is a first-time contributor. Let's try to be more constructive by pointing to the devguide.

Copy link
Member

Choose a reason for hiding this comment

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

I think "This module" make a better sentence anyway.

:mod:`marshal` and :mod:`pickle` modules.

Encoding basic Python object hierarchies::
Expand Down Expand Up @@ -60,7 +65,7 @@ Pretty printing::
"6": 7
}

Specializing JSON object encoding::
Customizing JSON object encoding::
Copy link
Member

Choose a reason for hiding this comment

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

Ditto

Copy link
Member

Choose a reason for hiding this comment

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

Again, I think this is a better word, and we don't want to make a separate PR for it, it would be too much churn.


>>> import json
>>> def custom_json(obj):
Expand All @@ -83,7 +88,7 @@ Decoding JSON::
>>> json.load(io)
['streaming API']

Specializing JSON object decoding::
Customizing JSON object decoding::
Copy link
Member

Choose a reason for hiding this comment

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

Ditto


>>> import json
>>> def as_complex(dct):
Expand Down Expand Up @@ -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,
Expand All @@ -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.
Expand Down
Loading