Doc: Clarify sorted() returns new list in sorting howto

[NureddinSoltan]

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:

• the original list remains unchanged
• the return value must be assigned to a variable

This change updates the Sorting Basics section of the sorting HOWTO

---

📚 Documentation preview 📚: https://cpython-previews--144272.org.readthedocs.build/

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[NureddinSoltan]

This is a small documentation-only clarification.
Could a maintainer please add the skip issue label?

[picnixz]

IMO, the sentence "returns a new sorted list" is already clear. In the beginning of the section we have:

There is also a :func:sorted built-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.

[bedevere-app]

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 I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[NureddinSoltan]

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]

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)

[skirpichev]

@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.

[skirpichev]

IMO, it's useless. HOWTO already very clear here and sorted docs also:

Return a new sorted list from the items in iterable.

[skirpichev]

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]

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]

@skirpichev Thank you for asking for evidence. When I was searching before updating the PR, I found many beginners who were confused about this, like here and here.

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]

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!