Incorrect type inference with PEP 646 Unpack and self-type annotations

[zzzeek]

Bug Report

When a generic class uses TypeVarTuple (PEP 646) and a method has a self-type annotation that "reshapes" the type parameters, mypy incorrectly infers the return type when the class is instantiated with Unpack[Tuple[Any, ...]].

Specifically, mypy infers the return type as None instead of Any | None, leading to false "unreachable code" errors.

To Reproduce

from typing import Generic, TypeVar, Optional, Iterator, Any, Tuple
from typing_extensions import TypeVarTuple, Unpack

_T = TypeVar("_T", bound=Any)
_Ts = TypeVarTuple("_Ts")


class Result(Generic[Unpack[_Ts]]):
    """Generic result class that takes variadic type parameters.

    This mimics SQLAlchemy's Result class which is generic over Unpack[_Ts].
    """

    def scalar(self: "Result[_T, Unpack[Tuple[Any, ...]]]") -> Optional[_T]:
        return None




def test_function() -> Iterator[Any]:
    result: Result[Unpack[Tuple[Any, ...]]] = Result()
    reveal_type(result)
    data = result.scalar()
    reveal_type(data)
    if data is None:
        return
    yield from iter(data)

Expected Behavior

If we run pyright, the type of "data" is "Any | None" and the yield from is reachable:

$ pyright mypy_bug_repro.py 
/home/classic/dev/sqlalchemy/mypy_bug_repro.py
  /home/classic/dev/sqlalchemy/mypy_bug_repro.py:22:17 - information: Type of "result" is "Result[*tuple[Any, ...]]"
  /home/classic/dev/sqlalchemy/mypy_bug_repro.py:24:17 - information: Type of "data" is "Any | None"
0 errors, 0 warnings, 2 informations

Actual Behavior

Mypy sees "data" as None in all cases

$ mypy --warn-unreachable mypy_bug_repro.py 
mypy_bug_repro.py:22: note: Revealed type is "mypy_bug_repro.Result[Unpack[builtins.tuple[Any, ...]]]"
mypy_bug_repro.py:24: note: Revealed type is "None"
mypy_bug_repro.py:27: error: Statement is unreachable  [unreachable]
Found 1 error in 1 file (checked 1 source file)

Your Environment

• Mypy version: mypy 1.19.1 (compiled: yes)
• Python version: 3.14
• typing_extensions version: latest (for TypeVarTuple, Unpack)
• Pyright version (for comparison): 1.1.408

notes

So I used Claude to refactor SQLAlchemy's structures into standalone features. Additional commentary from Claude which may or may not be helpful:

The bug appears to be in mypy's type parameter matching logic. When trying to match:

• Instance type: Result[Unpack[Tuple[Any, ...]]]
• Against self-type: Result[_T, Unpack[Tuple[Any, ...]]]

Mypy should extract _T = Any from the first element of the unpacked tuple, but instead appears to fail at this extraction, possibly binding _T to Never or treating it as non-existent, resulting in Optional[Never] = None.

downstream SQLAlchemy issues is at sqlalchemy/sqlalchemy#13089 which is local to the new 2.1.0beta1 release that uses pep-646

[ilevkivskyi]

Hm, this may be indirectly caused by #18665. That one causes a lot of troubles for numpy, so I actually wanted to work on it in January but instead spent more time than expected polishing the parallel type checking.

[zzzeek]

any workarounds for this one on the def scalar() side of the example? I've tried lots of different combinations of overloads with no success, it really sees that Unpack with almost anything in it and assumes None

[ilevkivskyi]

This really depends on what kind of constraints do you have. Something as simple as:

class Result(Generic[_T, Unpack[_Ts]]):
    def scalar(self) -> Optional[_T]:
        return None

works (no need for self-type). But I guess you may need to update some other methods in Result.

[zzzeek]

that looks like you modified the type of the whole object though, so, that would be a pretty big deal on this end

