Contradictory sentences in json docs

[jonathandung]

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 | None

I can open a PR if required.

Linked PRs

• gh-146061: Fix contradicting sentences in json docs #146095

[eendebakpt]

@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]

Sure, I will open a PR that closes this issue later.

[serhiy-storchaka]

Please check also the docstrings.

[jonathandung]

Please check also the docstrings.

Good catch!

In the json source, specifically the json.dump docstring:

    If ``indent`` is a non-negative integer, then JSON array elements and
    object members will be pretty-printed with that indent level. An indent
    level of 0 will only insert newlines. ``None`` is the most compact
    representation.

    If specified, ``separators`` should be an ``(item_separator,
    key_separator)`` tuple.  The default is ``(', ', ': ')`` if *indent* is
    ``None`` and ``(',', ': ')`` otherwise.  To get the most compact JSON
    representation, you should specify ``(',', ':')`` to eliminate
    whitespace.

This is also wrong! It should be along the lines of

    If ``indent`` is a non-negative integer, then JSON array elements and
    object members will be pretty-printed with that indent level. An indent
    level of 0 will only insert newlines. ``None`` gives a compact
    representation; see below.

    If specified, ``separators`` should be an ``(item_separator,
    key_separator)`` tuple.  The default is ``(', ', ': ')`` if *indent* is
    ``None`` and ``(',', ': ')`` otherwise.  To get the most compact JSON
    representation, you should specify ``(',', ':')`` to eliminate
    whitespace.

I will edit that file in my fork as well.

[jonathandung]

Please check also the docstrings.

Done