Skip to content

bpo-40576: Align docs for list.sort and sorted #20017

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.

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

Closed
wants to merge 1 commit into from

Conversation

sxlijin
Copy link

@sxlijin sxlijin commented May 9, 2020

Align the documentation for both list.sort and sorted since the
latter'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 in
    list.sort, because that's controlled by reverse, not key.

library/functions.rst:

  • Fix the type signature of sorted.
  • Redirect the documentation to list.sort.

library/stdtypes.rst:

  • Replace the "as if each comparison were reversed" language with
    "descending order" for consistency. (Also,library/itertools.html technically reversed isn't
    quite true: == comparisons aren't reversed ;).)

tutorial/datastructures.rst:

  • Point the link for list.sort at list.sort.

The set of modified files/locations was determined using:

grep -C3 -rnE '\`(list\.sort|sorted)\`' . | grep -v 'howto/sorting\|whatsnew'

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() or pydoc, which I suspect tend to be used by people
who 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

@the-knights-who-say-ni
Copy link

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA).

CLA Missing

Our records indicate the following people have not signed the CLA:

@sxlijin

For legal reasons we need all the people listed to sign the CLA before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

If you have recently signed the CLA, please wait at least one business day
before our records are updated.

You can check yourself to see if the CLA has been received.

Thanks again for the contribution, we look forward to reviewing it!

@sxlijin
Copy link
Author

sxlijin commented May 9, 2020

CLA is incoming (I got the echosign email just now, so I should only need to wait for Ewa to flip the bit now).

Align the documentation for both `list.sort` and `sorted` since the
latter'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` in
  `list.sort`, because that's controlled by `reverse`, not `key`.

library/functions.rst:

* Fix the type signature of `sorted`.
* Redirect the documentation to `list.sort`.

library/stdtypes.rst:

* Fix the type signature of `list.sort`.
* Replace the "as if each comparison were reversed" language with
  "descending order" for consistency. (Also, technically reversed isn't
  quite true: == comparisons aren't reversed ;).)

tutorial/datastructures.rst:

* Point the reference for `list.sort` to `list.sort`, instead of
  `sorted`.

The set of modified files/locations was determined using:

    grep -C3 -rnE '`(list\.sort|sorted)`' . | grep -v 'howto/sorting\|whatsnew'

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()` or `pydoc`, which I suspect tend to be used by people
who know what sort stability is. (Incidentally, in the discussion on
pythonGH-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.)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants