在 Python 的类型提示体系中，当我们想要编写一个可以接收任意函数并返回包装后的函数的泛型组件时，传统方式很难完整保留原函数的参数类型信息，ParamSpec 的出现很好地解决了这个问题。
什么是 ParamSpec
ParamSpec 是 typing 模块中引入的一种特殊类型变量，它的作用是捕获函数的参数规格，包括参数的类型、数量、默认值等信息，而不是像普通的 TypeVar 那样只能捕获单个类型。它可以和 Callable 等类型结合使用，实现对函数参数类型的完整保存和转发。
要使用 ParamSpec，首先需要确保 Python 版本在 3.10 及以上，或者从 typing_extensions 中导入兼容版本：
from typing import Callable, TypeVar # Python 3.10+ 可以直接从 typing 导入 from typing import ParamSpec # 如果是更低版本，可以从 typing_extensions 导入 # from typing_extensions import ParamSpec
传统参数类型转发的不足
在没有 ParamSpec 之前，我们如果尝试编写一个通用的装饰器来转发参数类型，通常会遇到类型信息丢失的问题。比如下面这个简单的装饰器示例：
from typing import Callable, Any
def simple_decorator(func: Callable[..., Any]) -> Callable[..., Any]:
def wrapper(*args: Any, **kwargs: Any) -> Any:
print("调用函数前")
result = func(*args, **kwargs)
print("调用函数后")
return result
return wrapper
@simple_decorator
def add(a: int, b: int) -> int:
return a + b
# 此时类型检查器无法得知 wrapper 接收的参数是两个 int，返回值也是 int
reveal_type(add) # 输出会是 Callable[..., Any]，丢失了原函数的参数类型信息
可以看到，用Callable[..., Any]的方式只能表示函数接收任意参数、返回任意类型，无法保留原函数的具体参数类型，这对类型检查非常不友好。
使用 ParamSpec 实现精确参数转发
ParamSpec 可以捕获原函数的参数规格，结合 TypeVar 捕获返回值类型，就能实现参数和返回值类型的完整转发。下面是改造后的装饰器示例：
from typing import Callable, TypeVar, ParamSpec
# 定义 ParamSpec 捕获参数规格
P = ParamSpec("P")
# 定义 TypeVar 捕获返回值类型
T = TypeVar("T")
def precise_decorator(func: Callable[P, T]) -> Callable[P, T]:
def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
print("调用函数前")
result = func(*args, **kwargs)
print("调用函数后")
return result
return wrapper
@precise_decorator
def add(a: int, b: int) -> int:
return a + b
@precise_decorator
def greet(name: str, prefix: str = "Hello") -> str:
return f"{prefix}, {name}"
# 此时类型信息被完整保留
reveal_type(add) # 输出 Callable[[int, int], int]
reveal_type(greet) # 输出 Callable[[str, str], str]
这里的核心逻辑是：ParamSpec 变量 P 捕获了被装饰函数的所有参数信息，P.args 表示位置参数的类型元组，P.kwargs 表示关键字参数的类型字典，结合 TypeVar T 捕获返回值类型，最终 wrapper 函数的类型就和原函数完全一致了。
ParamSpec 的常见使用场景
通用高阶函数
除了装饰器，ParamSpec 也适合用在各类通用高阶函数中，比如下面的函数用于统计另一个函数的执行时间，同时保留原函数的类型：
import time
from typing import Callable, TypeVar, ParamSpec
P = ParamSpec("P")
T = TypeVar("T")
def time_it(func: Callable[P, T]) -> Callable[P, T]:
def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
start = time.perf_counter()
result = func(*args, **kwargs)
end = time.perf_counter()
print(f"函数 {func.__name__} 执行耗时: {end - start:.6f} 秒")
return result
return wrapper
@time_it
def calculate_sum(n: int) -> int:
return sum(range(n))
result = calculate_sum(100000)
# 类型检查器可以正确识别 calculate_sum 接收 int 参数，返回 int
泛型类的回调函数
在定义泛型类的时候，如果类需要接收一个回调函数作为参数，也可以用 ParamSpec 来保留回调函数的参数类型：
from typing import Callable, Generic, ParamSpec, TypeVar
P = ParamSpec("P")
T = TypeVar("T")
class CallbackHandler(Generic[P, T]):
def __init__(self, callback: Callable[P, T]):
self.callback = callback
def run(self, *args: P.args, **kwargs: P.kwargs) -> T:
return self.callback(*args, **kwargs)
def multiply(x: int, y: int) -> int:
return x * y
handler = CallbackHandler(multiply)
# handler.run 的类型会被正确推断为接收两个 int，返回 int
res = handler.run(3, 4)
使用注意事项
- ParamSpec 只能用于捕获函数的参数规格，不能用于其他场景，比如捕获类的泛型参数。
- 在使用 ParamSpec 的时候，P.args 和 P.kwargs 必须同时出现在函数的参数列表中，不能单独使用其中一个。
- 如果不需要捕获返回值类型，可以只使用 ParamSpec，不需要搭配 TypeVar，比如只需要转发参数类型不需要关心返回值的场景。
- 低版本 Python 使用 ParamSpec 需要从 typing_extensions 库安装导入，保证兼容性。
通过 ParamSpec 特性，我们可以在 Python 泛型编程中完整保留函数的参数类型信息，让类型提示更加准确，减少类型检查的错误，提升代码的可维护性和可读性。