[issue40576] Align docs for list.sort, sorted, and on the website
New submission from Sam Lijin <python@sxlijin.com>: 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/f9e227e5a9d7a74393ef259c861660c3d1f... list.sort was last updated in 2018 by https://github.com/python/cpython/pull/8516 I have an incoming PR for this. ---------- assignee: docs@python components: Documentation messages: 368508 nosy: docs@python, sxlijin priority: normal severity: normal status: open title: Align docs for list.sort, sorted, and on the website type: enhancement versions: Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40576> _______________________________________
Change by Sam Lijin <python@sxlijin.com>: ---------- keywords: +patch pull_requests: +19327 stage: -> patch review pull_request: https://github.com/python/cpython/pull/20017 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40576> _______________________________________
Eric V. Smith <eric@trueblade.com> added the comment: 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(). ---------- nosy: +eric.smith _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40576> _______________________________________
Sam Lijin <python@sxlijin.com> added the comment: 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-30d76a3dc0c885f86917... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40576> _______________________________________
Eric V. Smith <eric@trueblade.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40576> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: 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. ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40576> _______________________________________
participants (3)
-
Eric V. Smith -
Raymond Hettinger
-
Sam Lijin