[Xah Lee]
I just read you post. You did devote a substantial amount of time
to the project. Some of your criticisms are valid. Wish you had
posted patches, I think many of them would have been accepted.
Since you wrote this a few years ago, many examples have
been added to the docs and more are forthcoming.
Some are the criticisms are valid; others seem off-base.
* The key= and reversed= parameters are not intended for special
cases, leaving cmp= for the general case. They were intended to
be full replacements. In Python3.x, the cmp function is gone.
* The interaction of the key= and cmp= functions can be made to
interact (the key function is first applied to every element and
the cmp function then gets applied to the results of the key
function). This isn't a normal or intended use case, so the docs
don't delve into the subject.
* The reversed parameter does more than list.sort() followed by
list.reverse(). It also preserves stability in the event of equal
[(1,2), (1,3)]
li.sort(lambda x, y: cmp(x[1],y[1]), reverse=True)
li.sort(lambda x, y: cmp(y[1],x[1]))
* We should link the sorted() and list.sort() docs to the
sorting how-to (with a fuller discussion on the art of sorting
including a discussion of operator.itemgetter() and
operator.attrgetter() which were designed to work with the key=
parameter.
After one more reading of Xah Lee's posts on the documentation for
sort,
* The reason that list.sort() allows None for the cmp parameter is not
so that you can write list.sort(None). It was put there to make it
easier for people writing function definitions where the cmp function
s = seq[:]
s.sort(cmp) # needs to accept None as a possible
argument
return s[:maxlen]
* The reason for implementing the key= parameter had nothing to do
with limitations of Python's compiler. Instead, it was inspired by
the
decorate-sort-undecorate pattern.

* The reason for implementing the key= parameter had nothing to do
with limitations of Python's compiler. Instead, it was inspired by
the
decorate-sort-undecorate pattern.