Implementing Python Iterator Protocol

Python
class Countdown:
    """An iterable that returns a fresh iterator each time."""
    def __init__(self, start):
        self.start = start

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

class CountdownIterator:
    """The actual iterator: stateful, implements __next__."""
    def __init__(self, current):
        self.current = current

    def __iter__(self):
        return self  # iterators must be iterable too

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

for n in Countdown(3):
    print(n)  # 3 2 1

Simpler version using a generator function (preferred in almost all real code):

Python
def countdown(start):
    while start > 0:
        yield start
        start -= 1

Progress:

• Determine if you need a reusable iterable (supports multiple independent iterations) or a one-shot iterator
• Choose implementation style: generator function, generator expression, or explicit class
• Implement __iter__ (and __next__ if a class-based iterator)
• Ensure StopIteration is raised correctly (or let generator return naturally)
• Verify with iter(), next(), and a for loop
• If stateful resource cleanup is needed, consider a context manager instead/alongside

Core distinction

• Iterable: has __iter__() returning an iterator. Can be iterated over repeatedly, each time producing a new iterator.
• Iterator: has both __iter__() (returning itself) and __next__() (returning next value or raising StopIteration). Exhausted after one full pass — cannot restart.

Rule of thumb: containers are iterables, not iterators. If __iter__ returns self, the object is single-use.

Choosing an implementation

1. Generator function (yield) — default choice. Automatically implements the full protocol; state is managed by the interpreter via the frame.
2. Generator expression — for simple one-liner transformations of an existing iterable: (x*x for x in range(10)).
3. Explicit class — only when you need:
   • A reusable iterable (separate __iter__ returning fresh iterator state each call)
   • Extra methods/attributes on the iterator itself
   • Fine control not expressible with yield (rare)

Example 1: Iterable vs iterator bug

Input:

Python
class Numbers:
    def __init__(self, data):
        self.data = data
        self.i = 0

    def __iter__(self):
        return self

    def __next__(self):
        if self.i >= len(self.data):
            raise StopIteration
        v = self.data[self.i]
        self.i += 1
        return v

nums = Numbers([1, 2, 3])
print(list(nums))
print(list(nums))  # second call — what happens?

Output:

[1, 2, 3]
[]

Explanation: Numbers is its own iterator (__iter__ returns self), so it's exhausted after the first pass. Fix by separating iterable state (data) from iterator state (i) into two classes, or by making __iter__ return a fresh generator: def __iter__(self): return iter(self.data).

Example 2: Infinite iterator with manual protocol

Input:

Python
def take(iterable, n):
    it = iter(iterable)
    result = []
    for _ in range(n):
        result.append(next(it))
    return result

def naturals():
    n = 1
    while True:
        yield n
        n += 1

take(naturals(), 5)

Output: [1, 2, 3, 4, 5]

Example 3: Using next() with a default to avoid StopIteration

Input:

Python
it = iter([])
value = next(it, "empty")

Output: "empty" (no exception raised)