泛型类属性中联合类型处理的Pylance类型检查问题

问题场景 #

在Python 3.13.3环境下，使用泛型类结合联合类型时，Pylance对update方法的参数类型检查报错。要求必须保留DetailUnion联合类型，仅修改Foo类，不改动Detail1和DetailUnion。

原代码 #

from typing import Self


class Detail1:
    x: int

    def update(self, other: Self) -> None:
        self.x += other.x

class Detail2:
    y: str

    def update(self, other: Self) -> None:
        self.y += other.y

DetailUnion = Detail1 | Detail2


class Foo[Detail: DetailUnion]:

    detail: Detail

    def foo(self, other: Self) -> None:
        self.detail.update(other.detail)  # 此处触发类型错误

Pylance错误信息 #

Argument of type "Detail@Foo" cannot be assigned to parameter "other" of type "Detail1*" in function "update"
  Type "Detail1* | Detail2*" is not assignable to type "Detail1*"
    "Detail2*" is not assignable to "Detail1*" Pylance(reportArgumentType)

Argument of type "Detail@Foo" cannot be assigned to parameter "other" of type "Detail2*" in function "update"
  Type "Detail1* | Detail2*" is not assignable to type "Detail2*"
    "Detail1*" is not assignable to "Detail2*" Pylance(reportArgumentType)

问题原因 #

Pylance无法自动推断出self.detail与other.detail属于同一具体类型（均为Detail1或均为Detail2），而是将其识别为DetailUnion联合类型，导致与update方法要求的Self类型参数不匹配。

解决方案 #

方案1：使用cast强制类型转换 #

通过typing.cast明确告知类型检查器，other.detail的类型与self.detail一致：

from typing import Self, cast

# Detail1、Detail2、DetailUnion定义不变

class Foo[Detail: DetailUnion]:
    detail: Detail

    def foo(self, other: Self) -> None:
        self.detail.update(cast(Detail, other.detail))

方案2：添加类型断言验证 #

通过assert在运行时验证类型一致性，同时帮助类型检查器缩小类型范围：

from typing import Self

# Detail1、Detail2、DetailUnion定义不变

class Foo[Detail: DetailUnion]:
    detail: Detail

    def foo(self, other: Self) -> None:
        assert type(self.detail) is type(other.detail), "Detail types must match"
        self.detail.update(other.detail)

方案说明 #

• 方案1仅作用于静态类型检查，不影响运行时逻辑，适合确定类型必然一致的场景。
• 方案2增加了运行时类型验证，提升代码安全性，但类型不匹配时会抛出AssertionError。

内容的提问来源于stack exchange，提问作者inaku Gyan