如何为Python联合类型别名声明共享方法解决类型检查报错？

问题场景 #

现有两个无法修改的类A和B，二者均实现了f()方法：

class A:
  def f(self) -> bool:
    ...

class B:
  def f(self) -> bool:
    ...

我通过Union定义了类型别名：

from typing import Union, TypeAlias
FClass: TypeAlias = Union[A, B]

随后定义返回该类型的函数g()（函数内部实现无法修改）：

def g() -> FClass:
  ...  # 返回A或B类型的对象

n = g()
n.f()  # 类型检查器报错！

报错信息如下：

'A | B' has no attribute 'f'

实际场景是依赖的多分支库会返回不同内部对象，但它们共享同一API，需要让类型检查器识别FClass必然存在f()方法。

解决办法 #

1. 使用Protocol（推荐方案） #

Python的typing.Protocol可以定义虚拟接口，无需让A、B显式继承，只要类实现了协议声明的方法，就会被类型检查器判定为符合该协议。

代码示例：

from typing import Protocol, TypeAlias, runtime_checkable

# 定义协议，声明必须包含f()方法
@runtime_checkable  # 可选，添加后支持运行时检查对象是否符合协议
class FProtocol(Protocol):
    def f(self) -> bool:
        ...

# 重新定义类型别名
FClass: TypeAlias = FProtocol

# 也可直接将协议作为函数返回类型
def g() -> FProtocol:
    ...

n = g()
n.f()  # 类型检查器不再报错

类型检查器会自动识别A和B符合FProtocol，因为二者都实现了协议要求的f()方法。

2. 使用类型断言 #

如果不想定义协议，可通过断言告知类型检查器当前对象的具体类型：

n = g()
assert isinstance(n, (A, B))
n.f()  # 断言后类型检查器会识别n为A或B，确认存在f()方法

缺点是每次调用都需要添加断言，后续新增符合API的类时，还要更新断言中的类型列表。

3. 使用cast强制类型转换 #

通过typing.cast强制转换类型，绕过类型检查：

from typing import cast

n = cast(FClass, g())
n.f()

此方式相当于跳过类型检查，运行时若对象实际无f()方法仍会报错，仅适用于确认对象一定符合要求的场景。

内容的提问来源于stack exchange，提问作者Nathaniel Ford