Have at it, if you like
Nobody ever complains about it that I know of, so I’m not going mess with what appears to be working.
I think most people never really thought about it, and semi-consciously assume xs.sort(reverse=True) is the same as
xs.sort()
xs.reverse()
But it’s not. It is the same as:
xs.reverse()
xs.sort()
xs.reverse()
which is how it’s actually implemented. That’s the only connection between the keyword argument “reverse=” and the method “.reverse()”. They have different purposes.
The docs kind of say this, via “If [reverse=] set to True, then the list elements are sorted as if each comparison were reversed.”
I’d prefer plainer English, like “by default, elements are ordered from smallest to largest, but if reverse=True from largest to smallest; regardless, the original order of equal elements is preserved.”
All that’s very intentional for lists. I don’t know whether it was intentional for heapq.merge(). That stores tuples in the heap, one per input iterator. Each tuple holds the next unresolved value from its iterator, and the iterator’s bound __next__ method.
But that alone could blow up if different iterators had the same next value. Then tuple comparison could go on to try to compare the bound methods, and those don’t implement non-equality comparisons..
So, between those two, the index of the iterator in the original argument list is also stored. That ensures that all the tuples in the heap at any given time are totally ordered by lexicographic tuple comparison, never going on to compare he 3rd components.
“Inter-iterator stability” may just be a happy consequence of what was done just to prevent the implementation from blowing up, but that Raymond didn’t want the implementation to be constrained by it, so didn’t mention it in the docs.
OTOH, PyPy has a more efficient version of heapq.merge(), written by @sweeneyde, which doesn’t use heaps, and doesn’t need that trick. I recall at the time he was writing it that we agreed “inter-iterator stability” was nice to have, and, as I recall (but may be wrong) that it fell out “for free” by the rules used to promote values in his tournament tree (“in case of a tie, the left child wins”).