Repository navigation
Contradictory sentences in json docs #146061
Description
Documentation
In the json docs, it is said that "the most compact representation" for json is used if None is passed as indent to json.dump (the default behaviour), under the json.dump "Parameters" section.
However, under the description for the separators parameter, this is said: "If [separators is ]None (the default), separators defaults to (', ', ': ') if indent is None, and (',', ': ') otherwise. For the most compact JSON, specify (',', ':') to eliminate whitespace." The claim that the default behaviour gives "the most compact representation" is thus wrong; separators=(',', ':') is actually required as well.
Section concerned (source):
:param indent:
If a positive integer or string, JSON array elements and
object members will be pretty-printed with that indent level.
A positive integer indents that many spaces per level;
a string (such as ``"\t"``) is used to indent each level.
If zero, negative, or ``""`` (the empty string),
only newlines are inserted.
If ``None`` (the default), the most compact representation is used.
:type indent: int | str | None
:param separators:
A two-tuple: ``(item_separator, key_separator)``.
If ``None`` (the default), *separators* defaults to
``(', ', ': ')`` if *indent* is ``None``,
and ``(',', ': ')`` otherwise.
For the most compact JSON,
specify ``(',', ':')`` to eliminate whitespace.
:type separators: tuple | NoneI can open a PR if required.
Activity
eendebakpt commentedon Mar 17, 2026
@jonathandung You are correct. Changing the docs to "a compact representation" or "the most compact indentation" would address the issue I think. Adding the exact representation used is also possible, but would perhaps be a bit verbose.
If you can make a PR with a suggestion for improvement that would be great!
jonathandung commentedon Mar 17, 2026
Sure, I will open a PR that closes this issue later.
Fix python#146061
serhiy-storchaka commentedon Mar 18, 2026
Please check also the docstrings.
jonathandung commentedon Mar 19, 2026
Good catch!
In the json source, specifically the json.dump docstring:
This is also wrong! It should be along the lines of
I will edit that file in my fork as well.
jonathandung commentedon Mar 19, 2026
Done
gh-146061: Clarify indent=None in json docs (GH-146095)
[3.13] gh-146061: Clarify indent=None in json docs (GH-146095) (GH-14…
[3.14] gh-146061: Clarify indent=None in json docs (GH-146095) (GH-14…
[3.15] gh-146061: Clarify indent=None in json docs (GH-146095) (GH-14…