Annotate generator return types
A function lazily produces records or values without building a list first.
Python · Type Alias
Iterator
Iterator[T] annotates an iterator that yields values of type T. Modern Python code should use collections.abc.Iterator[T], while typing.Iterator remains as a compatibility form.
How it works
Iterator[T] describes an iterator that produces values of type T. Use it to annotate iterator-producing functions, including generators; the modern form comes from collections.abc rather than the deprecated typing alias.
Syntax
collections.abc.Iterator[T]Parameters
| Name | Type | Description |
|---|---|---|
T | type parameter | The type of each value produced by the iterator. |
Returns
An iterator producing values of type T.
Key points
- Iterator is generic, so supply the type of each value it produces, such as Iterator[str].
- The typing form represents the corresponding collections.abc iterator abstraction.
- Generator functions that only yield values may declare Iterator[YieldType] as their return type.
Common mistakes
- Prefer collections.abc.Iterator[T] in modern Python; the typing.Iterator alias is deprecated for this purpose.
- The annotation guides static type checkers but does not make Python enforce yielded values at runtime.
Example: Annotating a generator
from collections.abc import Iterator
def numbers() -> Iterator[int]:
yield 1
yield 2
for number in numbers():
print(number)The generator yields integers, and its return annotation describes the iterator's item type.
When to use it
Describe custom iterators
A custom object implements the iterator protocol and yields a known value type.
Document streaming inputs
An API accepts a one-pass stream of typed values.
Interview questions
QWhat does Iterator[int] mean?
Iterator[T] is a generic annotation for an iterator whose produced values have type T. A generator that only yields values can use it as its return annotation.
Follow-up: When would Iterable[T] be preferable? Use Iterable[T] when callers only need to iterate and the implementation need not expose iterator-specific behavior.
QHow do you annotate a generator that yields integers?
A generator function can be annotated with Iterator[T] when it yields values of type T. Calling the function returns a generator iterator rather than a materialized collection.
Follow-up: What is the practical consequence of returning an iterator? Consumption is typically one-pass, so callers should not assume they can restart it without creating another iterator.
QWhich Iterator import should modern code use?
The modern generic alias is collections.abc.Iterator[T]. The typing module's Iterator is retained for compatibility but is deprecated because the collections.abc form supports subscription.
Follow-up: How would you annotate an iterator of an unconstrained type? Use Iterator[Any] or leave the item type broad according to the intended static contract.
Related
collections.abc.Iteratorcollections.abc.Iterabletyping.Iterabletyping.GeneratorStopIterationiterator.__iter__()iterator.__next__()