ParamSpec 是 Python 3.10 引入的类型原语，专用于精确捕获和转发高阶函数（如装饰器）中被修饰函数的完整参数结构（含名称、数量、默认值、args/*kwargs 约束等）；不用它时，Callable[P, R] 退化为裸 Callable，导致类型检查器无法推导参数类型，进而丢失 IDE 补全、help() 和 inspect.signature() 的准确性。
ParamSpec 是什么，为什么不用它会丢类型信息
Python 3.10 引入 ParamSpec，专门解决高阶函数（比如装饰器）中参数类型丢失的问题。不使用它时，typing.Callable 或裸 Callable 只能描述“某个可调用对象”，无法表达“参数完全等同于原函数，仅返回值不同”。结果是 mypy 报 error: Cannot infer type argument 1 of "Callable"，IDE 也无法跳转或补全被修饰函数的参数。
关键在于：ParamSpec 不是替代 TypeVar，而是和它配合——TypeVar 管返回值，ParamSpec 管参数结构（包括数量、名称、默认值、是否可变等）。
最简可用的 ParamSpec 装饰器写法
下面这个装饰器能 100% 保留原函数签名，连 help() 和 inspect.signature() 都完全一致：
from typing import Callable, TypeVar, ParamSpec, Concatenate
from functools import wraps
P = ParamSpec('P')
R = TypeVar('R')
def log_calls(func: Callable[P, R]) -> Callable[P, R]:
@wraps(func)
def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
print(f"Calling {func.__name__}")
return func(*args, **kwargs)
return wrapper
注意三点：
-
P.args和P.kwargs必须显式用于wrapper的参数注解，不能写成*args, **kwargs（否则类型系统视为泛型可变参数，丢失原始约束） -
@wraps(func)仍需保留，它修复__name__、__doc__等运行时属性，但类型层面的签名还原全靠P - 必须用
Callable[P, R]注解输入函数，不能用Any或Callable[..., R]，否则 mypy 直接放弃推导
遇到 mypy 报错 “Invalid type application” 怎么办 这个错误通常出现在两种场景：
一是用了旧版 mypy（ParamSpec 支持从 mypy 0.930 开始稳定，低于此版本会直接报错。升级命令：pip install -U mypy
二是参数中含关键字限定（keyword-only）或位置限定（positional-only），而你的 Python 版本或 mypy 配置没开相应支持：
立即学习“Python免费学习笔记（深入）”；
- 确保
python_version = "3.10"在mypy.ini中明确指定 - 若函数含
/或*参数分隔符，mypy 需开启--show-traceback查看具体哪一参数未被识别 - 避免在
ParamSpec实例化时加bound=...或contravariant=True—— 这些高级用法在装饰器中极少需要，反而容易触发校验失败
想加额外参数（比如日志级别）又不破坏原签名？用 Concatenate
如果装饰器本身要接收一个新参数（例如 level: str），但又不想让它暴露在被修饰函数调用时，就得用 Concatenate：
from typing import Concatenate
def log_with_level(level: str):
def decorator(func: Callable[Concatenate[str, P], R]) -> Callable[P, R]:
@wraps(func)
def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
print(f"[{level}] Calling {func.__name__}")
return func(*args, **kwargs)
return wrapper
return decorator
这里 Concatenate[str, P] 表示：实际传给 func 的参数列表是 str + 原函数所有参数，但装饰后对外暴露的仍是 P（即原函数签名）。调用时写 @log_with_level("DEBUG")，被修饰函数调用方式完全不变。
注意：Concatenate 的第一个类型是装饰器“自己”的参数，后续才是原函数参数；顺序错、多写或少写都会导致 mypy 推导失败，且错误提示非常模糊——建议先删掉 Concatenate 写通基础版，再逐步加。
ParamSpec 的核心难点不在语法，而在接受它要求你把“参数结构”当作一等类型来思考。很多人卡在第一步：以为写对了 P 就够，却忘了 wrapper 的 *args: P.args 和 **kwargs: P.kwargs 缺一不可。漏掉任一，类型就断了。
