ZetCode

Python iterator

last modified November 16, 2026 Python 3.15

In this article we show how to work with iterators in Python.

Iteration is the process of going through the items of a collection one by one. An iterable is an object that can be iterated over: lists, tuples, strings, dictionaries, sets, files, and ranges are iterables. An iterator is an object that produces the successive values of an iterable and remembers its position.

The iterator protocol consists of two special methods. An iterable implements __iter__, which returns a new iterator. An iterator implements __next__, which returns the next item or raises StopIteration when there are no more items, and __iter__, which returns the iterator itself. The built-in iter and next functions call these methods.

Iterators produce values on demand. This makes the code simpler, saves memory, because the items do not have to exist all at once, and allows working with infinite sequences.

A simple example

The following example takes an iterator from a string and reads its items with the next function.

simple_it.py
text = 'falcon'

it = iter(text)

print(next(it))
print(next(it))
print(next(it))
print(list(it))

try:
    next(it)
except StopIteration:
    print('no more items')

print(next(it, 'default'))

The iter function returns an iterator over the characters of the string. Each next call returns one character and moves the iterator forward.

print(list(it))

The list function takes the remaining items. The iterator is then exhausted.

try:
    next(it)
except StopIteration:
    print('no more items')

print(next(it, 'default'))

Calling next on an exhausted iterator raises StopIteration. With a second argument, next returns that default value instead.

$ python simple_it.py
f
a
l
['c', 'o', 'n']
no more items
default

How the for loop works

The for loop is built on the iterator protocol. It calls iter on the iterable, calls next repeatedly, and ends when StopIteration is raised.

for_loop.py
vals = ['sky', 'cloud', 'rain']

for val in vals:
    print(val, end=' ')
print()

it = iter(vals)
while True:
    try:
        val = next(it)
    except StopIteration:
        break
    print(val, end=' ')
print()

The while loop does by hand what the for loop does for us. Both loops print the same words.

$ python for_loop.py
sky cloud rain 
sky cloud rain 

Iterables and iterators

An iterable can be iterated many times, because each iter call returns a new, independent iterator. An iterator can be traversed only once.

iterable_iterator.py
vals = [1, 2, 3]

it = iter(vals)

print(type(vals).__name__, type(it).__name__)
print(hasattr(vals, '__next__'), hasattr(it, '__next__'))
print(iter(vals) is iter(vals))
print(iter(it) is it)

print(list(it))
print(list(it))
print(list(vals), list(vals))

A list has no __next__ method; it is an iterable, not an iterator. Two iter calls on a list give two different list_iterator objects, while iter on an iterator returns the iterator itself. This is why an iterator can be used in a for loop.

print(list(it))
print(list(it))

The second list call returns an empty list, because the iterator is exhausted. The list itself can be converted again and again.

$ python iterable_iterator.py
list list_iterator
False True
False
True
[1, 2, 3]
[]
[1, 2, 3] [1, 2, 3]

Functions that consume iterables

Many built-in functions accept any iterable and consume its items: the list, tuple, set, and dict constructors, sorted, sum, max, min, and str.join. Note that some iterables can be very large, or infinite.

iterator_builtins.py
text = 'an old falcon'

print(list(text))
print(tuple(text))
print(sorted(set(text)))
print(''.join(dict.fromkeys(text)))
print(max(text), min(text), sum(map(ord, text)))
print('f' in iter(text))

We build a list, a tuple, and a sorted list of unique characters from a string. The dict.fromkeys call removes duplicates while keeping the order of first occurrence. The in operator also works with an iterator; it consumes items until it finds a match.

$ python iterator_builtins.py
['a', 'n', ' ', 'o', 'l', 'd', ' ', 'f', 'a', 'l', 'c', 'o', 'n']
('a', 'n', ' ', 'o', 'l', 'd', ' ', 'f', 'a', 'l', 'c', 'o', 'n')
[' ', 'a', 'c', 'd', 'f', 'l', 'n', 'o']
an oldfc
o   1217
True

