Generator[T] is falsely marked as incompatible with Iterator[T] when implementing an overload

[jshumphrey]

High-level problem: A method is overloaded such that one possible return type is Iterator[T]. In this overload situation, I'm returning a Generator[T], and this is marked as incompatible with Iterator[T].

I'm running pyright as part of Pylance in VS Code; I can also reproduce this behavior in the Pyright Playground.

I do not believe this to be a duplicate of #1289, since that issue was traced to typeshed settings, whereas this behavior is reproducible in the Playground.

---

I've got a method where you can either provide a single value as an input, or a Sequence of values. If you provide a single value, you get a single result. If you provide a Sequence of values, you get an Iterator with one result for each input value. I've added typing.overload definitions to indicate this.

The problem is that I want to return a generator for the second use-case; when I try to do so, I get a typing warning.

import typing
from collections.abc import Iterator, Sequence

FooDict: typing.TypeAlias = dict[int, str]

class Bar:
    # Assume that list(Bar) returns a list of str
    def __iter__(self) -> Iterator[str]: ...

    @typing.overload
    def foo(self, i: int) -> FooDict: ...

    @typing.overload
    def foo(self, i: Sequence[int]) -> Iterator[FooDict]: ...  # Typing error on this line

    def foo(self, i: int | Sequence[int]):
        if isinstance(i, int):
            return {i: list(self)[i]}
        if isinstance(i, Sequence):
            return ({x: list(self)[x]} for x in i)
        raise TypeError

This gives a typing error:

Overloaded implementation is not consistent with signature of overload 2
Function return type "Iterator[FooDict] is incompatible with type "dict[int, str] | Generator[dict[int, str], None, None]"
"Iterator[FooDict]" is incompatible with "dict[int, str]"
"Iterator[FooDict]" is incompatible with "Generator[dict[int, str], None, None"

However, adjusting the type annotation for the (real) implementation of def foo so that it explicitly unions the two possible return types (def foo(self, i: int | Sequence[int]) -> FooDict | Iterator[FooDict]:) gets rid of the error.

[erictraut]

Pyright is working as designed here. I don't consider this a bug.

Pyright is telling you that the return type of your implementation is not consistent with the return types of your respective overloads.

If you omit a return type annotation for a function, pyright will infer the return type based on the return and yield statements in the function. In this case, the inferred return type is FooDict | Generator[FooDict, None, None]. This type is a correct inference, but it's not consistent with the return types of your overload signatures.

Mypy (another popular Python type checker) doesn't support return type inference, but if you add an explicit return type annotation of FooDict | Generator[FooDict, None, None] to your code (consistent with the return type inferred by pyright) and then run mypy, it emits the same error that you're seeing with pyright.

You can fix this in your code by doing one of the following:

1. Change the second overload to return a Generator[FooDict, None, None]
2. (As you noted), provide an explicit return type annotation for the overload implementation: FooDict | Iterator[FooDict]