Strange behavior when UnionType meets overload methods

[inaku (inaku-Gyan)]

I intend to create a generic class such that the static type checker can get its generic argument correctly when I pass a type (which can be a UnionType) into its __init__. Examples:

a = Foo(tp=str)  # `a` is expected to be `Foo[str]`
b = Foo(tp=str | int)  # `b` is expected to be `Foo[str | int]`

I first tried this:

class Foo[T]:
    def __init__(self, *, tp: type[T]) -> None: ...

foo = Foo(tp=str | int)

Then Pylance reports an error here:

Cannot assign a parameter of type "UnionType" to parameter "tp" of type "type[T@Foo]" in function "__init__"
  Type "UnionType" is not assignable to type "type[T@Foo]" Pylance(reportArgumentType)

By some accident, however, I find the following code works:

from typing_extensions import deprecated
from typing import overload


class Foo[T]:

    @overload
    def __init__(self, *, tp: type[T]) -> None: ...

    @overload
    @deprecated("xxx")
    def __init__(self, *, tp: type[T]) -> None: ...

    def __init__(self, *, tp: type[T]) -> None: ...


foo = Foo(tp=str | int)

Pylance never reports any error, and foo is correctly displayed as (variable) foo: Foo[int | str]

I wonder why the latter works, and what's the best way to achieve my goal.

[Eric Traut (erictraut)]

The value expression str | int at runtime produces an object that is an instance of UnionType. It is not an instance of the type class, so it's not assignable to type. The typing spec is clear on that point, so pyright is correct in flagging that as a type violation.

Pyright should reject both of the above cases. The fact that it doesn't in the second case (involving an overload) is a bug.

It looks like you are using str | int as a type form — that is, you want it to be interpreted as a type expression rather than a value expression. There is a draft PEP 747 that introduces a mechanism in the type system to handle type forms.

[Eric Traut (erictraut)]

Keep in mind that the union operator (|) is intended to apply to sets. This makes sense in type theory because a type represents a set of runtime values. A union operator combines two sets. If your intent is to allow callers to specify a list of classes, then a union operator is not appropriate. I'd recommend instead using a tuple or a set.

class Foo[T]:
    def __init__(self, *, tp: type[T] | tuple[type[T], ...]) -> None: ...

foo = Foo(tp=(str, int))

If you decide to use TypeForm, then you are taking on the responsibility of handling any valid type form object, including the objects generated by type expressions Literal[1] or Self or list["ForwardReference"]. That makes sense for tools like runtime type checkers, but I wouldn't recommend it for most Python code.

[inaku (inaku-Gyan)]

Hello! I tried TypeForm with Python 3.13.3, but Pyright still raises an error:

from typing_extensions import TypeForm


class Foo[T]:
    def __init__(self, *, tp: TypeForm[T]) -> None: ...


foo = Foo(tp=str | int)  # Error here

Cannot assign a parameter of type "UnionType" to parameter "tp" of type "TypeForm[T@Foo]" in function "__init__"
  Type "UnionType" is not assignable to type "TypeForm[T@Foo]" Pylance(reportArgumentType)

[Eric Traut (erictraut)]

This is because you haven't set enableExperimentalFeatures to true in the config. PEP 747 is not yet accepted, so TypeForm is considered an experimental feature.