bpo-40576: Align docs for list.sort and sorted #20017
Closed
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Align the documentation for both
list.sort
andsorted
since thelatter's C implementation delegates to the C implementation of the
former, in both docstrings, the library docs, and tutorial.
Add a note about how reverse and sort stability interplay, as
this is an easily forgotten edge case and may not necessarily always be
desired.
bltinmodule.c, listobject.c.h:
Instead of saying "equal elements" in the note about sort stability,
we standardize on the "compare equal" phrasing from functions.rst,
which is more precise phrasing that acknowledges that sorting is
controlled by
key
."ascending or descending" is dropped from the explanation of
key
inlist.sort
, because that's controlled byreverse
, notkey
.library/functions.rst:
sorted
.list.sort
.library/stdtypes.rst:
"descending order" for consistency. (Also,library/itertools.html technically reversed isn't
quite true: == comparisons aren't reversed ;).)
tutorial/datastructures.rst:
list.sort
atlist.sort
.The set of modified files/locations was determined using:
The example of sort stability is included in functions.rst
but omitted from the docstrings deliberately: you can only really get to
it via
help()
orpydoc
, which I suspect tend to be used by peoplewho know what sort stability is. (Incidentally, in the discussion on
GH-8516, the last update to the list.sort docstring, rhettinger
also expresses the POV that further discussion of sort stability belongs
in extended docs like FAQs/HOWTOs.)
https://bugs.python.org/issue40576