classification
Title: Incorrect description of sorting for PrettyPrinter
Type: Stage: resolved
Components: Documentation Versions: Python 3.8
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: TextGeek, docs@python, steven.daprano, terry.reedy, xtreak
Priority: normal Keywords:

Created on 2020-01-24 17:01 by TextGeek, last changed 2020-01-25 07:37 by terry.reedy. This issue is now closed.

Messages (5)
msg360630 - (view) Author: Steven DeRose (TextGeek) Date: 2020-01-24 17:01
The doc for pprint.PrettyPrinter at https://docs.python.org/3/library/pprint.html says:

    If sort_dicts is true (the default), dictionaries will be formatted with their keys sorted, otherwise they will display in insertion order

I believe the insertion order is not even known by normal dicts (only by OrderedDict), so I think the last phrase must be wrong. If it's somehow correct, it deserves explaining....
msg360632 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python committer) Date: 2020-01-24 17:18
dicts preserve their insertion order from Python 3.6 and is reflected in the documentation unless I am missing something here.
msg360663 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-01-24 23:34
How about 'in their default insertion order'?
msg360671 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2020-01-25 07:01
I don't think that any change is needed here. Adding "their default" to insertion order doesn't really help: if the reader knows dicts are now ordered, adding "default" is redundant; if the reader doesn't know, they'll still be confused. "What default insertion order? Dicts don't know their insertion order!" (Well actually they do.)

In a handful of more releases, most Python programmers won't even know, or will have forgotten, that there was ever a time that dicts didn't preserve insertion order, just as most of them don't know that there was ever a time that sorting wasn't stable or that dicts lacked an `update` method :-)

No offense to Steven here, but the problem wasn't with the docs (they are correct and accurate) but with his outdated knowledge of dicts. It's a perfectly understandable mistake to make, but it was a mistake.

I'm closing the task, but if anyone feels strongly enough to re-open it, I won't object.
msg360674 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-01-25 07:37
Closing is fine with me.
History
Date User Action Args
2020-01-25 07:37:12terry.reedysetmessages: + msg360674
2020-01-25 07:01:25steven.dapranosetstatus: open -> closed

nosy: + steven.daprano
messages: + msg360671

resolution: not a bug
stage: resolved
2020-01-24 23:34:15terry.reedysetnosy: + terry.reedy
messages: + msg360663
2020-01-24 17:18:45xtreaksetnosy: + xtreak
messages: + msg360632
2020-01-24 17:01:37TextGeekcreate