Custom containers
Expose a custom collection to for loops and other iterable consumers.
Python · Module
__iter__
__iter__ is the special method Python calls when it needs an iterator for a container. Implement it to return an iterator over the container’s contents; mappings conventionally iterate over keys.
How it works
Define __iter__ on a container when iter(obj) or a for loop should traverse it. The method returns an iterator over the container’s contents; mappings conventionally yield keys, while sequences yield values.
Syntax
object.__iter__(self)Parameters
| Name | Type | Description |
|---|---|---|
self | object | The instance whose contents should be exposed through iteration. |
Returns
A new iterator object that can iterate over all objects in the container.
Key points
- Python invokes __iter__ when code needs an iterator for a container, including iteration contexts such as for loops.
- The method’s result must be an iterator capable of traversing the container’s contents.
- A mapping’s default iteration behavior should expose its keys.
- Implementing __iter__ explicitly is recommended for mappings and sequences so iteration uses the iterable protocol efficiently.
- A generator function can serve as an implementation strategy: calling it produces an iterator whose values are generated on demand.
Common mistakes
- Assigning __iter__ to None deliberately disables iteration and causes iter() to raise TypeError.
Example: Make a container iterable
class Batch:
def __init__(self, items):
self._items = tuple(items)
def __iter__(self):
return iter(self._items)
for item in Batch(["a", "b"]):
print(item)The class exposes its stored values to for loops by returning a fresh iterator over the tuple.
When to use it
Generator-based iteration
Yield values lazily instead of constructing a complete result collection.
Mapping views
Provide standard key iteration for mapping-like objects.
Interview questions
QWhat is the contract of __iter__?
__iter__ is called when an iterator is required for a container. It should return a new iterator that can traverse the container’s objects.
Follow-up: What should a mapping’s __iter__ yield? It should iterate over the mapping’s keys.
QHow can __iter__ be implemented lazily?
A for loop obtains an iterator from the object, then repeatedly requests values from that iterator until iteration ends. A generator function is one way to produce such an iterator because calling it returns an iterator object.
Follow-up: What ends a generator’s iteration? Returning or reaching the end raises StopIteration internally to mark the end of its values.
QWhat happens if a class has no __iter__ method?
A class may support iteration through the sequence protocol even without __iter__: iter() can use __getitem__ with integer arguments beginning at zero. If neither protocol is supported, iter() raises TypeError.
Follow-up: How can this fallback be disabled? Set the class’s __iter__ attribute to None; then iter() raises TypeError instead of falling back to __getitem__.
Related
object.__aiter__object.__getitem__iter()iterator.__next__StopIteration