[Python-Dev] RE: [Python-checkins] CVS: python/dist/src/Doc/lib libfuncs.tex,1.76,1.77

[Tim Peters]

[Fred L. Drake]
> Update the filter() and list() descriptions to include information
> about the support for containers and iteration.
> ...
>   \begin{funcdesc}{list}{sequence}
> !   Return a list whose items are the same and in the same order as
> !   \var{sequence}'s items.  \var{sequence} may be either a sequence,
> !   a container that supports iteration, or an iterator object.
> ...

[and similarly for filter()]

Before we repeat this last incantation umpteen more times in the docs, is
this how we want it to read in the end?  The truth of the implementation and
of the design is that "sequence" is any object that supports iteration,
period (if PyObject_GetIter(op) succeeds, list(op) etc are happy, else they
raise TypeError).  "A sequence" and "an iterator object" *always* support
iteration, so naming them too appears to draw a distinction that doesn't
exist.

Suggested alternative:

    \var{sequence} must support iteration (see XXX).

where XXX is common boilerplate explaining what "support iteration" means,
and that sequences and iterator objects are just particular cases of that.
Note that this boilerplate may expand to include generators too before 2.2 is
real, and a generator isn't really "a container that supports iteration" (the
word "container" is a strain in the generator context).  That is, a
long-winded incantation is just going to get longer over time, and if it's
repeated umpteen places in the docs I doubt they'll all get updated when
needed.