How to Write Python Generator Type Hints
Learn to write correct Python generator type hints: the three Generator parameters, when Iterator suffices, and how type checkers verify your code.

Writing a Python generator type hint is different from annotating a normal function. A generator function contains at least one yield statement, and calling it does not execute the body immediately. Instead, it returns a generator object that produces values lazily. The type hint must describe that object, not a list or a single value.
def count_up_to(limit: int) -> list[int]:
current = 1
while current <= limit:
yield current
current += 1This annotation is wrong. The function never returns a list. Calling count_up_to(3) produces a generator object, and a type checker will flag the mismatch because the body contains yield but the declared return type is list[int].
The correct annotation uses the Generator type:
from typing import Generator
def count_up_to(limit: int) -> Generator[int, None, None]:
current = 1
while current <= limit:
yield current
current += 1Generator is a generic type with three parameters. The first is the type of values yielded, the second is the type of values that can be sent into the generator via .send(), and the third is the type of the value returned when the generator finishes. For a plain generator that only yields values, the send and return types are both None.
The Three Parameters of Generator
The full signature is Generator[YieldType, SendType, ReturnType]. Each parameter serves a distinct role:
| Parameter | Meaning | Typical value |
|---|---|---|
| YieldType | Type of each value produced by yield | int, str, SomeModel |
| SendType | Type of values accepted by .send() | None if you never send |
| ReturnType | Type of the value from return when exhausted | None if no return value |
If a generator yields integers and never accepts sent values, Generator[int, None, None] is correct. If it yields strings and returns a final summary value, the third parameter changes:
from typing import Generator
def read_lines() -> Generator[str, None, int]:
count = 0
for line in open("data.txt"):
yield line.strip()
count += 1
return countHere the generator yields each stripped line, and when the file is exhausted it returns the total line count. A caller that exhausts the generator with a for loop will not see the return value. The value is attached to the StopIteration exception that marks the end, so an explicit next() loop or yield from is needed to observe it. The type hint records that behavior so callers know what to expect.
When Iterator or Iterable Is the Better Hint
Most generators in real code only yield values. They never use .send(), and they never return a meaningful value. In that case, Generator[T, None, None] is verbose. The Iterator type is a simpler and equally accurate annotation:
from collections.abc import Iterator
def count_up_to(limit: int) -> Iterator[int]:
current = 1
while current <= limit:
yield current
current += 1Iterator[T] is the right public annotation for a generator that yields T and does not use .send() or return a value. Because Iterator[T] is a subtype of Iterable[T], it is valid anywhere an iterable is expected, and it communicates that the result can be iterated once.
Iterable[T] is even more general. It describes any object that can be iterated, including lists, tuples, and generators. If a function accepts an iterable, annotating the parameter as Iterable[T] is usually better than Iterator[T] because it allows callers to pass lists or sets. But as a return annotation for a generator function, Iterable[T] is less precise: it hides the fact that the result is single-use. Prefer Iterator[T] for generator return types and Iterable[T] for parameters that accept any iterable input.
Typing Generators That Accept send() Values
The middle parameter of Generator matters when the generator uses yield as an expression. A generator can receive values from the caller through .send(), and those values become the result of the yield expression:
from typing import Generator
def accumulator() -> Generator[float, float, None]:
total = 0.0
while True:
value = yield total
total += valueHere the generator yields the current total and accepts a new value to add. The annotation Generator[float, float, None] says: yields floats, accepts floats via .send(), and returns nothing. A caller can then do:
acc = accumulator()
next(acc) # start the generator, get initial total
acc.send(2.5) # send 2.5, receive the new totalWithout the middle parameter set correctly, a type checker cannot verify that send() calls pass the right type. This is the main case where you need the full three-parameter form rather than Iterator[T].
How Type Checkers Infer Generator Types
Mypy, Pyright, and other type checkers use the yield statements in the body to validate the yield type. If you annotate the function with Generator[int, None, None] but the body yields strings, the checker reports a mismatch. The same applies to the return type: if the body contains return 42, the third parameter must be int.
Inference also works in the other direction. If you write a generator function without an explicit return annotation, the checker infers a Generator type from the body. That inferred type is often more specific than you need, which is why an explicit Iterator[T] annotation is useful: it narrows the public contract and prevents callers from depending on send or return behavior you did not intend to expose.
One practical detail: yield from changes what the checker verifies. If a generator delegates to another generator with yield from, the delegated generator's yield type must match the outer generator's yield type. The send and return types must also be compatible, because yield from forwards both.
Common Mistakes in Generator Type Hints
A frequent mistake is using List[T] or Sequence[T] as the return annotation for a generator function. The function does not return a list, so the annotation is false and the checker will reject the body.
Another mistake is forgetting the third parameter when the generator returns a value. Generator[int, None] is invalid; Generator always takes three type arguments. If the generator has no send or return behavior, use Iterator[int] instead of trying to shorten Generator.
A subtler issue: annotating a generator with Generator[int, None, int] when the body has no return statement. The checker will complain that the declared return type is int but the function can complete without returning a value. Either add the return or change the third parameter to None.
Mismatches also appear when the same generator is used in multiple contexts. If one consumer needs to send int values into it while another only iterates over str values, the generator function's public annotation cannot be just Iterator[str]; it needs to be something like Generator[str, int, None]. The public type hint should reflect the full behavior, not the easiest single use.
Version Compatibility and Import Choices
The typing module has provided Generator since Python 3.5. If you need to support Python versions before 3.9, from typing import Generator is the safe choice. On Python 3.9 and later, collections.abc exposes the same generic types directly:
from collections.abc import Generator
def numbers() -> Generator[int, None, None]:
yield 1
yield 2For annotations, collections.abc.Generator and typing.Generator are interchangeable: both refer to the same generator ABC. Prefer the collections.abc import in Python 3.9+ because the corresponding typing aliases are deprecated for this purpose. The same applies to Iterator and Iterable.
Annotations do not affect how the generator runs. By default, annotation expressions are evaluated at function definition time, but that does not change generator execution. If you want to avoid evaluating annotation expressions at definition time, use from __future__ import annotations; annotations are then stored as strings. The important thing is that the annotation matches the generator's actual behavior, because type checkers and IDE tooling rely on it for autocompletion, refactoring, and static validation.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.