Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork34k
Doc: Clarify sorted() returns new list in sorting howto#144272
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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Doc: Clarify sorted() returns new list in sorting howto#144272
Conversation
python-cla-botbot commentedJan 27, 2026 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
All commit authors signed the Contributor License Agreement. |
NureddinSoltan commentedJan 27, 2026
This is a small documentation-only clarification. |
picnixz left a comment• edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
IMO, the sentence "returns a new sorted list" is already clear. In the beginning of the section we have:
There is also a :func:
sortedbuilt-in function that builds a new
sorted list from an iterable.
The proposed changes add more text and honestly make the section less digest. I'm however -0.5 with changing the example to the last example:
>>>sorted([5,2,3,1,4])[1, 2, 3, 4, 5]
is transformed into
>>> integers = [5, 2, 3, 1, 4]>>> sorted_integers = sorted(integers)>>> sorted_integers[1, 2, 3, 4, 5]However, this would also make the example less digest and the problem is maybe rather with the implicit REPL output. So I would rather not change anything.
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
NureddinSoltan commentedJan 27, 2026
Thank you for reviewing! I remember when I first read this documentation, I was confused about what "returns a new sorted list" meant. Seeing the result in the shell made me think the original list was sorted. I like your second suggestion of changing the first example to use variables and I agree with that. If you think that improvement is worth making, I'm happy to update the PR. Otherwise, I'm fine closing it. |
picnixz commentedJan 27, 2026
Let's ask some documentation and teaching experts@terryjreedy@hugovk (I only taught Python to people already familiar with it so my opinion here is biased) |
Uh oh!
There was an error while loading.Please reload this page.
skirpichev left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
@NureddinSoltan, you did a claim:
Beginners often mistakenly assume that sorted(list) modifies the list in place.
Could you prove it somehow?
IMO, there is no issue and the PR must be closed.
| A simple ascending sort is very easy: just call the :func:`sorted` function. It | ||
| returns a new sorted list: | ||
| returns a new sorted list and does not modify the original. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
IMO, it's useless. HOWTO already very clear here and sorted docs also:
Return a new sorted list from the items in iterable.
| If you do not store or otherwise use the return value, the sorted result is | ||
| lost: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
It's also redundant, given above sentence.
No need to explain every basic language feature in the HOWTO. We have the Tutorial for this.
picnixz commentedJan 28, 2026
After a night of rest, I also think that my example would still be too complex for a HOWTO. I actually thought that the HOWTO was the tutorial but it seems that those are two different sections right? if this is the case I agree on closing the issue |
NureddinSoltan commentedJan 28, 2026
@skirpichev Thank you for asking for evidence. When I was searching before updating the PR, I found many beginners who were confused about this, likehere andhere. To be honest, when I first read this documentation myself, I had to really think about it. Seeing the sorted result come out in the shell gave me the feeling that the list was sorted, even though I already knew it wasn't. That's why I thought making it more explicit with an example would help people who are going to read it for the first time. But I understand if you think the current version is clear enough. Thanks for taking the time to review it! |
NureddinSoltan commentedJan 28, 2026
Thank you@picnixz@StanFromIreland@skirpichev for taking the time to review this and for the discussion. I understand your perspective on keeping the documentation concise. I'll close this PR now. I appreciate the feedback! |
Uh oh!
There was an error while loading.Please reload this page.
This PR clarifies that
sorted()returns a new list without modifying the original.Beginners often mistakenly assume that
sorted(list)modifies the list in place.The documentation now includes examples showing that:
This change updates theSorting Basics section of the sorting HOWTO
📚 Documentation preview 📚:https://cpython-previews--144272.org.readthedocs.build/