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

Tim Peters tim.one@home.com
Wed, 2 May 2001 17:24:28 -0400

[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.