Move doctests to the main docs. Eliminate duplication. Improve coverage. (GH-30869)

Author: rhettinger

Doc/library/itertools.rst

@@ -1004,3 +1004,241 @@ which incur interpreter overhead.
                c, n = c*(n-r)//n, n-1
            result.append(pool[-1-n])
        return tuple(result)
+
+.. doctest::
+    :hide:
+
+    These examples no longer appear in the docs but are guaranteed
+    to keep working.
+
+    >>> amounts = [120.15, 764.05, 823.14]
+    >>> for checknum, amount in zip(count(1200), amounts):
+    ...     print('Check %d is for $%.2f' % (checknum, amount))
+    ...
+    Check 1200 is for $120.15
+    Check 1201 is for $764.05
+    Check 1202 is for $823.14
+
+    >>> import operator
+    >>> for cube in map(operator.pow, range(1,4), repeat(3)):
+    ...    print(cube)
+    ...
+    1
+    8
+    27
+
+    >>> reportlines = ['EuroPython', 'Roster', '', 'alex', '', 'laura', '', 'martin', '', 'walter', '', 'samuele']
+    >>> for name in islice(reportlines, 3, None, 2):
+    ...    print(name.title())
+    ...
+    Alex
+    Laura
+    Martin
+    Walter
+    Samuele
+
+    >>> from operator import itemgetter
+    >>> d = dict(a=1, b=2, c=1, d=2, e=1, f=2, g=3)
+    >>> di = sorted(sorted(d.items()), key=itemgetter(1))
+    >>> for k, g in groupby(di, itemgetter(1)):
+    ...     print(k, list(map(itemgetter(0), g)))
+    ...
+    1 ['a', 'c', 'e']
+    2 ['b', 'd', 'f']
+    3 ['g']
+
+    # Find runs of consecutive numbers using groupby.  The key to the solution
+    # is differencing with a range so that consecutive numbers all appear in
+    # same group.
+    >>> data = [ 1,  4,5,6, 10, 15,16,17,18, 22, 25,26,27,28]
+    >>> for k, g in groupby(enumerate(data), lambda t:t[0]-t[1]):
+    ...     print(list(map(operator.itemgetter(1), g)))
+    ...
+    [1]
+    [4, 5, 6]
+    [10]
+    [15, 16, 17, 18]
+    [22]
+    [25, 26, 27, 28]
+
+    Now, we test all of the itertool recipes
+
+    >>> import operator
+    >>> import collections
+
+    >>> take(10, count())
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+    >>> list(prepend(1, [2, 3, 4]))
+    [1, 2, 3, 4]
+
+    >>> list(enumerate('abc'))
+    [(0, 'a'), (1, 'b'), (2, 'c')]
+
+    >>> list(islice(tabulate(lambda x: 2*x), 4))
+    [0, 2, 4, 6]
+
+    >>> list(tail(3, 'ABCDEFG'))
+    ['E', 'F', 'G']
+
+    >>> it = iter(range(10))
+    >>> consume(it, 3)
+    >>> next(it)
+    3
+    >>> consume(it)
+    >>> next(it, 'Done')
+    'Done'
+
+    >>> nth('abcde', 3)
+    'd'
+
+    >>> nth('abcde', 9) is None
+    True
+
+    >>> [all_equal(s) for s in ('', 'A', 'AAAA', 'AAAB', 'AAABA')]
+    [True, True, True, False, False]
+
+    >>> quantify(range(99), lambda x: x%2==0)
+    50
+
+    >>> quantify([True, False, False, True, True])
+    3
+
+    >>> quantify(range(12), pred=lambda x: x%2==1)
+    6
+
+    >>> a = [[1, 2, 3], [4, 5, 6]]
+    >>> list(flatten(a))
+    [1, 2, 3, 4, 5, 6]
+
+    >>> list(repeatfunc(pow, 5, 2, 3))
+    [8, 8, 8, 8, 8]
+
+    >>> import random
+    >>> take(5, map(int, repeatfunc(random.random)))
+    [0, 0, 0, 0, 0]
+
+    >>> list(islice(pad_none('abc'), 0, 6))
+    ['a', 'b', 'c', None, None, None]
+
+    >>> list(ncycles('abc', 3))
+    ['a', 'b', 'c', 'a', 'b', 'c', 'a', 'b', 'c']
+
+    >>> dotproduct([1,2,3], [4,5,6])
+    32
+
+    >>> data = [20, 40, 24, 32, 20, 28, 16]
+    >>> list(convolve(data, [0.25, 0.25, 0.25, 0.25]))
+    [5.0, 15.0, 21.0, 29.0, 29.0, 26.0, 24.0, 16.0, 11.0, 4.0]
+    >>> list(convolve(data, [1, -1]))
+    [20, 20, -16, 8, -12, 8, -12, -16]
+    >>> list(convolve(data, [1, -2, 1]))
+    [20, 0, -36, 24, -20, 20, -20, -4, 16]
+
+    >>> list(flatten([('a', 'b'), (), ('c', 'd', 'e'), ('f',), ('g', 'h', 'i')]))
+    ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i']
+
+    >>> import random
+    >>> random.seed(85753098575309)
+    >>> list(repeatfunc(random.random, 3))
+    [0.16370491282496968, 0.45889608687313455, 0.3747076837820118]
+    >>> list(repeatfunc(chr, 3, 65))
+    ['A', 'A', 'A']
+    >>> list(repeatfunc(pow, 3, 2, 5))
+    [32, 32, 32]
+
+    >>> list(grouper('abcdefg', 3, fillvalue='x'))
+    [('a', 'b', 'c'), ('d', 'e', 'f'), ('g', 'x', 'x')]
+
+    >>> it = grouper('abcdefg', 3, incomplete='strict')
+    >>> next(it)
+    ('a', 'b', 'c')
+    >>> next(it)
+    ('d', 'e', 'f')
+    >>> next(it)
+    Traceback (most recent call last):
+      ...
+    ValueError: zip() argument 2 is shorter than argument 1
+
+    >>> list(grouper('abcdefg', n=3, incomplete='ignore'))
+    [('a', 'b', 'c'), ('d', 'e', 'f')]
+
+    >>> list(triplewise('ABCDEFG'))
+    [('A', 'B', 'C'), ('B', 'C', 'D'), ('C', 'D', 'E'), ('D', 'E', 'F'), ('E', 'F', 'G')]
+
+    >>> list(sliding_window('ABCDEFG', 4))
+    [('A', 'B', 'C', 'D'), ('B', 'C', 'D', 'E'), ('C', 'D', 'E', 'F'), ('D', 'E', 'F', 'G')]
+
+    >>> list(roundrobin('abc', 'd', 'ef'))
+    ['a', 'd', 'e', 'b', 'f', 'c']
+
+    >>> def is_odd(x):
+    ...     return x % 2 == 1
+
+    >>> evens, odds = partition(is_odd, range(10))
+    >>> list(evens)
+    [0, 2, 4, 6, 8]
+    >>> list(odds)
+    [1, 3, 5, 7, 9]
+
+    >>> it = iter('ABCdEfGhI')
+    >>> all_upper, remainder = before_and_after(str.isupper, it)
+    >>> ''.join(all_upper)
+    'ABC'
+    >>> ''.join(remainder)
+    'dEfGhI'
+
+    >>> list(powerset([1,2,3]))
+    [(), (1,), (2,), (3,), (1, 2), (1, 3), (2, 3), (1, 2, 3)]
+
+    >>> all(len(list(powerset(range(n)))) == 2**n for n in range(18))
+    True
+
+    >>> list(powerset('abcde')) == sorted(sorted(set(powerset('abcde'))), key=len)
+    True
+
+    >>> list(unique_everseen('AAAABBBCCDAABBB'))
+    ['A', 'B', 'C', 'D']
+
+    >>> list(unique_everseen('ABBCcAD', str.lower))
+    ['A', 'B', 'C', 'D']
+
+    >>> list(unique_justseen('AAAABBBCCDAABBB'))
+    ['A', 'B', 'C', 'D', 'A', 'B']
+
+    >>> list(unique_justseen('ABBCcAD', str.lower))
+    ['A', 'B', 'C', 'A', 'D']
+
+    >>> d = dict(a=1, b=2, c=3)
+    >>> it = iter_except(d.popitem, KeyError)
+    >>> d['d'] = 4
+    >>> next(it)
+    ('d', 4)
+    >>> next(it)
+    ('c', 3)
+    >>> next(it)
+    ('b', 2)
+    >>> d['e'] = 5
+    >>> next(it)
+    ('e', 5)
+    >>> next(it)
+    ('a', 1)
+    >>> next(it, 'empty')
+    'empty'
+
+    >>> first_true('ABC0DEF1', '9', str.isdigit)
+    '0'
+
+    >>> population = 'ABCDEFGH'
+    >>> for r in range(len(population) + 1):
+    ...     seq = list(combinations(population, r))
+    ...     for i in range(len(seq)):
+    ...         assert nth_combination(population, r, i) == seq[i]
+    ...     for i in range(-len(seq), 0):
+    ...         assert nth_combination(population, r, i) == seq[i]
+
+    >>> iterable = 'abcde'
+    >>> r = 3
+    >>> combos = list(combinations(iterable, r))
+    >>> all(nth_combination(iterable, r, i) == comb for i, comb in enumerate(combos))
+    True