Python docs [was: function with a state]

Xah Lee xah at
Mon Mar 28 13:56:42 CEST 2005

Python doc “3.6.4 Mutable Sequence Types” at

in which contains the documentation of the “sort” method of a list.

.sort([cmp[,  key[, reverse]]])
sort the items of s in place
(7), (8), (9), (10)



The sort() method takes optional arguments for  controlling the

 cmp specifies a custom comparison function of two arguments  (list
items) which should return a negative, zero or positive number
depending on whether the first argument is considered smaller than,
equal to, or larger than the second argument: "cmp=lambda x,y:
cmp(x.lower(), y.lower())"

 key specifies a function of one argument that is used to  extract a
comparison key from each list element:  "cmp=str.lower"

 reverse is a boolean value. If set to True, then the  list elements
are sorted as if each comparison were reversed.

 In general, the key and reverse conversion processes are  much faster
than specifying an equivalent cmp function. This is  because cmp is
called multiple times for each list element while  key and reverse
touch each element only once.

 Changed in version 2.3: Support for None as an equivalent to omitting
cmp was added.

Changed in version 2.4: Support for key and reverse was added.


As a piece of documentation, this is a relatively lousy one.

The question Python doc writers need to ask when evaluating this piece
of doc are these:

* can a experienced programer (expert at several languages) who is new
to Python, and also have read the official Python tutorial, can he,
read this doc about ”sort”, and know exactly how to use it with all
the options?

* can this piece of documentation be rewritten fairly easily, so that
the answer to the previous question is a resounding yes?

To me, the answers to the above questions are No and Yes. Here are some
issues with the doc:

* in the paragraph about “Key”, the illustration given is:
“cmp=str.lower”. Shouldn't it be “key=str.lower”?

* This doc lacks examples. One or two examples will help a lot,
especially to less experienced programers. (which comprises the
majority of readers) In particular, it should give a full example of
using the cmp predicate and one with key.

* This doc fails to address what happens when the predicate and the
short cut version conflicts. e.g.
myList.sort(lambda x,y: cmp(x[0], y[0]), lambda x: str(x[0]), False )

* on the whole, the way this doc is written does not give a clear
picture of what exactly is happening (think of mathematics) with sort,
nor the roles of the supplied options, nor how to use them.

Quick remedy: add a examples of using cmp predicate. And a example
using “key” predicate. Add example of Using one of them and with
reverse. (the examples need not to come with much explanations. One
sentence annotation will do. )

Other than that, the way the doc is layed out with a terse table and
run-on footnotes (as appeared in other pages) is not inductive. For a
better improvement, there needs to be overhaul of the organization and
the attitude of the entire doc. The organization needs to be programing
based, as opposed to implementation or computer science based. (in this
regard, one can learn from the Perl folks). As to attitude, the writing
needs to be Python-as-is, as opposed to computer science framework.
I'll might have to give more details in the future, but I've made some
headway in this respect before; peruse:

 xah at xahlee.org

More information about the Python-list mailing list