Python inspect.signature 怎样读取装饰器保留的参数

装饰器经常把原函数包成 (*args, **kwargs)，这会让文档生成器、参数校验器或调用适配器看不到原来的参数。解决办法通常不是手动解析字符串，而是让包装器保留 __wrapped__，再用 inspect.signature() 读取 Signature 对象。

官方地址：https://docs.python.org/3/library/inspect.html#inspect.signature

默认情况下，inspect.signature() 会沿着装饰器留下的 __wrapped__ 链寻找原函数；使用 functools.wraps 生成包装器，通常就能恢复原参数签名。若要检查包装器自己的接口，传入 follow_wrapped=False。

先看 inspect.signature 返回什么

inspect.signature(callable) 返回一个 Signature 对象。它不是只能展示的字符串：parameters 是按声明顺序保存参数的有序映射，每个值都是 Parameter，可以继续读取参数种类、默认值和注解。

from inspect import Parameter, signature


def load_page(path: str, *, limit: int = 20) -> list[str]:
    # 这个函数同时展示位置参数、关键字专用参数、默认值和返回注解。
    return [path] * limit


sig = signature(load_page)
print(str(sig))
for name, parameter in sig.parameters.items():
    # kind 能区分普通参数、关键字专用参数以及 *args/**kwargs。
    print(name, parameter.kind, parameter.default, parameter.annotation)

实际使用时，优先读取 sig.parameters，而不是对 str(sig) 做切片。字符串适合展示，结构化的 Parameter 才适合生成表单、校验调用参数或拼装适配层。

让装饰器保留原函数签名

一个没有元数据处理的装饰器，返回的包装函数通常只有 *args 和 **kwargs。functools.wraps 是最小改动：它会复制常用元数据，并让包装器拥有指向原函数的 __wrapped__ 属性。默认的 signature() 才能沿这条链继续查找。

from functools import wraps
from inspect import signature


def traced(function):
    # wraps 让内省工具知道 wrapper 代理的是哪个原函数。
    @wraps(function)
    def wrapper(*args, **kwargs):
        # 这里可以记录调用，但不要改变原函数的参数传递规则。
        return function(*args, **kwargs)

    return wrapper


@traced
def create_user(name: str, *, active: bool = True) -> dict:
    # 示例返回一个简单对象，重点是观察签名元数据。
    return {"name": name, "active": active}


print(signature(create_user))
print(create_user.__wrapped__.__name__)

这里的 create_user 实际调用对象仍然是 wrapper，但 signature(create_user) 默认会解包到 create_user(name: str, *, active: bool = True) -> dict。这解决的是“公开调用契约如何被发现”，并不代表装饰器自动完成参数校验。

什么时候使用 follow_wrapped=False

默认的 follow_wrapped=True 适合回答“调用方应该看到什么参数”。如果正在开发装饰器本身，想知道包装器真正接收的接口，就关闭自动解包：

from inspect import signature


wrapped_signature = signature(create_user, follow_wrapped=False)
public_signature = signature(create_user)

# 关闭解包后看到的是 wrapper 的 *args/**kwargs 接口。
print(wrapped_signature)
# 默认解包后看到的是原函数的公开调用签名。
print(public_signature)

这两个结果用途不同：前者用于排查包装器层是否把调用交给下游，后者用于生成文档或让调用适配器理解业务函数。不要把 follow_wrapped=False 当成修复签名丢失的方法，它只是选择了另一层对象。

确实需要代理接口时再设置 __signature__

有些适配器的公开参数并不等于内部函数参数，例如包装器只接受一个配置对象，却希望文档展示拆开的字段。这时可以构造一个 Signature 并赋给 __signature__。Python 文档将该属性的使用说明列为 CPython 实现细节，因此必须把它当作明确的公开契约维护，而不是随意伪造。

from inspect import Parameter, Signature, signature


def proxy(*args, **kwargs):
    # 内部实现仍然按代理层的真实入口接收参数。
    return {"args": args, "kwargs": kwargs}


proxy.__signature__ = Signature([
    # 公开契约必须与适配器实际支持的调用方式保持一致。
    Parameter("name", Parameter.POSITIONAL_OR_KEYWORD, annotation=str),
    Parameter("active", Parameter.KEYWORD_ONLY, default=True, annotation=bool),
])

print(signature(proxy))

设置后，signature(proxy) 会优先得到这份公开签名。若真实的 proxy 并不能处理 active，文档和调用器就会被误导，所以更推荐在“代理接口稳定、内部实现有意隐藏”时使用它。

用 Signature.bind 做调用适配

签名读出来以后，可以用 bind() 把位置参数和关键字参数绑定成名字映射。绑定失败会抛出 TypeError，比自己统计参数数量更可靠；bind_partial() 则允许缺少部分必填参数，适合分阶段构造调用。

from inspect import signature


def send_message(topic: str, body: str, *, retry: int = 2) -> None:
    # 这里仅定义调用契约，不执行网络发送。
    return None


sig = signature(send_message)
bound = sig.bind("events", "ready", retry=3)
bound.apply_defaults()

# arguments 是可直接交给适配层继续处理的参数名映射。
print(bound.arguments)

try:
    # 缺少 body 时，bind 会给出参数契约错误。
    sig.bind("events")
except TypeError as exc:
    # 适配层可以把异常转换为自己的输入错误，而不是吞掉它。
    print(f"参数不完整：{exc}")

装饰器签名问题的常见边界

小结

如果目标是让装饰器后的函数继续暴露原参数，先在包装器上使用 functools.wraps；如果目标是检查包装器自身，使用 follow_wrapped=False；如果目标是设计一个与内部实现不同的稳定代理接口，才考虑 __signature__。读取结果后，用 Signature.parameters 和 bind() 处理结构化参数，避免围绕字符串签名写脆弱逻辑。

相关问题

为什么用了 wraps 仍然看不到想要的参数？

检查是否对外层又套了一层没有使用 wraps 的装饰器，也检查调用时是否传入了 follow_wrapped=False。多层包装时，每一层都应维护正确的 __wrapped__ 链。

bind 和 bind_partial 有什么区别？

bind 要求必填参数齐全，bind_partial 允许暂时缺少参数，适合把调用拆成多个阶段。两者都只做签名绑定，不会替你调用目标函数。

可以直接修改 Signature.parameters 吗？

不建议。Signature 和 Parameter 都是不可变对象，应使用 Signature.replace() 或 Parameter.replace() 生成修改后的副本。