Python Reference ยท Standard Library: Data Structures and Functional Tools
The itertools module
Reference for Python's itertools module: count, cycle, chain, islice, groupby, accumulate, batched, pairwise, zip_longest, tee and the lazy-iterator pitfalls.
itertools is a toolbox of fast, memory-friendly iterator builders. Each function returns a lazy iterator, so nothing is computed until you loop over it, and you can chain them to process huge or even infinite streams without building lists.
The combinatoric functions (product, permutations, combinations) have their own page: itertools combinatoric functions.
from itertools import chain, islice print(list(islice(chain("ab", "cd"), 3))) # ['a', 'b', 'c']
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Syntax
from itertools import count, cycle, chain, islice, groupby
| Function | Description |
|---|---|
count(start=0, step=1) |
Infinite counter. |
cycle(iterable) |
Repeats the items forever (stores a copy of the first pass). |
repeat(x, times=None) |
Yields x endlessly, or times times. |
chain(*iterables), chain.from_iterable(it) |
Concatenates iterables lazily. |
islice(it, stop) or islice(it, start, stop, step=1) |
Slice any iterator; no negative values. |
accumulate(it, func=operator.add, *, initial=None) |
Running totals (or any binary function). |
pairwise(it) |
Overlapping pairs (a, b), (b, c)... (3.10+). |
batched(it, n) |
Tuples of n items; the last may be shorter (3.12+; strict=True in 3.13+ raises on a short batch). |
groupby(it, key=None) |
Groups consecutive items with equal keys, as (key, group_iterator). |
zip_longest(*its, fillvalue=None) |
Like zip but runs until the longest ends. |
takewhile, dropwhile, filterfalse, compress, starmap, tee |
Filtering and utility helpers. |
Return value: an iterator (never a list). Raises: TypeError when an argument is not iterable; ValueError for invalid islice bounds or batched(it, 0).
Usage notes
- Everything is lazy and single-use. Once an iterator is consumed it is empty; wrap in
list()to keep the results, as the last example shows. groupbyneeds sorted input. It only groups neighbors, sosorted(data, key=key)first if you want one group per key. Each group is also invalidated as soon as you advance to the next one: convert it withlist(group)before moving on.- Infinite iterators need a stopper. Combine
count(),cycle()orrepeat()withislice,takewhile,zipor abreak.list(count())never finishes. teehas a cost. It buffers items one copy has seen and the other has not. If you advance only one copy a long way, memory grows; usuallylist()is simpler.isliceconsumes items it skips, and it cannot go backward or accept negative indexes.chain.from_iterableaccepts a single iterable of iterables, and works with generators (a flatten-one-level idiom).- Prefer comprehensions for simple transforms; itertools wins when you need streaming, composition or speed.
- Version notes:
pairwisearrived in 3.10,batchedin 3.12. On older versions write them withzipandislice.