可调用对象联合类型与返回联合类型的可调用对象的类型兼容问题

问题描述 #

编写了如下代码：

from typing import Union, Callable

def x() -> Union[str, int]:
    return ...  # 多行逻辑，无法用lambda替代

l: list[Union[Callable[[], str], Callable[[], int]]] = [x]

MyPy和Pylance均提示类型不兼容，报错信息：

Expression of type "list[() -> (str | int)]" cannot be assigned to declared type "list[(() -> str) | (() -> int)]"
  Type "() -> (str | int)" cannot be assigned to type "(() -> str) | (() -> int)"
    Type "() -> (str | int)" cannot be assigned to type "() -> str"
      Function return type "str | int" is incompatible with type "str"
        Type "str | int" cannot be assigned to type "str"
          "int" is incompatible with "str"
    Type "() -> (str | int)" cannot be assigned to type "() -> int"
      Function return type "str | int" is incompatible with type "int"
        Type "str | int" cannot be assigned to type "int"

由于列表类型由第三方库确定，必须是Union[Callable[[], str], Callable[[], int]]的列表，需求是：

• 能否将x的类型修改为可调用对象的联合类型（而非返回联合类型的可调用对象）？
• 在不忽略类型安全的前提下，如何通过类型提示或代码调整让类型检查器认可这段代码？

解决方案 #

方案1：使用typing.cast进行类型转换 #

通过cast明确告知类型检查器，x符合目标联合类型的约束，这不会破坏类型安全（因为我们清楚x的实际行为满足要求）：

from typing import Union, Callable, cast

def x() -> Union[str, int]:
    # 多行业务逻辑
    if some_condition:
        return "hello"
    else:
        return 123

CallableUnion = Union[Callable[[], str], Callable[[], int]]
l: list[CallableUnion] = [cast(CallableUnion, x)]

方案2：给函数添加@overload重载 #

通过重载声明，让类型检查器将x识别为两种可调用类型的联合，这是更优雅的适配方式，完全支持多行函数场景：

from typing import Union, Callable, overload

@overload
def x() -> str: ...

@overload
def x() -> int: ...

def x() -> Union[str, int]:
    # 多行业务逻辑
    if some_condition:
        return "hello"
    else:
        return 123

l: list[Union[Callable[[], str], Callable[[], int]]] = [x]

此时类型检查器会自动将x匹配为Callable[[], str] | Callable[[], int]，完美契合目标列表类型。

类型不兼容的核心原因 #

Callable[[], str | int]（返回联合类型的单一函数）和Callable[[], str] | Callable[[], int]（两种不同函数类型的联合）是语义完全不同的类型：

• 前者表示：单个函数，每次调用可能返回str或int
• 后者表示：要么是返回str的函数，要么是返回int的函数，每个函数的返回类型是确定的

类型检查器不会自动转换二者，因为它们的行为约束存在本质差异。

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