Reading lines from a file

A file object is an iterator over the lines of the file. Reading a file in a loop takes one line at a time, without loading the whole file into memory.

words.txt
word
blue
sky
cloud
winter
falcon

The words.txt file has a header line followed by words.

read_lines.py
with open('words.txt') as f:
    header = next(f).rstrip()
    print('header:', header)

    for n, line in enumerate(f, 1):
        print(n, line.rstrip())

    print(f is iter(f))

Because the file object is an iterator, we can call next on it to read and skip the header line. The for loop then continues from the second line. The enumerate function numbers the lines.

$ python read_lines.py
header: word
1 blue
2 sky
3 cloud
4 winter
5 falcon
True

A custom iterator

To create a custom iterator, we define a class with the __iter__ and __next__ methods.

inf_seq.py
class InfSeq:

    def __init__(self):
        self.x = 0

    def __iter__(self):
        return self

    def __next__(self):
        self.x += 1
        return self.x ** self.x


for n, e in enumerate(InfSeq()):
    if n == 10:
        break
    print(e, end=' ')
print()

The iterator produces the infinite sequence 1, 4, 27, 256, ..., where each item is x ** x.

def __iter__(self):
    return self

The for statement calls __iter__ to obtain the iterator. An iterator returns itself.

def __next__(self):
    self.x += 1
    return self.x ** self.x

The __next__ method computes the next item. It never raises StopIteration, so the sequence is infinite.

for n, e in enumerate(InfSeq()):
    if n == 10:
        break

Because we are working with an infinite sequence, we must interrupt the loop at some point.

$ python inf_seq.py
1 4 27 256 3125 46656 823543 16777216 387420489 10000000000 

Separating the iterable from the iterator

An object that is its own iterator can be traversed only once. A container that should be iterable many times returns a new iterator object from its __iter__ method.

countdown.py
class Countdown:

    def __init__(self, start):
        self.start = start

    def __iter__(self):
        return CountdownIterator(self.start)


class CountdownIterator:

    def __init__(self, n):
        self.n = n

    def __iter__(self):
        return self

    def __next__(self):
        if self.n <= 0:
            raise StopIteration
        self.n -= 1
        return self.n + 1


c = Countdown(3)

print(list(c))
print(list(c))

for a in c:
    for b in c:
        print(f'{a}{b}', end=' ')
print()

The Countdown class is an iterable; the state of the iteration lives in CountdownIterator. Each loop gets its own iterator, so we can convert the object to a list twice and even nest two loops over the same object.

$ python countdown.py
[3, 2, 1]
[3, 2, 1]
33 32 31 23 22 21 13 12 11 

Ending the iteration with StopIteration

A finite iterator ends the iteration by raising the StopIteration exception.

random_words.py
import random


class RandomWords:

    words = ['sky', 'blue', 'cloud', 'milk', 'cosmos', 'rainbow', 'drop',
             'new', 'stop']

    def __init__(self, seed):
        self.rnd = random.Random(seed)

    def __iter__(self):
        return self

    def __next__(self):
        word = self.rnd.choice(self.words)
        if word == 'stop':
            raise StopIteration
        return word


for word in RandomWords(4):
    print(word)

The iterator produces random words until the word stop is picked. We use a random.Random instance with a fixed seed, so the program gives the same words on every run.

$ python random_words.py
milk
cosmos
blue
drop
new
cloud
blue
blue
sky
drop

Generators

Writing iterator classes is rarely necessary. A generator function is a function with a yield statement; calling it returns a generator, which is an iterator. The function body runs until the next yield each time next is called, and its local variables keep their values between calls.

generator_fun.py
def countdown(n):
    while n > 0:
        yield n
        n -= 1


def powers():
    x = 1
    while True:
        yield x ** x
        x += 1


g = countdown(3)
print(type(g).__name__, iter(g) is g)
print(next(g), next(g), next(g))
print(next(g, 'done'))

