Bug? @overloaded __init__() on a Generic class

[finite-state-machine]

I'm trying to have a Generic class set specific values for its TypeVars based on parameters passed to ThatClass.__init__() using a set of @overload rules. There doesn't seem to be a good (no errors) way to annotate this situation, but it's not clear to me which subset of these error messages represent bugs in pyright, and which are expected limitations of the tool.

If I annotate the relevant parameters in the __init__() @overloads using the narrowed, concrete types, I get errors about the implementation (non-@overload method & body) being incompatible, presumably because pyright doesn't understand that these are equivalent (Class1).

If I only annotate self on the @overloads, pyright warns only the 1st signature will ever be used, because all three @overloads use the "same" types for their non-self parameters – again, pyright hasn't taken into account that the annotation of self changes the semantic meaning of the TypeVars associated with the class (Class2).

With both approaches, pyright does the right thing with the constructor is actually called (i.e., the constructed instances are assigned the right specialization of Class1 or Class2 as the case may be); the problems (or reports of problems) occur only where the constructors are declared.

My suspicion is that both sets of error messages are bugs in pyright (in the sense that they represent surprising and undesired behaviour), but this may be based on a misunderstanding of the limitations of type inference.

I'd appreciate advice on where issues should be filed, or suggestions on a more appropriate way to handle this.

[pyright playground]:

from __future__ import annotations
from typing_extensions import (
        Any,
        Generic,
        Literal,
        TypeAlias,
        TypeVar,
        assert_type,
        cast,
        overload,
        )

# pyright: strict

Color: TypeAlias = Literal['red', 'orange', 'purple']
Flavor: TypeAlias = Literal['cherry', 'strawberry', 'orange', 'grape']
Size: TypeAlias = Literal['small', 'medium', 'large']

_K = TypeVar('_K', Literal['color'], Literal['flavor'], Literal['size'])
_V = TypeVar('_V')

class Class1(Generic[_K, _V]):
    """each `__init__()` `@overload` uses concrete types for `key` and `value`

    At line 58, pyright issues 3× `reportInconsistentOverload`:

        "Overloaded implementation is not consistent with signature of
         overload {1,2,3}"

    Details for each report are similar:

        Type "(self: Self@Class1[_K@Class1, _V@Class1], key: _K@Class1, value: _V@Class1) -> None" is not assignable to type ↩
           ↪ "(self: Class1[Literal['color'], Color], key: Literal['color'], value: Color) -> None"
          Parameter 2: type "Literal['color']" is incompatible with type "_K@Class1"
            Type "Literal['color']" is not assignable to type "_K@Class1"
          Parameter 3: type "Color" is incompatible with type "_V@Class1"
            Type "Color" is not assignable to type "_V@Class1" (reportInconsistentOverload)
    """
    key: _K
    value: _V

    @overload
    def __init__(
            self: Class1[Literal['color'], Color],
            key: Literal['color'], value: Color
            ) -> None: ...
    @overload
    def __init__(
            self: Class1[Literal['flavor'], Flavor],
            key: Literal['flavor'], value: Flavor
            ) -> None: ...
    @overload
    def __init__(
            self: Class1[Literal['size'], Size],
            key: Literal['size'], value: Size
            ) -> None: ...

    def __init__(self, key: _K, value: _V):                           # line 58

        self.key = key
        self.value = value



class Class2(Generic[_K, _V]):
    """each `__init__()` `@overload` uses `TypeVar`s for `key` and `value`

    At lines 82 and 87, pyright issues 2× `reportOverlappingOverload`:

        "Overload {2,3} for '__init__' will never be used because its
         parameters overlap overload 1"
    """
    key: _K
    value: _V

    @overload
    def __init__(
            self: Class2[Literal['color'], Color],
            key: _K, value: _V
            ) -> None: ...
    @overload
    def __init__(                                                     # line 82
            self: Class2[Literal['flavor'], Flavor],
            key: _K, value: _V
            ) -> None: ...
    @overload
    def __init__(                                                     # line 87
            self: Class2[Literal['size'], Size],
            key: _K, value: _V
            ) -> None: ...

    def __init__(self, key: _K, value: _V):

        self.key = key
        self.value = value


def test_class1_annotations() -> None:

    p_color = Class1('color', cast(Any, 'red'))
    assert_type(p_color, Class1[Literal['color'], Color])  # OK
    p_flavor = Class1('flavor', cast(Any, 'cherry'))
    assert_type(p_flavor, Class1[Literal['flavor'], Flavor])  # OK
    p_size = Class1('size', cast(Any, 'medium'))
    assert_type(p_size, Class1[Literal['size'], Size])  # OK


def test_class2_annotations() -> None:

    p_color = Class2('color', cast(Any, 'red'))
    assert_type(p_color, Class2[Literal['color'], Color])  # OK
    p_flavor = Class2('flavor', cast(Any, 'cherry'))
    assert_type(p_flavor, Class2[Literal['flavor'], Flavor])  # OK
    p_size = Class2('size', cast(Any, 'medium'))
    assert_type(p_size, Class2[Literal['size'], Size])  # OK

[erictraut]

You're using aspects of the type system that are not well defined or specified. In particular, you're using value-constrained type variables — and with literal type constraints. I recommend rethinking your approach so you can use type system features that are better defined. One obvious solution is to create a class hierarchy — one subclass for "color", "flavor" and "size" — rather than trying to make a single class act upon all three types and then using a string to differentiate between them.

As for your question about bugs in pyright, I think pyright is doing the right thing here, so I don't think any of these are bugs. The first set of errors (in Class1) are legitimate and dictated by the draft typing spec section on overlapping overloads. Not surprisingly, mypy generates the same errors in this case.

The second set of errors (in Class2) also appears to be legitimate, although mypy doesn't generate errors in this case. I think this is a bug in mypy, which doesn't fully implement the latest updates in the Python typing spec regarding constructors.