From: Raymond Hettinger [mailto:raymond.hettinger@verizon.net]
The docs and examples are a good place to start.
Just looked at the documentation for now... 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. dropwhile: the definition doesn't mention an "invert" parameter, but the Python equivalent does (but doesn't use it). This parameter (I assume) would merge the functionality of "dropwhile" and "dropuntil". Maybe it would be more readable to have both (implemented internally via a single function and a flag, probably)? It's also probably worth pointing out that dropwhile could have a slow startup time - imagine from itertools import dropwhile, count for n in dropwhile(lambda x: x < 2**30, count(-2**30)): print "Hello!" The first iteration wouldn't happen for a long time... (This is true of most iterator functions, it's just more surprising in this case as all of the remaining iterations will be "fast") ifilter: "Evaluates to True" should probably just be "is true". The Python code accepts functions returning non-boolean values in the natural way. 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. That's the key reason for having zip as well as map, isn't it? It's nearly worth a different name, but I can't think of one :-( izip: No real problem, other than that the subtle differences between zip and map(None) are hard to remember. Add the subtle differences between zip and izip, and map and imap, and it all gets rather messy. I wish there was an easy way of unifying or differentiating these. But I can't offer one myself :-( starmap: Um, I see the point. Sort of. A usage example or two would help a lot - I can't think why I'd want this. And I hate the name. Isn't it basically iapply? takewhile: As with dropwhile, the issue of the invert parameter (or a function dropuntil) needs resolving. In the examples section, reimplementation of existing tools, nth is wrong (the definition doesn't use "s"!) Also, with the definitions of enumerate/iteritems, my initial thought was "but the builtins will be quicker". This makes the examples bad, as they associate the itertools functions with the idea that they are slow. (Of course, that isn't the point, nor is it true, but it's not a good impression to leave the reader with). One final point - I don't really like the i- form of the names. We already have this style with x- forms like range/xrange, and it bugs me because I'm not *really* comfortable with having 2 forms (it's the usual problem of why use one rather than the other - and the name gives no clue). The need is there with builtins, but for a module maybe it isn't. Could we not have itertools just defining map, zip, ... functions. Then a user can either use the qualified form, or use import from. So you have import itertools for x in itertools.zip(a,b): or from itertools import zip as izip for x in izip(a,b): On the other hand, maybe this will also end up causing confusion... Hope this helps, Paul.