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.