在 Python 类型提示中，TypeVar 与联合类型（Union Type）的交互常令人困惑。本文将深入探讨当一个 TypeVar 被约束为特定类型时，为何它不能直接接受一个包含这些类型的联合类型，并提供两种有效的解决方案：通过扩展 TypeVar 的约束列表来包含联合类型本身，或使用 bound 参数来指定 TypeVar 的上界，从而在保持类型安全的同时增强代码的灵活性。
TypeVar 约束与联合类型的冲突
在 Python 的 typing 模块中，TypeVar 用于定义泛型，允许函数或类的参数和返回值在保持类型关系的同时接受不同类型。当 TypeVar 通过列出多个类型进行定义时，例如 T = TypeVar("T", float, Fraction)，它被视为一个受约束的 TypeVar。这意味着 T 在任何给定时刻都必须是其约束列表中的精确一个类型（即 float 或 Fraction），而不是这些类型的任意组合。
考虑以下示例，其中 f 函数使用了一个受约束的 TypeVar：
from fractions import Fraction
from typing import TypeVar
T = TypeVar("T", float, Fraction)
def f(x: T) -> T:
"""
期望一个 float 或 Fraction，并返回相同类型的值
"""
return x * 2
# 以下调用是合法的，因为它们提供了 T 约束列表中的精确一个类型
f(1.0) # ok
f(Fraction(1, 2)) # ok
def g(x: float | Fraction) -> float | Fraction:
"""
期望一个 float 或 Fraction
"""
return f(x) / 2当尝试在 g 函数内部调用 f(x) 时，类型检查器（如 Pyright）会报错：
立即学习“Python免费学习笔记（深入）”；
Argument of type "float | Fraction" cannot be assigned to parameter "x" of type "T@f" in function "f" Type "float | Fraction" is incompatible with constrained type variable "T"
这个错误的核心在于，g 函数的参数 x 被注解为 float | Fraction，这是一个联合类型。这意味着 x 的实际类型在运行时可能是 float 或 Fraction，但在编译时（类型检查时），它被视为这两种类型中的任意一种。然而，f 函数的参数 x: T 要求 T 必须是 float 或 Fraction 中的某一个具体类型。类型检查器无法确定 float | Fraction 这个联合类型是否能匹配 T 所代表的单一具体类型。它不能将一个“可能是 A 或 B”的类型直接赋给一个“必须是 A 或必须是 B”的类型变量，除非这个联合类型本身也是 T 的一个约束。
一个更简单的例子可以说明这一点：
from typing import TypeVar
from fractions import Fraction
T = TypeVar("T", float, Fraction)
def f(x: T) -> T: ...
def getFloatOrFraction() -> float | Fraction: ...
num: float | Fraction = getFloatOrFraction()
# f(num) # 错误：Type "float | Fraction" is incompatible with constrained type variable "T"解决方案
针对上述问题，有两种主要的解决方案，它们适用于不同的场景和需求。
方案一：扩展 TypeVar 约束以包含联合类型
如果你的设计意图是 f 函数能够处理具体的 float 或 Fraction，并且也能够处理一个在运行时可能是其中任何一种的联合类型，那么你需要将这个联合类型本身也作为 TypeVar 的一个约束。
from fractions import Fraction
from typing import TypeVar
# 将联合类型 float | Fraction 添加到 TypeVar 的约束列表中
T = TypeVar("T", float, Fraction, float | Fraction)
def f(x: T) -> T:
"""
现在可以接受 float, Fraction, 或者 float | Fraction
"""
return x * 2
# 测试
f(1.0) # ok
f(Fraction(1, 2)) # ok
def g(x: float | Fraction) -> float | Fraction:
"""
期望一个 float 或 Fraction
"""
return f(x) / 2 # 现在 Pyright 不会报错说明： 通过将 float | Fraction 加入 T 的约束列表，你告诉类型检查器 T 现在可以是 float、Fraction，或者是一个明确的 float | Fraction 类型。当 g 函数中的 x（类型为 float | Fraction）被传递给 f 时，类型检查器会发现 float | Fraction 是 T 的一个有效约束，因此调用是合法的。在这种情况下，f(x) 的返回类型将被推断为 float | Fraction。
适用场景： 当你希望函数对输入类型有严格的控制，并且希望在输入是联合类型时，输出也保持为该联合类型时。
方案二：使用 bound 参数定义 TypeVar 上界
如果你的目标是让 TypeVar 能够接受任何是某个联合类型子类型的类型，而不仅仅是联合类型本身或其精确成员，那么使用 bound 参数是更灵活的选择。bound 参数指定了 TypeVar 的上界，意味着 T 可以是任何继承自或兼容于 bound 所指定类型的类型。
from fractions import Fraction
from typing import TypeVar
# 使用 bound 参数，表示 T 必须是 float 或 Fraction 的子类型
T = TypeVar("T", bound=float | Fraction)
def f(x: T) -> T:
"""
期望任何 float 或 Fraction 的子类型，并返回相同类型的值
"""
return x * 2
# 测试
f(1.0) # ok
f(Fraction(1, 2)) # ok
class MyFloat(float):
pass
def getMyFloatOrFraction() -> MyFloat | Fraction:
return MyFloat(3.14) if True else Fraction(1, 2)
def h(x: MyFloat | Fraction) -> MyFloat | Fraction:
"""
期望 MyFloat 或 Fraction
"""
return f(x) / 2 # 现在 Pyright 不会报错说明： 当 T = TypeVar("T", bound=float | Fraction) 定义时，T 可以是 float 或 Fraction，也可以是它们的任何子类型（例如 MyFloat 是 float 的子类型）。当 h 函数中的 x（类型为 MyFloat | Fraction）被传递给 f 时，类型检查器会推断 T 为 MyFloat | Fraction，这符合 bound=float | Fraction 的要求，因为 MyFloat | Fraction 是 float | Fraction 的一个子类型（或本身）。在这种情况下，f(x) 的返回类型将被推断为 MyFloat | Fraction。
适用场景： 当你希望函数能够处理更广泛的类型，只要它们满足某个基本类型（或联合类型）的契约时。这允许更强的泛型能力，因为 T 可以被推断为比 bound 更具体的类型。
总结与注意事项
- 受约束的 TypeVar (TypeVar("T", A, B))：T 必须是 A 或 B 中的一个精确类型。它不会自动兼容 A | B 这样的联合类型，除非 A | B 也明确列在约束中。
- 带有上界的 TypeVar (TypeVar("T", bound=A | B))：T 可以是任何是 A | B 子类型的类型。这提供了更大的灵活性，因为它允许类型检查器推断出比上界更具体的类型。
在选择使用哪种方法时，请考虑你的泛型函数需要多严格地控制输入类型：
- 如果你需要确保输入类型严格匹配列表中的一个，并且在输入是联合类型时也希望输出是该联合类型，请将联合类型添加到 TypeVar 的约束列表中。
- 如果你希望函数能够处理任何兼容于特定基类型（或联合类型）的类型，并允许类型检查器推断出最具体的类型，那么使用 bound 是更合适的选择。
理解 TypeVar 的这两种不同用法是编写健壮且类型安全的 Python 泛型代码的关键。
