Python Iterators

Python Iterators: Iterator Protocol, Iterables, & Generators

An iterable is an object capable of returning its members one at a time (implements __iter__()). An iterator is an object that keeps state and yields values sequentially via __next__(), raising StopIteration when elements are exhausted.

Iterator Protocol Flow

flowchart LR
    A["Iterable Object"] -->|iter()| B["Iterator Object"]
    B -->|next()| C{"Has Next Item?"}
    C -- "Yes" --> D["Return Value"] --> B
    C -- "No" --> E["Raise StopIteration Exception"]

Protocol Protocol Methods

1. __iter__(): Returns the iterator object itself.
2. __next__(): Returns the next value from the sequence; raises StopIteration when empty.

Practical Code Example

from typing import Iterator

class CountDown:
    """Custom Iterator counting down from a given start number."""
    def __init__(self, start: int) -> None:
        self.current = start

    def __iter__(self) -> Iterator[int]:
        return self

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

# Generator Function equivalent using yield
def countdown_generator(start: int) -> Iterator[int]:
    while start > 0:
        yield start
        start -= 1

if __name__ == "__main__":
    print("--- Custom Class Iterator ---")
    for num in CountDown(3):
        print(num)

    print("--- Yield Generator Function ---")
    for num in countdown_generator(3):
        print(num)

Best Practices & Gotchas

• Iterators are Exhaustible: Once an iterator raises StopIteration, it is empty; attempting to iterate over it again yields no items.
• Prefer Generators (yield): Creating custom iterators using generator functions (yield) requires far less boilerplate than writing custom class iterators.
• Memory Efficiency: Generators evaluate values lazily on demand, making them ideal for processing large files or infinite streams.

Self-Check Challenge

Write a generator function even_numbers(max_limit: int) using yield that yields all even numbers from 0 up to max_limit.