p = powers()
print([next(p) for _ in range(6)])

The countdown generator does the same work as the two classes in the previous examples. When the function returns, the generator raises StopIteration. The powers generator is an infinite generator equivalent to the InfSeq class.

$ python generator_fun.py
generator True
3 2 1
done
[1, 4, 27, 256, 3125, 46656]

Generator expressions

A generator expression looks like a list comprehension in parentheses. It creates a generator, which computes the values lazily.

gen_expr.py
import sys

squares_list = [x * x for x in range(1_000_000)]
squares_gen = (x * x for x in range(1_000_000))

print(sys.getsizeof(squares_list))
print(sys.getsizeof(squares_gen))

print(sum(x * x for x in range(1_000_000)))
print(next(squares_gen), next(squares_gen))

The list of a million squares takes over 8 MB, while the generator object takes a few hundred bytes, regardless of the number of items. When a generator expression is the only argument of a function, the extra parentheses can be omitted, as in the sum call.

$ python gen_expr.py
8448728
216
333332833333500000
0 1

The iter function with a sentinel

With two arguments, iter(callable, sentinel) creates an iterator that calls the function until it returns the sentinel value.

iter_sentinel.py
import functools
import io
import random

rnd = random.Random(7)
roll = functools.partial(rnd.randint, 1, 6)

print(list(iter(roll, 6)))

stream = io.BytesIO(b'abcdefghijklmnopqrstuvwxyz')

for chunk in iter(functools.partial(stream.read, 8), b''):
    print(chunk)

The first iterator rolls a die until a six comes up. The second one reads a binary stream in chunks of eight bytes until read returns an empty bytes object, which marks the end of the stream. This idiom is common when reading files in fixed-size blocks.

$ python iter_sentinel.py
[3, 2, 4]
b'abcdefgh'
b'ijklmnop'
b'qrstuvwx'
b'yz'

The sequence protocol

If a class has no __iter__ method but implements __getitem__, the iter function creates an iterator that calls __getitem__ with indexes 0, 1, 2, ... until it raises IndexError.

getitem_seq.py
class Squares:

    def __init__(self, n):
        self.n = n

    def __getitem__(self, i):
        if i >= self.n:
            raise IndexError(i)
        return i * i


s = Squares(5)

print(list(s))
print(9 in s)
print(type(iter(s)).__name__)

The Squares object works in a list call and with the in operator, although it does not define __iter__.

$ python getitem_seq.py
[0, 1, 4, 9, 16]
True
iterator

Lazy built-in functions

The zip, map, filter, enumerate, and reversed built-in functions return iterators. They do no work until we ask for the items.

lazy_builtins.py
names = ['Paul', 'Lucy', 'Robert']
ages = [34, 28, 52]

z = zip(names, ages)
m = map(str.upper, names)
e = enumerate(names, start=1)

print(type(z).__name__, type(m).__name__, type(e).__name__)
print(list(z), list(m), list(e), sep='\n')
print(list(z))

r = reversed(names)
print(next(r), list(r))

try:
    list(zip(names, ages[:2], strict=True))
except ValueError as err:
    print(err)

The functions return zip, map, and enumerate objects. After we convert them to lists, they are exhausted, so the second list(z) call returns an empty list.

list(zip(names, ages[:2], strict=True))

By default, zip stops at the shortest iterable. With strict=True, it raises ValueError when the lengths differ.

$ python lazy_builtins.py
zip map enumerate
[('Paul', 34), ('Lucy', 28), ('Robert', 52)]
['PAUL', 'LUCY', 'ROBERT']
[(1, 'Paul'), (2, 'Lucy'), (3, 'Robert')]
[]
Robert ['Lucy', 'Paul']
zip() argument 2 is shorter than argument 1

Iterator exhaustion pitfall

A common bug is to use an iterator twice, expecting it to behave like a list.

exhaustion.py
data = map(int, ['1', '2', '3', '4'])

print(2 in data)
print(list(data))

