类型变量与联合类型的兼容性挑战
在python的类型提示系统中，typing模块提供了强大的工具来增强代码的可读性和可维护性。typevar（类型变量）允许我们创建泛型函数或类，确保输入和输出之间存在类型关联。然而，当typevar与联合类型（如float | np.ndarray）结合使用时，可能会遇到出乎意料的类型检查错误，尤其是在使用pyright等静态类型分析工具时。
考虑以下场景，我们定义了一个泛型函数 f，它期望输入是 float 或 np.ndarray，并返回相同类型的值：
from typing import TypeVar
import numpy as np
T = TypeVar("T", float, np.ndarray)
def f(x: T) -> T:
"""
期望接收一个浮点数或一个NumPy数组，并返回相同类型的值
"""
return x * 2
f(1) # 类型检查通过
f(np.array([1, 2, 3])) # 类型检查通过现在，我们定义另一个函数 g，它接受一个 float 或 np.ndarray 的联合类型作为输入，并尝试将其传递给 f：
def g(x: float | np.ndarray) -> float | np.ndarray:
"""
期望接收一个浮点数或一个NumPy数组
"""
return f(x) / 2在此处，Pyright会报告一个类型错误：
Argument of type "float | ndarray[Unknown, Unknown]" cannot be assigned to parameter "x" of type "T@f" in function "f" Type "float | ndarray[Unknown, Unknown]" is incompatible with constrained type variable "T"
这个错误表明，尽管 x 的类型 float | np.ndarray 直观上包含了 f 函数所期望的 float 或 np.ndarray，但类型检查器却认为它们不兼容。
立即学习“Python免费学习笔记（深入）”；
理解约束型TypeVar
问题的核心在于对 TypeVar 定义方式的理解。当 TypeVar 像 T = TypeVar("T", float, np.ndarray) 这样定义时，它被称为一个约束型TypeVar。这意味着 T 在任何特定的调用点，都必须被精确地推断为 float 或 np.ndarray 中的一个。
例如，在 f(1.0) 中，T 被精确推断为 float。在 f(np.array([1, 2, 3])) 中，T 被精确推断为 np.ndarray。对于字面量 1，类型检查器通常会将其视为 int，并根据上下文将其提升为 float 或进行兼容性处理。
为什么联合类型与约束型TypeVar不兼容
当我们将一个联合类型 float | np.ndarray 传递给期望 T 的参数时，类型检查器无法确定 T 应该被精确推断为 float 还是 np.ndarray。它知道 x 可能是 float，也 可能是 np.ndarray，但它不能在编译时确定 x 就是 float 或 就是 np.ndarray。对于约束型 TypeVar 而言，这种不确定性导致了类型不匹配的错误。T 期望的是一个确定的具体类型（来自其约束列表），而不是一个类型集合。
解决方案一：在TypeVar约束中显式包含联合类型
如果你的泛型函数确实需要能够处理一个联合类型，并且希望在输入是联合类型时，其返回类型也反映为该联合类型，那么你需要将该联合类型本身作为 TypeVar 的一个有效约束。
from typing import TypeVar, Union
from fractions import Fraction # 使用Fraction替代np.ndarray以简化示例，行为一致
# T现在可以被推断为 float, Fraction, 或者 float | Fraction
# 注意：Union[float, Fraction] 等同于 float | Fraction
T = TypeVar("T", float, Fraction, Union[float, Fraction])
def f_constrained_union(x: T) -> T:
"""
期望接收一个浮点数、一个Fraction或它们的联合类型，并返回相同类型的值。
当输入为联合类型时，返回类型也将是联合类型。
"""
return x * 2
def g_constrained_union(x: float | Fraction) -> float | Fraction:
"""
期望接收一个浮点数或一个Fraction。
"""
# 现在类型检查通过
return f_constrained_union(x) / 2
# 示例
val_float: float = f_constrained_union(1.0) # T推断为float
val_fraction: Fraction = f_constrained_union(Fraction(1, 2)) # T推断为Fraction
# 当传入联合类型时，T被推断为 Union[float, Fraction]
val_union: float | Fraction = g_constrained_union(1.0)
val_union_2: float | Fraction = g_constrained_union(Fraction(1, 2))在这个方案中，当 g_constrained_union 将 x: float | Fraction 传递给 f_constrained_union 时，T 被成功推断为 float | Fraction，从而解决了类型不兼容的问题。
解决方案二：使用带有上界（bound）的TypeVar
如果你的泛型函数不需要严格限制输入类型为 TypeVar 约束列表中的精确类型，而是希望 TypeVar 能够接受任何是某个基类型或联合类型子类型的类型，那么使用带有上界 (bound) 的 TypeVar 是一个更灵活的选择。
T = TypeVar("T", bound=float | Fraction) 意味着 T 可以是 float、Fraction，或者是任何 float 或 Fraction 的子类型。关键在于，这种方式下，TypeVar 会保留输入参数的原始具体类型，并将其作为返回类型。
from typing import TypeVar, Union
from fractions import Fraction
# T_bound 可以是 float 或 Fraction 的任何子类型
T_bound = TypeVar("T_bound", bound=Union[float, Fraction])
def f_bounded(x: T_bound) -> T_bound:
"""
期望接收一个float或Fraction的子类型，并返回相同类型的值。
"""
return x * 2
def g_bounded(x: float | Fraction) -> float | Fraction:
"""
期望接收一个浮点数或一个Fraction。
"""
# 类型检查通过
return f_bounded(x) / 2
# 示例
class MyFloat(float): # MyFloat是float的子类型
pass
my_float_instance = MyFloat(3.14)
val_myfloat: MyFloat = f_bounded(my_float_instance) # T_bound推断为MyFloat
# 当传入联合类型时，T_bound被推断为 Union[float, Fraction]
val_float_or_fraction: float | Fraction = g_bounded(1.0)使用 bound 的主要优点是它能更好地保留类型信息。例如，如果 f_bounded 接收 MyFloat，它将返回 MyFloat，而不是仅仅 float。当传入联合类型 float | Fraction 时，T_bound 会被推断为 float | Fraction，同样解决了兼容性问题。
特殊情况：内置数字类型（float | int）
值得注意的是，在原始问题中，当 TypeVar 定义为 T = TypeVar("T", float, int) 并且传入 float | int 时，Pyright 并没有报错。这通常是因为 int 在Python的类型系统中，虽然不直接是 float 的子类型，但在许多数值操作和类型检查规则中，int 类型的值可以安全地用在期望 float 的地方，存在一种隐式的向上转型或特殊的协变处理。这种行为可能因类型检查器而异，但对于非内置的、不构成子类型关系的类型（如 float 和 Fraction 或 np.ndarray），上述的兼容性问题就会显现。
总结与最佳实践
- 约束型 TypeVar (TypeVar("T", Type1, Type2))：用于当你的泛型函数需要 T 精确地是约束列表中的某个类型时。如果需要处理联合类型，必须将该联合类型显式地添加到约束列表中。这种方法在需要精确控制 T 的推断结果为特定类型或其联合时非常有用。
- 上界型 TypeVar (TypeVar("T", bound=Union[Type1, Type2]))：用于当你的泛型函数需要 T 是某个基类型或联合类型的子类型时。它更灵活，能够保留传入参数的原始具体类型。这是处理泛型与联合类型兼容性问题的一种常用且推荐的方法，尤其是在希望泛型函数能接受更广泛的相关类型时。
选择哪种方法取决于你的具体需求：如果你需要 T 严格匹配预定义列表中的一个类型，并且在传入联合类型时希望返回类型也是该联合类型，请使用方案一。如果你需要更灵活的类型匹配，并希望泛型函数能够保留其输入参数的特定类型（只要它是上界类型的子类型），那么方案二（使用 bound）是更合适的选择。理解这两种 TypeVar 的行为差异是编写健壮且类型安全的Python代码的关键。
