Social problems of Python doc [was Re: Python docs disappointing]

Xah Lee xahlee at gmail.com
Mon Aug 17 08:50:27 CEST 2009


On Aug 12, 12:15 pm, Raymond Hettinger <pyt... at rcn.com> 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
> keys:
>
>    >>> 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=
> parameter.

> > 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
> sort,
> 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
> 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.

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.

  Xah
∑ http://xahlee.org/


More information about the Python-list mailing list