Clean-up itertools docs and recipes.

Doc/library/itertools.rst

@@ -35,18 +35,11 @@ equivalent result.
 Likewise, the functional tools are designed to work well with the high-speed
 functions provided by the :mod:`operator` module.
 
-The module author welcomes suggestions for other basic building blocks to be
-added to future versions of the module.
-
 Whether cast in pure python form or compiled code, tools that use iterators are
-more memory efficient (and faster) than their list based counterparts. Adopting
+more memory efficient (and often faster) than their list based counterparts. Adopting
 the principles of just-in-time manufacturing, they create data when and where
 needed instead of consuming memory with the computer equivalent of "inventory".
 
-The performance advantage of iterators becomes more acute as the number of
-elements increases -- at some point, lists grow large enough to severely impact
-memory cache performance and start running slowly.
-
 
 .. seealso::
 
@@ -598,55 +591,35 @@ which incur interpreter overhead.
 
 .. testcode::
 
-   def take(n, seq):
+   def take(n, iterable):
-       return list(islice(seq, n))
+       "Return first n items of the iterable as a list"
+       return list(islice(iterable, n))
 
-   def enumerate(iterable):
+   def enumerate(iterable, start=0):
-       return izip(count(), iterable)
+       return izip(count(start), iterable)
 
-   def tabulate(function):
+   def tabulate(function, start=0):
        "Return function(0), function(1), ..."
-       return imap(function, count())
+       return imap(function, count(start))
-
-   def iteritems(mapping):
-       return izip(mapping.iterkeys(), mapping.itervalues())
 
    def nth(iterable, n):
-       "Returns the nth item or raise StopIteration"
+       "Returns the nth item or empty list"
-       return islice(iterable, n, None).next()
+       return list(islice(iterable, n, n+1))
 
-   def all(seq, pred=None):
+   def quantify(iterable, pred=bool):
-       "Returns True if pred(x) is true for every element in the iterable"
+       "Count how many times the predicate is true"
-       for elem in ifilterfalse(pred, seq):
+       return sum(imap(pred, iterable))
-           return False
-       return True
 
-   def any(seq, pred=None):
+   def padnone(iterable):
-       "Returns True if pred(x) is true for at least one element in the iterable"
-       for elem in ifilter(pred, seq):
-           return True
-       return False
-
-   def no(seq, pred=None):
-       "Returns True if pred(x) is false for every element in the iterable"
-       for elem in ifilter(pred, seq):
-           return False
-       return True
-
-   def quantify(seq, pred=None):
-       "Count how many times the predicate is true in the sequence"
-       return sum(imap(pred, seq))
-
-   def padnone(seq):
        """Returns the sequence elements and then returns None indefinitely.
 
        Useful for emulating the behavior of the built-in map() function.
        """
-       return chain(seq, repeat(None))
+       return chain(iterable, repeat(None))
 
-   def ncycles(seq, n):
+   def ncycles(iterable, n):
        "Returns the sequence elements n times"
-       return chain.from_iterable(repeat(seq, n))
+       return chain.from_iterable(repeat(iterable, n))
 
    def dotproduct(vec1, vec2):
        return sum(imap(operator.mul, vec1, vec2))

Lib/test/test_itertools.py

@@ -1185,52 +1185,32 @@ Samuele
 [22]
 [25, 26, 27, 28]
 
->>> def take(n, seq):
+>>> def take(n, iterable):
-...     return list(islice(seq, n))
+...     "Return first n items of the iterable as a list"
+...     return list(islice(iterable, n))
 
->>> def enumerate(iterable):
+>>> def enumerate(iterable, start=0):
-...     return izip(count(), iterable)
+...     return izip(count(start), iterable)
 
->>> def tabulate(function):
+>>> def tabulate(function, start=0):
 ...     "Return function(0), function(1), ..."
-...     return imap(function, count())
+...     return imap(function, count(start))
-
->>> def iteritems(mapping):
-...     return izip(mapping.iterkeys(), mapping.itervalues())
 
 >>> def nth(iterable, n):
-...     "Returns the nth item"
+...     "Returns the nth item or empty list"
 ...     return list(islice(iterable, n, n+1))
 
->>> def all(seq, pred=None):
+>>> def quantify(iterable, pred=bool):
-...     "Returns True if pred(x) is true for every element in the iterable"
+...     "Count how many times the predicate is true"
-...     for elem in ifilterfalse(pred, seq):
+...     return sum(imap(pred, iterable))
-...         return False
-...     return True
 
->>> def any(seq, pred=None):
+>>> def padnone(iterable):
-...     "Returns True if pred(x) is true for at least one element in the iterable"
-...     for elem in ifilter(pred, seq):
-...         return True
-...     return False
-
->>> def no(seq, pred=None):
-...     "Returns True if pred(x) is false for every element in the iterable"
-...     for elem in ifilter(pred, seq):
-...         return False
-...     return True
-
->>> def quantify(seq, pred=None):
-...     "Count how many times the predicate is true in the sequence"
-...     return sum(imap(pred, seq))
-
->>> def padnone(seq):
 ...     "Returns the sequence elements and then returns None indefinitely"
-...     return chain(seq, repeat(None))
+...     return chain(iterable, repeat(None))
 
->>> def ncycles(seq, n):
+>>> def ncycles(iterable, n):
-...     "Returns the sequence elements n times"
+...     "Returns the seqeuence elements n times"
-...     return chain(*repeat(seq, n))
+...     return chain(*repeat(iterable, n))
 
 >>> def dotproduct(vec1, vec2):
 ...     return sum(imap(operator.mul, vec1, vec2))
@@ -1315,24 +1295,6 @@ perform as purported.
 >>> nth('abcde', 3)
 ['d']
 
->>> all([2, 4, 6, 8], lambda x: x%2==0)
-True
-
->>> all([2, 3, 6, 8], lambda x: x%2==0)
-False
-
->>> any([2, 4, 6, 8], lambda x: x%2==0)
-True
-
->>> any([1, 3, 5, 9], lambda x: x%2==0,)
-False
-
->>> no([1, 3, 5, 9], lambda x: x%2==0)
-True
-
->>> no([1, 2, 5, 9], lambda x: x%2==0)
-False
-
 >>> quantify(xrange(99), lambda x: x%2==0)
 50