Iterators — __iter__ & __next__

By the end of this lesson you can:

• Trace what Python does internally when running for x in seq:.
• Define a class with __iter__ and __next__ to make your own iterator.
• Use iter(obj) and next(it) manually.
• Recognise that iterators are one-shot — exhausted after one pass.

# This loop:
for x in [10, 20, 30]:
    print(x)

# Is roughly equivalent to:
it = iter([10, 20, 30])     # __iter__
while True:
    try:
        x = next(it)         # __next__
    except StopIteration:
        break
    print(x)

Two dunders, one exception. iter() turns something iterable into an iterator. next() gets the next value. StopIteration ends the loop.

Iterable vs iterator — two roles

Iterable    something you CAN iterate (list, str, set, dict, file, range...)
            Defines __iter__ — "give me a fresh iterator"

Iterator    the THING THAT REMEMBERS WHERE YOU ARE
            Defines __next__ — "give me the next value or StopIteration"
            Also defines __iter__ that returns itself

A list is an iterable. Calling iter([1,2,3]) gives you a list iterator. Two different objects.

Two manual calls

it = iter([10, 20, 30])
print(type(it))         # <class 'list_iterator'>
print(next(it))         # 10
print(next(it))         # 20
print(next(it))         # 30
print(next(it))         # StopIteration!

You never normally write next() by hand — for-loops do it for you. But seeing it explicit reveals what's happening.

Build your own — a Countdown class

class Countdown:
    """Yields n, n-1, ..., 1, then stops."""

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

    def __iter__(self):
        return self          # an iterator returns itself from __iter__

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


for x in Countdown(5):
    print(x)
# 5
# 4
# 3
# 2
# 1

Three pieces: __init__ sets up state, __iter__ returns self, __next__ returns the next value or raises StopIteration. The for-loop wires them together.

Iterators are one-shot

cd = Countdown(3)

for x in cd:
    print(x)        # 3, 2, 1

print("Again?")
for x in cd:
    print(x)        # (nothing! n is already 0)

Once an iterator is exhausted, it's done. If you need a re-iterable, separate the iterable from the iterator — define __iter__ to return a new helper iterator each time:

class Numbers:
    """Iterable — re-iterable."""
    def __init__(self, n):
        self.n = n
    def __iter__(self):
        return NumbersIter(self.n)      # fresh iterator each time

class NumbersIter:
    """One-shot iterator."""
    def __init__(self, n):
        self.n = n
        self.i = 0
    def __iter__(self):
        return self
    def __next__(self):
        if self.i >= self.n:
            raise StopIteration
        self.i += 1
        return self.i

nums = Numbers(3)
print(list(nums))       # [1, 2, 3]
print(list(nums))       # [1, 2, 3]  -- works again!

That's why list, str, etc. work twice in a row — they're iterables, each iter() call creates a fresh iterator. map and filter are iterators themselves — that's why they exhaust.

Or just use a generator (tomorrow)

The class-based approach above is verbose. Tomorrow's lesson — yield — makes the same thing one function. But the class form is essential reading because it makes the protocol concrete.

Save as fib_iter.py:

# fib_iter.py — finite Fibonacci as an iterator class

class FibUpTo:
    """Yields Fibonacci numbers up to (but not exceeding) limit."""

    def __init__(self, limit):
        self.limit = limit
        self.a = 0
        self.b = 1

    def __iter__(self):
        return self        # I am an iterator

    def __next__(self):
        if self.a > self.limit:
            raise StopIteration
        value = self.a
        self.a, self.b = self.b, self.a + self.b   # advance
        return value


# Use in a for-loop
for n in FibUpTo(100):
    print(n, end=" ")
# 0 1 1 2 3 5 8 13 21 34 55 89

# Or use with list()
print()
print(list(FibUpTo(50)))     # [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

# Or with sum
print(sum(FibUpTo(100)))     # 232

Read the diff

__next__ uses tuple swap (self.a, self.b = self.b, self.a + self.b) to advance both numbers in one line — exactly the swap idiom from PY-L2-04. The for-loop, list(), and sum() all work because they only ask __iter__ and __next__. None of them care that FibUpTo isn't a list.

Every for-loop calls iter() to get an iterator, then next() until StopIteration. An iterable defines __iter__ that returns a fresh iterator. An iterator defines __next__ that yields one value or raises StopIteration. Iterators are one-shot — they exhaust. For re-iterability, separate the iterable from the iterator. The class-based protocol works but is verbose; tomorrow's yield makes the same shape five times shorter.