Pyright 对 assert_type 中 Callable 类型的检查基于渐进式等价性（gradual equivalence），而非赋值兼容性，因此参数名必须严格匹配；解决方法是显式写出参数名或改用 typing.cast 进行类型提示。
pyright 对 `assert_type` 中 `callable` 类型的检查基于渐进式等价性（gradual equivalence），而非赋值兼容性，因此参数名必须严格匹配；解决方法是显式写出参数名或改用 `typing.cast` 进行类型提示。
在使用 typing.assert_type 断言函数类型时，Pyright 并不接受“省略参数名”的 Callable[[int], ...] 形式来匹配实际带有参数名（如 n: int）的函数签名。这是因为 Pyright 将 assert_type 视为类型等价性校验（gradual equivalence），而非宽泛的类型兼容性（assignability）。等价性要求两个类型在结构上完全一致——包括参数名称、是否可选、是否带 *args/**kwargs 等细节。
例如，以下代码会触发 Pyright 报错：
from typing import assert_type, Callable
from collections.abc import Callable as ABC_Callable
def tuple_of_nums(n: int) -> tuple[int, ...]:
return tuple(range(n))
# ❌ 错误：Pyright 期望 (n: int) -> ..., 但收到 (int) -> ...
assert_type(tuple_of_nums, Callable[[int], tuple[int, ...]])
报错信息明确指出：expected "(int) -> tuple[int, ...]" but received "(n: int) -> tuple[int, ...]" —— 二者语义不同：前者仅支持位置传参，后者同时支持位置与关键字传参（tuple_of_nums(5) 和 tuple_of_nums(n=5) 均合法）。
✅ 正确做法是在 Callable 类型中显式声明参数名，使用字符串字面量形式（PEP 613 风格）或直接复刻函数签名：
from typing import assert_type, Callable
def tuple_of_nums(n: int) -> tuple[int, ...]:
return tuple(range(n))
# ✅ 正确：参数名 'n' 显式声明，与实际函数签名等价
assert_type(tuple_of_nums, Callable[[int], tuple[int, ...]]) # ❌ 仍错（无名）
assert_type(tuple_of_nums, Callable[["n": int], tuple[int, ...]]) # ✅ Pyright 4.12+ 支持（需启用 `enableExperimentalFeatures`）
# 或更通用且广泛兼容的写法（推荐）：
assert_type(tuple_of_nums, Callable[[int], tuple[int, ...]]) # ❌ 不推荐
# ✅ 推荐：使用 typing.Callable + 参数名注释（兼容所有版本）
from typing import Callable as TypingCallable
assert_type(tuple_of_nums, TypingCallable[[int], tuple[int, ...]]) # 仍不解决命名问题
⚠️ 注意：截至 Pyright v4.13，标准 Callable[[T], R] 语法本身不支持参数名；若需精确匹配带名参数，应改用 typing.Protocol 定义结构化可调用协议：
from typing import Protocol, assert_type, Tuple
class TupleOfNums(Protocol):
def __call__(self, n: int) -> Tuple[int, ...]: ...
assert_type(tuple_of_nums, TupleOfNums) # ✅ 类型等价，且语义清晰
? 总结建议：
-
assert_type是调试/验证工具，非运行时断言，其行为依赖类型检查器实现； - Pyright 采用严格等价性校验，参数名、可变参数、默认值等均需一致；
- 若仅需“让类型检查器信任该值为某类型”，优先考虑
cast（如cast[Callable[[int], tuple[int,...]], tuple_of_nums]），它不进行校验，仅提供类型提示； - 生产代码中，避免对高阶函数类型做
assert_type断言；更推荐通过 Protocol 或显式类型注解（如tuple_of_nums: Callable[[int], tuple[int,...]]）提升可维护性。
