[docs] [issue22237] sorted() docs should state that the sort is stable

[Martin Panter]

Martin Panter added the comment:

It looks like a fork of that how-to is actually part of the documentation: <https://docs.python.org/release/3.4.0/howto/sorting.html>. Perhaps the two should be linked better.

If “sorted” is indeed meant to be stable, that makes the docstring for the “heapsort” function <https://docs.python.org/release/3.4.0/library/heapq.html#basic-examples> invalid. That function is not stable, for example: heapsort((0, 0, False, 0)) -> [0, False, 0, 0].

Also, the how-to implicitly guarantees that only less-than (__lt__) is required for comparison. This is already documented for “list.sort”, but it might be good to add that guarantee to the “sorted” reference. Maybe also clarify if it applies (or not) to other sorting and comparison routines (e.g. heapq, bisect, min, max), though maybe that is straying off scope for this bug.

----------
nosy: +vadmium

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue22237>
_______________________________________