Mypy 单参数与可变参数类型重载指南

本文介绍如何使用 Mypy 的高级泛型与 `TypeVarTuple` 实现对 `foo(x)`（单参数）和 `foo(x, y, z, ...)`（多参数）两种调用形式的精准类型区分，避免运行时类型模糊，提升静态检查准确性。

在 Python 类型提示中，仅靠 *args 无法自然区分“单个参数”与“多个参数”的语义差异——因为 *a: int 在类型层面允许 0 个或多个参数，而 foo(1) 和 foo(1, 2) 都会匹配同一签名，导致重载失效。解决这一问题的关键在于显式建模参数数量与结构：将单参数调用视为特例（1 个位置参数），将多参数调用建模为“至少两个具名参数 + 零或多个额外参数”，从而让 Mypy 能基于调用实参个数和位置性（/ 分隔符）准确选择重载分支。

以下是推荐的、经 Mypy（≥1.10）和 Pyright 验证的实现方案：

from typing import overload, TypeVar, TypeVarTuple

T = TypeVar('T')
T2 = TypeVar('T2')
Ts = TypeVarTuple('Ts')

@overload
def foo(a: T, /) -> T:
    """单参数调用：返回原值，类型精确保留。"""

@overload
def foo(a0: T, a1: T2, /, *rest: *Ts) -> tuple[T, T2, *Ts]:
    """双参数及以上调用：返回元组，保持各参数原始类型（含类型推导）。"""

def foo(a: T, /, *rest: *Ts) -> T | tuple[T, *Ts]:
    if len(rest) == 0:
        return a
    return (a, *rest)

✅ 关键设计说明：

• 使用 / 强制位置参数，防止关键字传参干扰重载解析（如 foo(a=1) 会被拒绝）；
• 第二个重载明确要求 至少两个位置参数（a0, a1），再配合 *rest: *Ts 捕获剩余参数，使 foo(1, 2) 和 foo(1, 2, 3) 均命中该分支；
• TypeVarTuple（Ts）确保元组元素类型被逐个保留（协变推导），例如 foo(1, 2.0, "hello") 返回 tuple[int, float, str]；
• 运行时逻辑简洁：仅通过 len(rest) 判断是否为单参数调用，零开销。

? 类型检查效果验证：

reveal_type(foo(1))           # Revealed type is "builtins.int"
reveal_type(foo(1, 2))        # Revealed type is "tuple[builtins.int, builtins.int]"
reveal_type(foo(1, 2.0, "x")) # Revealed type is "tuple[builtins.int, builtins.float, Literal['x']]"

foo()                         # error: Missing 1 required positional argument
foo(1, bar=2)                 # error: Unexpected keyword argument "bar"

⚠️ 注意事项：

• 此方案要求 Python ≥ 3.11（TypeVarTuple 自 Python 3.11 引入）及 Mypy ≥ 1.10（完整支持 *Ts 解包语法）；
• 不要尝试用 Union[T, tuple[T, ...]] 替代重载——这会丢失参数个数与类型的精细信息，导致 foo(1, 2) 被误判为 int | tuple[int, ...]，丧失类型安全性；
• 若需兼容旧版 Python（<3.11），可退化为固定元组重载（如 foo(a: int), foo(a: int, b: int), foo(a: int, b: int, c: int)），但会失去任意长度支持。

综上，通过 TypeVarTuple 与强制位置参数的组合，我们不仅能优雅表达“单参数直返、多参数打包”的语义，还能让类型检查器完全理解调用意图——无需放弃 * 的简洁性，也无需牺牲类型精度。