[Python-Dev] Itertools

[Raymond Hettinger]

From: "Moore, Paul" <Paul.Moore@atosorigin.com>
> Just looked at the documentation for now...

Great.  Any review at all is helpful


> count: In the absence of any explicit statement, I'd expect it
> to work transparently with longs, not just integers. You should
> likely make this explicit.

Done.


> dropwhile: the definition doesn't mention an "invert" parameter
> but the Python equivalent does (but doesn't use it).

Fixed the python definition in the docs.


>  It's also probably worth pointing out that dropwhile could have a
> slow startup time 

Done.


> ifilter: "Evaluates to True" should probably just be "is true".

Done.


> imap: The stop-on-shortest behaviour is reasonable (given the nature
> of iterators), but the fact that it's different from map is
> definitely a wart. 

It is one I'm willing to live with.  A need for a None fillin doesn't
come up in the use cases for iterator algebra and would more than likely
lead to unexpected errors.  I'm counting on documenting the difference;
having a different name (imap vs map); knowing that its use with map() 
was already extremely rare (how many functions respond well to having
a parameter suddenly switch type and become None); and having the
domain itself be a guide (for example, __builtin__.pow and math.pow
are not identical but in the domain of floats the idea of using 
raised-to-modulo just doesn't come up).

Though it chafes my desire for "foolish consistency", it neatly 
parallels the SML/Haskell versions, works well with other itertools,
and I don't expect a real problem to ever arise in practice.


> izip: No real problem, other than that the subtle differences between
> zip and map(None) are hard to remember.  I wish there was an easy 
> way of unifying or differentiating these.

zip() and map(None) are already set in stone.
izip() and imap(None) have no differences.

zip() and izip() only differ in that they return an iterator.  They are
differentiated by their name (hence, the "i" in izip).

So, the only difference is the None fillin feature for map().
The reasons for that are listed above.


> starmap: Um, I see the point. Sort of. A usage example or two would
>help a lot.  And I hate the name.

Expanded the docs with an example, clarified the usage, and put in
an analogy to show why the name is appropriate:  map() is to f(a,b)
as starmap is to f(*c).

While the name is reminiscent of a constellation chart, the use of
the star names has a long history in functional languages.
It also matches python's choice of an operator for f(*c).


> I can't think why I'd want this.

If your data stream is already "pre-zipped", it's major PITA to
unzip them  just to feed imap().


> takewhile: As with dropwhile, the issue of the invert parameter (or
> a function dropuntil) needs resolving.

Fixed.


> In the examples section, reimplementation of existing tools, nth is
> wrong (the definition doesn't use "s"!) 

Fixed.


> Also, with the definitions of enumerate/iteritems, my initial 
> thought was "but the builtins will be quicker". 

There is a strong pedagological value in building off of 
existing knowledge when showing how itertools can be
combined.  

But your point is well taken, so I rewrote the introduction to the 
section to indicate that it is just to show how the pieces fit
together.


> One final point - I don't really like the i- form of the names.

It is the module designer's perogative.  Not only does it steal
the pithy naming convention from MacIntosh marketing, it
is helpful for indicating that each function returns an iterator.

The x-functions pre-date iterators and generators and are 
all on their way out.  I don't want any confusion with them.


> Hope this helps, 
> Paul.

Absolutely.
Thank you again for contributing review time.


Raymond Hettinger