关于将生成器函数标注为Iterator的困惑及技术咨询

Hey David, great question—this is a common point of confusion when working with Python's typing system and generators, so let's break it down step by step.

First, let's clarify the core relationship here:

Python generator functions return iterator objects by default. And since every iterator is also an iterable (because Iterator inherits from Iterable in the typing hierarchy), both Iterable[YieldType] and Iterator[YieldType] are valid annotations for generator return types.

Why Both Annotations Work #

Let's quickly recap the difference between the two:

• An Iterable is any object you can loop over with a for loop. It implements the __iter__() method, which returns an iterator. Examples include lists, tuples, and yes—generators.
• An Iterator is a stateful object that implements both __iter__() (which returns itself) and __next__() (which produces the next value in the sequence). Generators are perfect examples of iterators: they keep track of their internal state between yield calls, and you can call next() directly on them.

Since your infinite_stream generator is an iterator (and thus also an iterable), either annotation passes type checkers like mypy or pyright.

How to Choose Between Them #

The choice comes down to how you want to communicate the intended use of the generator to other developers (and type checkers):

• Use Iterable[int] if you only care that the return value can be iterated over (e.g., in a for loop). This is more flexible—it allows any iterable, not just iterators. But it doesn't signal that the object is stateful or supports direct next() calls.
• Use Iterator[int] (like you did) if you want to be precise: generators are iterators, so this annotation tells users that the object has internal state, can be consumed only once, and supports methods like next(). This is especially useful if the code that uses the generator will directly interact with it as an iterator (e.g., calling next() manually, or passing it to functions that expect an iterator).

Looking at Your Example #

Your infinite_stream function annotated as def infinite_stream(start: int) -> Iterator[int]: is completely correct. When you pass this generator to another function, type checkers will recognize it as both an iterator and an iterable, so it will work with functions expecting either type.

For example, both of these function signatures would accept your generator:

# Accepts any iterable (including your generator)
def print_some(stream: Iterable[int], limit: int) -> None:
    for num in stream:
        if limit <= 0:
            break
        print(num)
        limit -= 1

# Explicitly accepts an iterator (matches your annotation)
def print_via_next(stream: Iterator[int], limit: int) -> None:
    for _ in range(limit):
        print(next(stream))

Key Takeaway #

Both annotations are valid, but Iterator[YieldType] is more precise for generators since it accurately describes what the function actually returns. Iterable[YieldType] is a looser annotation that works if you just need to communicate "this can be looped over."

内容的提问来源于stack exchange，提问作者David Michael Gang