is this issue known to be fixable on the mypy side ? this is only a prerelease series of sqlalchemy so we have some time

[ilevkivskyi]

It is fixable, but somewhat non-trivial (essentially we will need to re-define the exact way how mypy interprets ...). I can't really promise any timeline, likely in the best case it will be few months (since we have many things going on now).

[CaselIT]

Interestingly this is correctly matched, but only if the the result is of type Result[Unpack[Tuple[int, ...]]]. If it's for example Result[Unpack[Tuple[int, str]]] we are back to resolving None

def scalar(self: "Result[Unpack[Tuple[_T, ...]]]") -> Optional[_T]:return None

[CaselIT]

It also seems that Any is treated differently from other types. This these overload it works if the tuple is typed, but not with Any

from typing import Generic, TypeVar, Optional, Iterator, Any, Tuple, overload
from typing_extensions import TypeVarTuple, Unpack

_T = TypeVar("_T", bound=Any)
_Ts = TypeVarTuple("_Ts")

class Result(Generic[Unpack[_Ts]]):
    """Generic result class that takes variadic type parameters.

    This mimics SQLAlchemy's Result class which is generic over Unpack[_Ts].
    """

    @overload
    def scalar(
        self: "Result[_T, Unpack[Tuple[Any, ...]]]",
    ) -> Optional[_T]: ...
    @overload
    def scalar(self: "Result[Unpack[Tuple[_T, ...]]]") -> Optional[_T]: ...
    def scalar(self) -> Optional[Any]:
        return None

def test_function() -> None:
    result: Result[Unpack[Tuple[int, ...]]] = Result()
    reveal_type(result)
    data = result.scalar()
    reveal_type(data)
    result2: Result[Unpack[Tuple[int, str]]] = Result()
    reveal_type(result2)
    data2 = result2.scalar()
    reveal_type(data2)
    result3: Result[Unpack[Tuple[Any, ...]]] = Result()
    reveal_type(result3)
    data3 = result3.scalar()
    reveal_type(data3)
    result4: Result[Any] = Result()
    reveal_type(result4)
    data4 = result4.scalar()
    reveal_type(data4)

I get as output

test2.py:24: note: Revealed type is "test2.Result[Unpack[builtins.tuple[builtins.int, ...]]]"
test2.py:26: note: Revealed type is "builtins.int | None"
test2.py:28: note: Revealed type is "test2.Result[builtins.int, builtins.str]"
test2.py:30: note: Revealed type is "builtins.int | None"
test2.py:32: note: Revealed type is "test2.Result[Unpack[builtins.tuple[Any, ...]]]"
test2.py:34: note: Revealed type is "None"
test2.py:36: note: Revealed type is "test2.Result[Any]"
test2.py:38: note: Revealed type is "Any | None"

[CaselIT]

It seems that using Result[Any] in place of Result[Unpack[builtins.tuple[Any, ...]]] does fix.

Maybe a simple fix could be to make mypy consider Result[Unpack[builtins.tuple[Any, ...]]] the same as Result[Any]?

[uriyyo]

So I have found a workaround for now.

mypy resolves type to Never in such case, so adding overload with first arg Never allows at least to catch such case and avoid unreachable stmt error:

    @overload
    def scalar(self: Result[Never, Unpack[TupleAny]]) -> Optional[Any]:
        pass

    @overload
    def scalar(self: Result[_T, Unpack[TupleAny]]) -> Optional[_T]:
        pass

    def scalar(self: Result[_T, Unpack[TupleAny]]) -> Optional[_T]:
         ...

[zzzeek]

confirmed that #20651 (comment) appears to solve the issue completely. mypy's typing comes out just as you'd want it to. we had a few other workarounds that were not as clean as this one.

[ilevkivskyi]

confirmed that #20651 (comment) appears to solve the issue completely. mypy's typing comes out just as you'd want it to. we had a few other workarounds that were not as clean as this one.

Great, this relieves some pressure from us :-)