nums = (n for n in range(5))
total = sum(nums)
count = len(list(nums))
print(total, count)

nums = list(n for n in range(5))
print(sum(nums), len(nums))

The in test consumes the items up to the match, so list(data) returns only the remaining numbers. The sum call exhausts the generator, so the count is zero. If we need the data more than once, we store it in a list first.

$ python exhaustion.py
True
[3, 4]
10 0
10 5

The itertools module

The itertools module contains functions that create and combine iterators.

itertools_demo.py
from itertools import (batched, chain, count, cycle, islice, pairwise,
                       takewhile, tee)

print(list(islice(count(10, 5), 4)))
print(list(islice(cycle('ab'), 5)))
print(list(chain([1, 2], 'xy', range(2))))
print(list(batched(range(7), 3)))
print(list(pairwise([1, 4, 9, 16])))
print(list(takewhile(lambda x: x < 10, count(1, 3))))

a, b = tee(iter([1, 2, 3]))
print(list(a), list(b))

The count and cycle functions create infinite iterators, which we cut with islice. The chain function joins iterables, batched (Python 3.12) groups items into tuples, pairwise returns overlapping pairs, and takewhile takes items while a condition holds. The tee function splits one iterator into two independent ones.

$ python itertools_demo.py
[10, 15, 20, 25]
['a', 'b', 'a', 'b', 'a']
[1, 2, 'x', 'y', 0, 1]
[(0, 1, 2), (3, 4, 5), (6,)]
[(1, 4), (4, 9), (9, 16)]
[1, 4, 7]
[1, 2, 3] [1, 2, 3]

Checking for iterables

The collections.abc module defines the Iterable, Iterator, and Generator abstract base classes, which can be used with isinstance.

abc_check.py
from collections.abc import Generator, Iterable, Iterator


class Squares:

    def __getitem__(self, i):
        if i >= 3:
            raise IndexError
        return i * i


def gen():
    yield 1


for obj in ([1], iter([1]), gen(), 'abc', 42, Squares()):
    print(f'{type(obj).__name__:15} {isinstance(obj, Iterable)!s:6} '
          f'{isinstance(obj, Iterator)!s:6} {isinstance(obj, Generator)}')

for obj in (42, Squares()):
    try:
        iter(obj)
        print(type(obj).__name__, 'is iterable')
    except TypeError as e:
        print(e)

The Iterable check looks for the __iter__ method, so it does not recognize the Squares class, which is iterable through __getitem__. The only reliable test is to call iter and catch TypeError.

$ python abc_check.py
list            True   False  False
list_iterator   True   True   False
generator       True   True   True
str             True   False  False
int             False  False  False
Squares         False  False  False
'int' object is not iterable
Squares is iterable

Asynchronous iterators

Asynchronous iterators are used in async for loops. They implement __aiter__ and the __anext__ coroutine, which raises StopAsyncIteration at the end. An async generator is an async def function with yield.

async_iter.py
import asyncio


class Ticker:

    def __init__(self, n):
        self.n = n
        self.i = 0

    def __aiter__(self):
        return self

    async def __anext__(self):
        if self.i >= self.n:
            raise StopAsyncIteration
        await asyncio.sleep(0.1)
        self.i += 1
        return self.i


async def countdown(n):
    while n > 0:
        await asyncio.sleep(0.1)
        yield n
        n -= 1


async def main():
    async for t in Ticker(3):
        print('tick', t)
    print([n async for n in countdown(3)])
    it = aiter(Ticker(2))
    print(await anext(it), await anext(it), await anext(it, 'end'))


asyncio.run(main())

The Ticker class and the countdown async generator wait before producing each value. The aiter and anext built-in functions are the asynchronous counterparts of iter and next.

$ python async_iter.py
tick 1
tick 2
tick 3
[3, 2, 1]
1 2 end

Source

Iterator types – Python documentation

itertools – Functions creating iterators for efficient looping

In this article we have worked with iterators in Python. See also Python generators and Python for loop.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Python tutorials.