Skip to content

Iterators and Iterables

Understand the iterator protocol: __iter__, __next__, iter(), next(), and custom iterables.

What you'll learn

  • Distinguish iterables from iterators
  • Implement the iterator protocol with __iter__ and __next__
  • Use iter() and next() built-in functions
  • Create custom iterable classes
  • Leverage itertools for advanced iteration

Concept

Iterables vs Iterators

An iterable is any object you can loop over with for — lists, strings, dicts, sets, files, generators. An iterator is the object that actually produces the values during iteration.

  • Iterable — has an __iter__() method that returns an iterator
  • Iterator — has an __next__() method that returns the next value, and an __iter__() that returns itself
my_list = [1, 2, 3]       # iterable
my_iter = iter(my_list)   # get an iterator from the iterable

print(next(my_iter))  # 1
print(next(my_iter))  # 2
print(next(my_iter))  # 3
print(next(my_iter))  # StopIteration!

Every time you write a for loop, Python calls iter() on the iterable to get an iterator, then calls next() repeatedly until StopIteration is raised.

The for Loop Under the Hood

# This for loop:
for item in [1, 2, 3]:
    print(item)

# Is equivalent to:
_iter = iter([1, 2, 3])
while True:
    try:
        item = next(_iter)
        print(item)
    except StopIteration:
        break

Understanding this protocol demystifies how for loops work and lets you create your own iterables.

Creating a Custom Iterator

Implement __iter__() and __next__() to make any class iterable:

class CountDown:
    def __init__(self, start):
        self.current = start

    def __iter__(self):
        return self  # the object is its own iterator

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

# Use it in a for loop
for n in CountDown(5):
    print(n)  # 5, 4, 3, 2, 1

__iter__ returns the iterator object (often self). __next__ returns the next value or raises StopIteration when done. Once StopIteration is raised, the iterator is exhausted and cannot be reused.

Separate Iterable and Iterator

To allow multiple independent iterations, separate the iterable (the container) from the iterator (the cursor):

class Range2:
    """An iterable that can be iterated multiple times."""
    def __init__(self, start, stop):
        self.start = start
        self.stop = stop

    def __iter__(self):
        # Return a NEW iterator each time
        return Range2Iterator(self.start, self.stop)

class Range2Iterator:
    def __init__(self, start, stop):
        self.current = start
        self.stop = stop

    def __iter__(self):
        return self

    def __next__(self):
        if self.current >= self.stop:
            raise StopIteration
        value = self.current
        self.current += 1
        return value

r = Range2(1, 4)
print(list(r))  # [1, 2, 3]
print(list(r))  # [1, 2, 3] — works again because __iter__ creates a new iterator

This is how built-in types like list and range work — each for loop creates a fresh iterator.

iter() and next() Built-ins

# iter() — get an iterator
it = iter([1, 2, 3])

# next() — get the next value
print(next(it))  # 1

# next() with a default — no StopIteration
print(next(it, "done"))  # 2
print(next(it, "done"))  # 3
print(next(it, "done"))  # "done" (default, no exception)

# iter() with a sentinel — call a function until it returns the sentinel
import random
rolls = iter(lambda: random.randint(1, 6), 6)  # roll dice until we get 6
print(list(rolls))  # e.g., [3, 1, 5, 2] — stops before the 6

The two-argument form iter(callable, sentinel) calls the function repeatedly until it returns the sentinel value — useful for reading lines until EOF.

itertools — Powerful Iteration Tools

The itertools module provides a toolkit of iterator-building functions:

from itertools import (
    chain,           # combine iterables
    product,         # cartesian product
    combinations,    # all combinations of size k
    permutations,    # all orderings
    islice,          # slice an iterator
    groupby,         # group consecutive elements
    cycle,           # repeat forever
    count,           # infinite counter
    accumulate,      # running totals
)

# chain — combine multiple iterables
print(list(chain([1, 2], [3, 4], [5])))  # [1, 2, 3, 4, 5]

# product — cartesian product
print(list(product([1, 2], ["a", "b"])))
# [(1, 'a'), (1, 'b'), (2, 'a'), (2, 'b')]

# combinations
print(list(combinations("ABCD", 2)))
# [('A','B'), ('A','C'), ('A','D'), ('B','C'), ('B','D'), ('C','D')]

# accumulate — running totals
print(list(accumulate([1, 2, 3, 4, 5])))  # [1, 3, 6, 10, 15]

itertools functions are lazy — they produce values on demand, making them memory-efficient for large or infinite sequences.

Checking Iterability

from collections.abc import Iterable

print(isinstance([1, 2, 3], Iterable))  # True
print(isinstance(42, Iterable))          # False
print(isinstance("hello", Iterable))     # True

Use collections.abc.Iterable to check if an object is iterable. This is more robust than trying iter(obj) and catching TypeError.

Example

              # iter() and next() basics
my_list = [10, 20, 30]
my_iter = iter(my_list)
print(next(my_iter))  # 10
print(next(my_iter))  # 20
print(next(my_iter))  # 30

# next() with default — avoids StopIteration
empty = iter([])
print(next(empty, "exhausted"))  # exhausted

# Custom iterator class
class CountDown:
    def __init__(self, start):
        self.current = start

    def __iter__(self):
        return self

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

print("Countdown:")
for n in CountDown(5):
    print(f"  {n}")

# itertools — powerful iteration tools
from itertools import chain, product, combinations, accumulate, islice, count

# chain — combine iterables
print(f"Chained: {list(chain([1, 2], [3, 4]))}")

# product — cartesian product
print(f"Product: {list(product([1, 2], ['a', 'b']))}")

# combinations
print(f"Combos: {list(combinations('ABC', 2))}")

# accumulate — running totals
print(f"Accumulate: {list(accumulate([1, 2, 3, 4]))}")

# islice — take first N from an infinite iterator
print(f"First 5 of count(): {list(islice(count(10), 5))}")

# iter() with sentinel — read until a value
data = iter([1, 2, 3, 0, 4, 5])
before_zero = list(iter(lambda: next(data), 0))
print(f"Before zero: {before_zero}")  # [1, 2, 3]

# Check if iterable
from collections.abc import Iterable
print(f"List is iterable: {isinstance([1, 2], Iterable)}")
print(f"Int is iterable: {isinstance(42, Iterable)}")
            

Shows iter()/next() basics, a custom CountDown iterator, itertools functions (chain, product, combinations, accumulate, islice, count), the sentinel form of iter(), and isinstance check for iterability.

Try it

  • Text Counter

    Iterating over text characters and words uses the iterator protocol.

  • JSON Formatter

    JSON arrays and objects are iterables — process them with iterators.

Common mistakes

The mistake

Confusing iterables with iterators and trying to call next() on a list

The fix

A list is an iterable, not an iterator. Call iter() first to get an iterator: it = iter(my_list), then next(it). The for loop does this automatically. Only iterators have __next__; iterables only have __iter__.

The mistake

Making __iter__ return self, which makes the object single-use (cannot iterate twice)

The fix

If __iter__ returns self, the iterator is exhausted after one pass. To allow multiple iterations, __iter__ should return a NEW iterator object each time. This is how list and range work — each for loop gets a fresh iterator.

Related Cheatsheets

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors