Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Statements and Keywords

Python iterators and generators

Reference for the Python iterator protocol: iterables, iterators, StopIteration, generator functions, generator expressions, yield from and send().

An iterable is any object you can loop over; an iterator is the object that does the looping and remembers its position. A for loop calls iter() on the iterable to get an iterator, then calls next() on it until it raises StopIteration.

A generator is the easiest way to write an iterator: a function containing yield returns a generator object, and each next() runs the function until the next yield. Generator expressions, like (n * n for n in nums), are the one-line form.

Python
it = iter([10, 20])
print(next(it), next(it))   # 10 20

Try it

Python What a for loop does

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.

Python Generators

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

Python
iterator = iter(iterable)
item = next(iterator)

def gen():
    yield value
    x = yield value
    yield from other_iterable
    return result

expr = (item for item in iterable if condition)
Name Description
iter(obj) Returns an iterator for an iterable (calls obj.__iter__()).
next(it[, default]) Returns the next item (calls it.__next__()); with default, returns it instead of raising StopIteration.
yield value Pauses the generator and hands value to the caller.
yield from x Delegates to another iterable and yields all its items; its return value becomes the value of the expression.
gen.send(v) Resumes the generator, making the paused yield evaluate to v.
gen.throw(exc) / gen.close() Raises an exception at the paused yield / stops the generator.

Raises: StopIteration when an iterator has no more items. A generator's return value ends it and puts the value on the StopIteration.

Usage notes

  • An iterator is also iterable. Its __iter__() returns itself, so for works on both. Lists, strings, dicts and files are iterables, not iterators: each iter() call gives a fresh position.
  • One pass only. Once an iterator or generator is exhausted it stays empty. Create a new one to start over, as the second sum(squares) above shows.
  • Lazy evaluation. Generator code does not run until the first next(), and values are produced one at a time. That keeps memory flat for large or infinite streams.
  • send() needs a primed generator. Call next(gen) first, or send None, to reach the first yield; sending a real value to a just-created generator raises TypeError.
  • StopIteration inside a generator is converted to RuntimeError (PEP 479), so do not let it escape from a next() call inside generator code.
  • Generator expressions need parentheses unless they are the only argument of a call: sum(n for n in nums).
  • Writing your own class needs __iter__() and __next__(); a generator method for __iter__ is usually simpler.
  • Tools. The itertools module offers ready-made lazy building blocks such as islice, chain and count.