Skip to content

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

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

Open
jonathandung wants to merge 16 commits into
base: main
Choose a base branch
from
+5 −5
Open

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

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
17a3337
Fix #146061
jonathandung Mar 17, 2026
a5c0e64
Remove trailing space
jonathandung Mar 18, 2026
8cc270a
Merge branch 'main' into main
jonathandung Mar 18, 2026
6729677
Merge branch 'main' into main
jonathandung Mar 19, 2026
539d82c
Edit json.dump docstring
jonathandung Mar 19, 2026
5571e3c
Merge branch 'python:main' into main
jonathandung Mar 19, 2026
62a65d9
Remove trailing whitespace
jonathandung Mar 19, 2026
307fbf1
Shorten description
jonathandung Mar 19, 2026
64cfb01
Merge branch 'main' into main
jonathandung Mar 19, 2026
9200894
Merge branch 'main' into main
jonathandung Mar 19, 2026
f8f49dc
Change docstring for dumps as well
jonathandung Mar 19, 2026
c8b2cd0
Remove trailing whitespace
jonathandung Mar 19, 2026
2336497
Merge branch 'main' into main
jonathandung Mar 19, 2026
357302d
Merge branch 'main' into main
jonathandung Mar 19, 2026
813cf20
Merge branch 'main' into main
jonathandung Mar 19, 2026
ae431d1
Merge branch 'main' into main
jonathandung Mar 25, 2026
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
4 changes: 3 additions & 1 deletion Doc/library/json.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,9 @@ Basic Usage
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.
If ``None`` (the default), no pretty printing is done, and a
Comment thread
jonathandung marked this conversation as resolved.
Outdated
compact representation is used, though a singular space is
still left after the separators.
Comment thread
jonathandung marked this conversation as resolved.
Outdated
:type indent: int | str | None

:param separators:
Expand Down
4 changes: 2 additions & 2 deletions Lib/json/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,8 +142,8 @@ def dump(obj, fp, *, skipkeys=False, ensure_ascii=True, check_circular=True,

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.
level of 0 will only insert newlines. ``None`` gives a compact
Copy link
Copy Markdown
Member

@serhiy-storchaka serhiy-storchaka Mar 19, 2026

Choose a reason for hiding this comment

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

If ``indent`` is ``None`` (the default), no newlines are inserted.

Copy link
Copy Markdown
Member

@serhiy-storchaka serhiy-storchaka Mar 19, 2026

Choose a reason for hiding this comment

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

This is not true. indent=None does not give a compact representation. indent=None gives the result of the same size as indent=0. I would not mention compactness here, it is misleading.

Copy link
Copy Markdown
Contributor Author

@jonathandung jonathandung Mar 19, 2026

Choose a reason for hiding this comment

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

It does give a compact representation.

> python -c "print(__import__('json').dumps([{'a': 1, 'b': [2, 3], 'c': {'d': 4, 'e': [5, 6]}}, 7]))"
[{"a": 1, "b": [2, 3], "c": {"d": 4, "e": [5, 6]}}, 7]
> python -c "print(__import__('json').dumps([{'a': 1, 'b': [2, 3], 'c': {'d': 4, 'e': [5, 6]}}, 7], indent=None))"
[{"a": 1, "b": [2, 3], "c": {"d": 4, "e": [5, 6]}}, 7]
> python -c "print(__import__('json').dumps([{'a': 1, 'b': [2, 3], 'c': {'d': 4, 'e': [5, 6]}}, 7], indent=0))"
[
{
"a": 1,
"b": [
2,
3
],
"c": {
"d": 4,
"e": [
5,
6
]
}
},
7
]

Copy link
Copy Markdown
Member

@serhiy-storchaka serhiy-storchaka May 4, 2026

Choose a reason for hiding this comment

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

The term "compact" is ambiguous and misleading. It is not explicitly defined, and the only example for compact encoding uses separators=(',', ':'). It can be understood as a synonym of "the most compact".

What index=None does is making the output single-line, or not inserting newlines.

representation; see below.

If specified, ``separators`` should be an ``(item_separator,
key_separator)`` tuple. The default is ``(', ', ': ')`` if *indent* is
Expand Down
Loading