social problems of python doc


Thanks Raymond.

I've been out of python community for a couple of years. I've saved your messages and will study it later when next time i work in python. Possibly today and will reply in some of your points.

But just wanted to say thanks for improving python.

Also, sometimes ago out of the blue i noticed someone has posted a bug on python's gzip doc with acknowledgement. http://bugs.python.org/issue2406

Thank you M.-A. DARCHE (madarche).

Also, i noticed python doc now and later has improved a lot since last i looked around python 2.4. For one thing, the html/xhtml is now valid html. Good riddence of the fucking TeX. Also, code examples have syntax coloring on.

∑ http://xahlee.org/


On Aug 12, 12:15 pm, Raymond Hettinger wrote:
[Xah Lee]

> i've wrote several articles about this issue, total time spend on this
> is probably more than 2 months full-time work. See:

> • Python Documentation Problems
> http://xahlee.org/perl-python/python_doc_index.html

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.

> I often receive thank you emails for 2 particular articles, which are
> most frequently google searched as indicated by my weblog:

> • Python Doc Problem Example: gzip
> http://xahlee.org/perl-python/python_doc_gzip.html

> • Python Doc Problem Example: sort()
> http://xahlee.org/perl-python/python_doc_sort.html

> • Sorting in Python and Perl
> http://xahlee.org/perl-python/sort_list.html

Some are the criticisms are valid; others seem off-base.

Here are a few thoughts on list.sort() for those who are interested:

* 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

>>> sorted([(1,2), (1,3)], key=itemgetter(0), reverse=True)
[(1,2), (1,3)]

So it was not correct to say that the following are equivalent:

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=


Here are a few thoughts on list.sort() for those who are interested:

After one more reading of Xah Lee's posts on the documentation for
here are couple more thoughts:

* 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
is a possible argument:

def sort_and_chop(seq, maxlen, cmp=None):
s = seq[:]
s.sort(cmp) # needs to accept None as a possible
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
decorate-sort-undecorate pattern.


Hi Raymond,

thanks for the many points. They are informative, some i disagree, but it's getting into detail. I don't know python 3.0, will have to look into its sort in the future.

This part i don't particular agree:

> * 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 decorate-sort-undecorate pattern is a compiler limitation, for most of today's langs. I'm not sure, but i think some of the fancy functional langs automatically detect such and optimize it away, to various degrees.

... my criticism is usually written in a style catered to irritate a particular class of coder i call tech geekers (they think of themselfs with their idiotic term “hackers”). So, parts are exaggerated. It'd be more clear to say, that the reason for python's “key”, and as a “solution” or need of the decorate-sort-undecorate issue, can be attributed to the current state of the art of popular imperative language's compilers (induced by such lang's semantics).

again, i haven't studied python 3.0 to see what it has changed with sort, and thanks for the informative post. I find it intriguing that it doesn't have “cmp” anymore as you say.... maybe when i actually study it and i'll come away with rage and rants. LOL.

∑ http://xahlee.org/

No comments:

Post a Comment