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.
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.
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.
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.
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.
word blue sky cloud winter falcon
The words.txt file has a header line followed by words.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
List all Python tutorials.