TypeVarTuple

是用于类型检查器表达“一串未知长度类型变量”的静态工具，需配合 Unpack 使用，仅支持函数参数、返回值和元组注解，不可运行时操作或设 bound/default。

什么是 TypeVarTuple？它不是用来“处理”类型参数的工具

TypeVarTuple 本身不处理、不解析、也不运行时检查类型参数；它只是让类型检查器（如 mypy、pyright）能表达「一串未知长度的类型变量」。你不能对它做 len()、索引或迭代，它在运行时只是个空的 typing.TypeVarTuple 实例。

它的核心用途是配合 Unpack[T] 在泛型签名中占位，比如函数接受任意多个不同类型的位置参数，或类支持变长元组类型。

常见错误现象：TypeError: 'TypeVarTuple' object is not subscriptable —— 试图像 Ts[0] 这样取元素；或者用 isinstance(x, Ts) 做运行时判断 —— 这毫无意义，因为 Ts 没有运行时行为。

怎么声明和使用 TypeVarTuple 配合 Unpack

必须成对出现：先定义 TypeVarTuple，再在形参/返回值中用 Unpack[...] 展开。否则类型检查器无法推导。

• 声明方式：Ts = TypeVarTuple('Ts')（字符串名需与变量名一致，否则 mypy 报错）
• 函数签名中必须显式写 *args: Unpack[Ts] 或 tuple: tuple[Unpack[Ts]]，不能只写 *args 或 tuple
• 调用时传入的具体类型，由类型检查器根据实参自动推导为元组形式，例如传 (int, str, bool) → 推出 Ts = (int, str, bool)

示例：

from typing import TypeVarTuple, Unpack, Callable
Ts = TypeVarTuple('Ts')
def apply_all(f: Callable[[Unpack[Ts]], int], args: Unpack[Ts]) -> int:
return f(args)
mypy 能正确推导：apply_all(lambda x, y: x+y, 1, 'a') → error
apply_all(lambda x, y: x+y, 1, 2) → ok，Ts = (int, int)

为什么不能用 TypeVarTuple 替代 *args: Any 或普通泛型？

它解决的是「类型维度上的可变性」，不是值维度。如果你只需要接收任意数量的值，用 *args 就够了；只有当你需要为每个位置都保留独立类型信息，并在返回值或其它参数中复用这些类型时，才需要 TypeVarTuple。

• 性能无影响：纯静态类型信息，不生成额外代码或运行时开销
• 兼容性注意：Python TypeVarTuple，旧版本会直接报错
• 替代方案有限：没有 TypeVarList 或 TypeVarDict；也不能用于关键字参数（**kwargs 不支持类型展开）

容易被忽略的限制：嵌套、约束、默认值都不行

TypeVarTuple 不能设 bound、不能设 contravariant、不能指定 default（Python 3.13+ 仍不支持 default），也不能出现在嵌套展开中，比如 list[Unpack[Ts]] 是非法的 —— 只允许在元组、函数参数列表、函数返回值这三处。

常见翻车点：

• def f(x: list[Unpack[Ts]]) -> None: → mypy 报 Invalid type application
• Ts = TypeVarTuple('Ts', bound=SupportsFloat) → 语法错误，TypeVarTuple 不接受 bound
• 试图在类型别名里提前展开：Alias = tuple[Unpack[Ts]] → 合法，但这个别名只能用在支持 Unpack 的上下文中，不能单独做类型注解

真正要用好它，得先想清楚：你是否真的需要每个参数的类型都被独立追踪，并且这些类型要在别处被完整复现？如果不是，大概率是在过度设计。