本文详解 MyPy 在泛型函数中报 Incompatible return value type 错误的根本原因，并通过对比上界（upper bound）与约束（constraints）两种类型变量定义方式，给出安全、符合预期的修复方案。
本文详解 mypy 在泛型函数中报 `incompatible return value type` 错误的根本原因，并通过对比上界（upper bound）与约束（constraints）两种类型变量定义方式，给出安全、符合预期的修复方案。
在使用 Python 3.12+ 的泛型语法（如 def func[T: BoundType](...)）时，一个常见误区是将 T: int | None 理解为“T 只能是 int 或 None”。实际上，T: int | None 表示 T 是 int | None 的子类型（subtype）——即上界（upper bound）约束。这意味着 T 可以是 int 的任意子类（如 class MyInt(int): pass），而 MyPy 必须保证：输入 MyInt，就一定返回 MyInt。
但问题在于：value + 1 调用的是 int.__add__，其类型存根明确返回 int（而非 Self），因此运行时 MyInt(3) + 1 得到的是纯 int 实例，而非 MyInt。这导致静态类型检查失败：
from typing import TYPE_CHECKING
def incr[T: int | None](value: T) -> T:
if value is None:
return value
return value + 1 # ❌ MyPy 报错：got "int", expected "T"✅ 正确解法是改用约束型类型变量（constrained type variable），即 T: (int, None)。它表示 T 必须精确等于 int 或 None 二者之一（非子类型），从而允许 MyPy 在类型推导时安全地将 int 结果向上转换（up-cast）为声明的 T：
def incr[T: (int, None)](value: T) -> T:
if value is None:
return value
return value + 1 # ✅ 合法：当 T 是 int 时，int → int；当 T 是 None 时，分支已覆盖
# 类型推导示例：
reveal_type(incr(None)) # Revealed type is "None"
reveal_type(incr(42)) # Revealed type is "builtins.int"⚠️ 注意事项：
立即学习“Python免费学习笔记（深入）”；
- 不要混淆
T: A | B（上界，允许子类型）与T: (A, B)（约束，仅限枚举值）； - 若需支持自定义数值子类并保持类型精确性，应显式重载
__add__并标注返回Self，或改用协议（Protocol）抽象； -
None在约束元组中是合法成员，但需确保所有分支逻辑覆盖全部约束类型，避免运行时TypeError（如对None + 1的调用已被if拦截）。
总结：当目标是“输入 int/None → 输出同类型”，务必使用约束 T: (int, None)；若需建模“输入某子类 → 输出同子类”，则需更精细的设计（如 Self 或协变协议）。类型安全始于对泛型语义的准确理解。
