This document provides a comprehensive tutorial for the Python itertools module, based on the official documentation: https://docs.python.org/3/library/itertools.html

The itertools module provides a set of functions for creating and working with iterators. Iterators are objects that allow you to loop over a sequence of values. The itertools module provides a number of useful iterators, as well as functions for combining and manipulating iterators.

itertools.count(start=0, step=1)

This function creates an iterator that returns evenly spaced values starting with start and incrementing by step.

from itertools import count

for i in count(10, 2):
    if i > 20:
        break
    print(i)

itertools.cycle(iterable)

This function creates an iterator that cycles through the elements of iterable.

from itertools import cycle

count = 0
for item in cycle(['a', 'b', 'c']):
    if count > 7:
        break
    print(item)
    count += 1

itertools.repeat(object[, times])

This function creates an iterator that returns object over and over again. If times is specified, the iterator will return object that many times.

from itertools import repeat

for i in repeat('xyz', 3):
    print(i)

itertools.accumulate(iterable[, func, *, initial=None])

This function creates an iterator that returns accumulated sums, or accumulated results of other binary functions.

from itertools import accumulate

print(list(accumulate([1, 2, 3, 4, 5])))

from itertools import accumulate
import operator

print(list(accumulate([1, 2, 3, 4, 5], operator.mul)))

itertools.chain(*iterables)

This function takes a series of iterables and returns an iterator that returns the elements of each iterable in turn.

from itertools import chain

for i in chain([1, 2, 3], ['a', 'b', 'c']):
    print(i)

itertools.chain.from_iterable(iterable)

This function is similar to itertools.chain(), but it takes a single iterable of iterables.

from itertools import chain

def from_iterable(iterables):
    # chain.from_iterable(['ABC', 'DEF']) --> A B C D E F
    for it in iterables:
        for element in it:
            yield element

for i in from_iterable(['ABC', 'DEF']):
    print(i)

itertools.compress(data, selectors)

This function creates an iterator that filters elements from data returning only those that have a corresponding element in selectors that evaluates to True.

from itertools import compress

print(list(compress('ABCDEF', [1, 0, 1, 0, 1, 1])))

itertools.dropwhile(predicate, iterable)

This function creates an iterator that drops elements from iterable as long as the predicate is true; afterwards, returns every element.

from itertools import dropwhile

print(list(dropwhile(lambda x: x < 5, [1, 4, 6, 4, 1])))

itertools.filterfalse(predicate, iterable)

This function creates an iterator that filters elements from iterable returning only those for which the predicate is False.

from itertools import filterfalse

print(list(filterfalse(lambda x: x % 2, range(10))))

itertools.groupby(iterable, key=None)

This function creates an iterator that returns consecutive keys and groups from the iterable.

from itertools import groupby

things = [("animal", "bear"), ("animal", "duck"), ("plant", "cactus"), ("vehicle", "speed boat"), ("vehicle", "school bus")]

for key, group in groupby(things, lambda x: x[0]):
    for thing in group:
        print("A %s is a %s." % (thing[1], key))
    print("")

itertools.islice(iterable, start, stop[, step])

This function creates an iterator that returns selected elements from the iterable.

from itertools import islice

print(list(islice('ABCDEFG', 2)))

from itertools import islice

print(list(islice('ABCDEFG', 2, 4)))

from itertools import islice

print(list(islice('ABCDEFG', 2, None)))

from itertools import islice

print(list(islice('ABCDEFG', 0, None, 2)))

itertools.pairwise(iterable)

This function returns successive overlapping pairs taken from the input iterable.

from itertools import pairwise

print(list(pairwise('ABCDEFG')))

itertools.starmap(function, iterable)

This function creates an iterator that computes the function using arguments obtained from the iterable.

from itertools import starmap

print(list(starmap(pow, [(2, 5), (3, 2), (10, 3)])))

itertools.takewhile(predicate, iterable)

This function creates an iterator that returns elements from the iterable as long as the predicate is true.

from itertools import takewhile

print(list(takewhile(lambda x: x < 5, [1, 4, 6, 4, 1])))

itertools.tee(iterable, n=2)

This function returns n independent iterators from a single iterable.

from itertools import tee

# once tee() is invoked, the original iterator should not be used anywhere else
# because it might advance the iterators returned by tee()
r = islice('ABCDEFG', 2)
i1, i2 = tee(r)

print(list(i1))
print(list(i2))

itertools.zip_longest(*iterables, fillvalue=None)

This function creates an iterator that aggregates elements from each of the iterables.

from itertools import zip_longest

print(list(zip_longest('ABCD', 'xy', fillvalue='-')))

itertools.product(*iterables, repeat=1)

This function creates an iterator that returns cartesian product of input iterables.

from itertools import product

print(list(product('ABCD', repeat=2)))

from itertools import product

print(list(product(range(2), repeat=3)))

from itertools import product

rows = [['A', 'B'], ['C', 'D']]
print(list(product(*rows)))

itertools.permutations(iterable, r=None)

This function creates an iterator that returns successive r length permutations of elements in the iterable.

from itertools import permutations

print(list(permutations('ABCD', 2)))

from itertools import permutations

print(list(permutations(range(3))))

itertools.combinations(iterable, r)

This function creates an iterator that returns successive r length combinations of elements in the iterable.

from itertools import combinations

print(list(combinations('ABCD', 2)))

from itertools import combinations

print(list(combinations(range(4), 3)))

itertools.combinations_with_replacement(iterable, r)

This function creates an iterator that returns successive r length combinations with replacement of elements in the iterable.

from itertools import combinations_with_replacement

print(list(combinations_with_replacement('ABCD', 2)))

This tutorial has covered the most commonly used functions in the Python itertools module. For more information, please refer to the official documentation: https://docs.python.org/3/library/itertools.html