This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Align docs for list.sort, sorted, and on the website
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.smith, rhettinger, sxlijin
Priority: normal Keywords: patch

Created on 2020-05-09 10:30 by sxlijin, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 20017 closed sxlijin, 2020-05-09 13:06
Messages (5)
msg368508 - (view) Author: Sam Lijin (sxlijin) * Date: 2020-05-09 10:30
It's mildly confusing to see `pydoc sorted` and `pydoc list.sort` to look so different, esp. since sorted just delegates to list.sort.

By extension, https://docs.python.org/3/library/functions.html#sorted should also be aligned with this, but I'm not super familiar with what the distinction content in the docstrings and the website is intended to be, if there is any guiding philosophy there.

sorted() appears to have been documented as an afterthought as part of this commit:
https://github.com/python/cpython/commit/f9e227e5a9d7a74393ef259c861660c3d1f36f83

list.sort was last updated in 2018 by https://github.com/python/cpython/pull/8516

I have an incoming PR for this.
msg368521 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2020-05-09 14:17
sorted() does not just delegate to list.sort(): it sorts any iterable.

>>> sorted({0:1,2:3,-1:4})
[-1, 0, 2]

I think your change conflates the two by pointing to list.sort() from sorted().
msg368523 - (view) Author: Sam Lijin (sxlijin) * Date: 2020-05-09 14:26
I do clarify that they're not the same thing and that `sorted` accepts any iterable: https://github.com/python/cpython/pull/20017/files#diff-30d76a3dc0c885f86917b7d307ccf279
msg368526 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2020-05-09 15:20
I still think it's a mistake to point to list.sort() from sorted(). If anything I think it should be the other way around.

We'll see what other people think.
msg368547 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-05-09 21:28
To me, the PR isn't an improvement.  It makes the docs much more verbose without really adding information.  We already link to the sorting-howto which already discusses the pragmatics that arise in actual applications.

Also, there is no special benefit to cross-linking the list.sort() and sorted() docs.  While their implementation share a common foundation, that is just an implementation detail that is irrelevant from a user's point of view.
History
Date User Action Args
2022-04-11 14:59:30adminsetgithub: 84756
2020-05-09 21:28:47rhettingersetnosy: + rhettinger
messages: + msg368547
2020-05-09 15:20:03eric.smithsetmessages: + msg368526
2020-05-09 14:26:45sxlijinsetmessages: + msg368523
2020-05-09 14:17:35eric.smithsetnosy: + eric.smith
messages: + msg368521
2020-05-09 13:06:38sxlijinsetkeywords: + patch
stage: patch review
pull_requests: + pull_request19327
2020-05-09 10:30:31sxlijincreate