如何为兼容Union类型及其成员类型的函数添加类型提示？

问题重现 #

先看你的代码和Mypy报错：

$ cat foo.py
from typing import overload, Union, TypeVar
T = Union[int, str]
SubT = TypeVar("SubT", int, str)

@overload
def a(t: T) -> T: ...
@overload
def a(t: SubT) -> SubT: ...
def a(t: T) -> T: return t

运行Mypy后得到错误：

$ mypy foo.py
foo.py:7: error: Overloaded function signatures 1 and 2 overlap with incompatible return types

为什么会报错？ #

原因在于重载的顺序和签名范围重叠：

1. 第一个重载接受T（即Union[int, str]）并返回T，这个签名的范围覆盖了所有int、str以及它们的联合类型。
2. 第二个重载接受SubT（约束为int或str）并返回SubT，这个签名的范围是int和str，完全被第一个重载的范围包含。

Mypy会认为这种重叠是有问题的：当传入int或str类型的参数时，两个重载都能匹配，但第一个重载返回的是Union[int, str]，第二个返回的是具体的int或str。虽然具体类型是联合类型的子类型，但Mypy不允许这种模糊的重载重叠，因为它无法确定应该优先使用哪个签名的返回类型。

解决方案：调整重载顺序，让更具体的签名优先 #

解决方法很简单，把更具体的重载（针对SubT的）放在前面，泛化的重载（针对T的）放在后面。Mypy会按照重载的定义顺序匹配，优先选择最具体的签名，这样就不会有冲突了：

from typing import overload, Union, TypeVar
T = Union[int, str]
SubT = TypeVar("SubT", int, str)

# 先定义更具体的重载：匹配int/str类型的参数
@overload
def a(t: SubT) -> SubT: ...
# 再定义泛化的重载：匹配Union[int, str]类型的参数
@overload
def a(t: T) -> T: ...
# 实现体
def a(t: T) -> T: return t

现在运行Mypy就不会报错了，而且完全符合你的期望：

• a(v_1)（v_1: Union[int, str]）会匹配第二个重载，返回Union[int, str]
• a(v_2)（v_2: int）会匹配第一个重载，返回int
• a(v_3)（v_3: str）会匹配第一个重载，返回str

针对复杂场景的扩展 #

你提到实际场景中SubT的约束远不止2种，甚至需要处理同构/异构Iterable的情况，这个方案依然适用：

• 对于同构Iterable：定义带约束的TypeVar（比如SubT = TypeVar("SubT", list[int], list[str], tuple[int, ...])），重载优先匹配这个SubT，保留类型粒度。
• 对于异构Iterable：定义泛化的Union类型作为另一个重载，处理混合类型的情况。

这种方式不需要为每个成员类型单独写重载，利用带约束的TypeVar就能批量处理所有同构类型，同时用泛化重载覆盖异构场景。

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