itertools module

The itertools module provides a set of functions that create iterators.

Some of these functions work in similar ways to the built-in functions on iterables, in particular the transforming and reducing functions. You may want to read that article if you are not familiar with map, filter, zip and sum. The itertools library generally extends the capabilities of the built-in functions.

This article covers all the functions in the itertools module, with examples. The functions are divided into groups that cover similar functionality:

• General iterators - mainly variants on the built-in functions
  • Map-like iterators - starmap.
  • Filter-like iterators - filterfalse, dropwhile, takewhile, compress, and isslice.
  • Zip-like iterators - chain, chain.from_iterable, and zip_longest.
  • Splitting iterators - tee and groupby.
  • Accumulating iterators - accumulate.
• Infinite iterators - count, cycle, and repeat.
• Combinatoric iterators - product, permutations, combinations and combinations_with_replacement.

All these functions are contained in the itertools module, so you always import this module to use the functions. We haven't shown this in all the examples, to avoid repetition, but you should include the import at the top of every example if you want to run them.

Using iterators

The itertools library, as its name suggests, works with iterables and iterators. See the iterators vs iterables article if you are not familiar with these.

Generally, the inputs to itertools functions are iterable objects. This means that they can accept lists, tuples, and strings, because those objects behave as iterables. They can also accept iterator objects because every iterator also behaves as an iterable. This means that you can chain itertools functions in various ways.

itertools functions always return an iterator. An iterator is a lazy object that only calculates values when it needs to. Here is an example:

import itertools

r = itertools.repeat(5, 3)

print(r)

for i in r:
    print(i)

The repeat function generates a stream of 3 elements, each with value 5. However, it doesn't generate those values immediately. Instead, it creates a lazy iterator.

When we call print(r), we see the following:

repeat(5, 3)

This is because r holds a repeat object rather than a sequence of values. The repeat object is a type of iterator.

We can loop over an iterator using a for loop, in the same way that we might loop over a list. The iterator r will return the value 5, three times, and then the loop will terminate. This means that the loop will print 5, three times, then exit.

Converting an iterator to a list

Another useful thing we can do with an iterator is to convert it to a list:

r = itertools.repeat(5, 3)

k = list(r)
print(k)

The first this to know is that when we previously looped over the iterator r we effectively "used up" the values in it. So the iterator has no values left. In this code, we must first call repeat again, to create a brand new iterator.

When we pass this to the list function a new list is created. The list function gets all the values from the iterator (internally it does something like the for loop above) and uses the values to create a new list. We can then print the list just like any other list.

Once again, this code uses up the iterator r, but of course the values in the list can be accessed as often as you wish. It is just a normal list.

See also

• itertools module - general iterators
• itertools module - infinite iterators
• itertools module - combinatoric iterators
• itertools module - cartesian product
• itertools module - permutations
• itertools module - combinations