itertools — iterator building blocks

Python itertools helpers, including iterator consumption, groupby on adjacent keys, islice, chain, pairwise, and batched.

The itertools module is part of the Python standard library. It is not a built-in and not a third-party package. Import it with `import itertools`. The helpers return iterators, not lists. Once an iterator has been consumed, a second pass is empty unless you build a new iterator.

This page documents the consumption model, groupby, and a small set of often-used constructors. It is not a catalog of every function in the module. pairwise was added in Python 3.10 and batched in 3.12; the examples were checked on Python 3.13.

Examples were checked against Python 3.13. See the official documentation for the complete API.

Python reference overview →

Consuming iterators, islice, and chain

list(it) walks the iterator to the end. A second list(it) yields nothing. itertools functions follow the same rule: they do not rewind their input and they do not copy it unless you do so yourself.

islice(iterable, start, stop, step) selects items by position, like slicing a list, but it works on any iterable and does not materialize the rest. chain(*iterables) yields from each iterable in turn. chain.from_iterable(iterable) is the lazy form when the iterables themselves come from an iterator.

itertools.islice, itertools.chain

itertools.islice(iterable, stop)
itertools.islice(iterable, start, stop, step=1)
itertools.chain(*iterables)
itertools.chain.from_iterable(iterable)

Build a new iterator from another iterable, or from several iterables in sequence. The input is consumed as you iterate, and is not reset afterward.

ParameterDescription
iterable / iterablesThe source of values. islice and chain do not require a list; any iterable is accepted.
start, stop, stepPositions as in sequence slicing. start defaults to 0 and step defaults to 1. None for stop means "until the input is exhausted".

Returns: An iterator, not a list. Wrap the result in list() only when you need a reusable sequence.

  • After list(it), a second list(it) is empty. That is normal iterator behavior, not a bug in itertools.
  • islice(range(10), 2, 8, 2) yields 2, 4, 6. It does not include the stop index.
python
from itertools import chain, islice

it = iter([1, 2, 3])
print(list(it))
print(list(it))
print(list(islice(range(10), 2, 8, 2)))
print(list(chain([1, 2], [3], "ab")))
print(list(chain.from_iterable([[1, 2], [3]])))

Expected output

[1, 2, 3]
[]
[2, 4, 6]
[1, 2, 3, 'a', 'b']
[1, 2, 3]

Official documentation →

groupby needs adjacent keys

groupby(iterable, key=None) yields consecutive groups that share the same key. It does not collect every equal key in the whole iterable. If the input is not already grouped — usually by sorting on the same key — repeated keys that are not adjacent become separate groups.

Each group is itself an iterator that shares the underlying input with groupby. You must consume a group before moving to the next one. Storing the groupby object and listing the groups later typically yields empty lists.

itertools.groupby

itertools.groupby(iterable, key=None)

Group consecutive items that share a key. Sort first if you want all equal keys in one group, and convert each group to a list immediately if you need to keep the values.

ParameterDescription
iterableThe input items, in the order they should be grouped.
keyA function that computes the group key. If omitted or None, the item itself is the key.

Returns: An iterator of (key, group) pairs. Each group is an iterator over the underlying input, not a list.

  • [1, 1, 2, 2, 1] produces three groups, because the last 1 is not adjacent to the first two.
  • list(groupby(...)) advances the shared iterator, so later list(group) is usually empty. Build (key, list(group)) inside the loop instead.
python
from itertools import groupby

print([(key, list(group)) for key, group in groupby([1, 1, 2, 2, 1])])
print([(key, list(group)) for key, group in groupby("AAAABBBCCDAA")])

stored = list(groupby("AAAABBBCCDAA"))
print([(key, list(group)) for key, group in stored])

Expected output

[(1, [1, 1]), (2, [2, 2]), (1, [1])]
[('A', ['A', 'A', 'A', 'A']), ('B', ['B', 'B', 'B']), ('C', ['C', 'C']), ('D', ['D']), ('A', ['A', 'A'])]
[('A', []), ('B', []), ('C', []), ('D', []), ('A', [])]

Official documentation →

pairwise and batched

pairwise(iterable), added in Python 3.10, yields overlapping pairs (s0, s1), (s1, s2), and so on. batched(iterable, n), added in 3.12, yields tuples of length n; the last batch may be shorter. In Python 3.13, batched(..., strict=True) raises ValueError if the final batch is incomplete.

itertools.pairwise, itertools.batched

itertools.pairwise(iterable)
itertools.batched(iterable, n, *, strict=False)

Iterate over overlapping pairs, or over non-overlapping batches of a fixed size. Both return iterators and consume the input lazily.

ParameterDescription
iterableThe input values.
nThe target batch length. It must be at least 1.
strictIf True, raise ValueError when the final batch is shorter than n. This argument was added in Python 3.13.

Returns: An iterator of tuples.

Raises

  • ValueError — batched(..., strict=True) raises ValueError if the input length is not a multiple of n. The message is "batched(): incomplete batch".
  • These helpers do not pad the last batch. Handle a short tail yourself, or use strict=True when a short tail should be an error.
python
from itertools import batched, pairwise

print(list(pairwise("ABCD")))
print(list(batched("ABCDEFG", 3)))
try:
    print(list(batched("ABCDEFG", 3, strict=True)))
except ValueError as exc:
    print(f"{type(exc).__name__}: {exc}")

Expected output

[('A', 'B'), ('B', 'C'), ('C', 'D')]
[('A', 'B', 'C'), ('D', 'E', 'F'), ('G',)]
ValueError: batched(): incomplete batch

Official documentation →