Python inspect.signature 绑定函数参数：bind、缺省值与调用前校验

命令分发器里最难受的一类报错，不是函数本身写错，而是配置文件把参数名拼错了，直到真正调用处理函数时才抛出 TypeError。如果调用目标是动态选择的，先用 inspect.signature 取得签名，再用 Signature.bind 做一次真实绑定，就能把“能不能这样调用”提前验证出来。

bind 负责按 Python 的调用规则匹配参数，匹配失败立即抛出 TypeError；需要把缺省值也展开时，再对返回的 BoundArguments 调用 apply_defaults()。

参数错误为什么总是拖到真正调用才暴露

假设系统根据配置选择 resize_image 或 archive_image，统一把字典交给函数。直接写成 handler(**payload) 看起来很短，但参数名写成 qualityy、同时传入位置值和同名关键字，或者漏掉必需参数时，错误点已经靠近业务副作用了。

这次排查先固定一个小函数，让问题只剩“参数如何被解释”：

def publish_record(record_id: int, *, channel: str = "draft", labels: tuple[str, ...] = ()) -> str:
    return f"{record_id}:{channel}:{','.join(labels)}"

payload = {"record_id": 17, "channel": "review"}

目标不是改写函数，而是在调用前把 payload 绑定到 publish_record 的签名。这样真正执行函数前，参数形状已经有一份可检查的证据。

先看 inspect.signature 给出的调用边界

inspect.signature(publish_record) 返回一个 Signature 对象。它的 parameters 保存参数顺序、参数种类和默认值：record_id 是必需的位置或关键字参数，channel 与 labels 是仅关键字参数，后两者都有缺省值。

这里先不要把 parameters 当成类型校验器。它能判断参数名和调用形式是否匹配，却不会自动保证传入的字符串真的是标注里的 int。类型检查是另一层职责。

用 Signature.bind 把配置绑定成可复查结果

绑定动作沿着 inspect.signature → bind → BoundArguments 这条链走。返回对象的 arguments 是一个可变映射，只包含显式绑定的值；绑定失败则直接得到 TypeError，不会返回半成品。

import inspect

def validate_call(handler, payload: dict[str, object]):
    signature = inspect.signature(handler)
    bound = signature.bind(**payload)
    bound.apply_defaults()
    return bound

bound = validate_call(publish_record, payload)
print(bound.arguments)
print(bound.args, bound.kwargs)
# {'record_id': 17, 'channel': 'review', 'labels': ()}
# (17,) {'channel': 'review', 'labels': ()}

apply_defaults() 之后，channel 和 labels 都进入规范化结果；其中可变位置参数会补成空 tuple，可变关键字参数会补成空 dict。接下来可把 bound.args 与 bound.kwargs 交给真正的处理函数，调用形式由绑定结果统一生成。

从错误分支定位到调用前门禁

多传或拼错关键字

signature.bind(record_id=17, qualityy="high") 会抛出 TypeError。这比让 publish_record(**payload) 进入业务函数更容易记录：日志可以保存处理器名称和被拒绝的字段，但不要把整份可能含敏感值的配置原样写入日志。

位置参数和关键字重复

signature.bind(17, record_id=18) 同样失败，因为 record_id 已经由位置参数占用。这个检查尤其适合把“通用位置参数列表”和“配置字典”合并的代码，避免重复字段悄悄覆盖。

bind_partial 不是放宽所有规则

bind_partial 允许暂时缺少必需参数，适合构建分阶段配置或模拟 functools.partial 的场景；它仍会拒绝未知参数、错误的位置关系和重复传参。最终执行前仍应使用完整的 bind。

验证结果：先绑定，再产生副作用

可以把动态调用收口成下面的顺序：选择处理函数，取得签名，绑定输入，补齐缺省值，最后才执行。绑定异常应该转成带处理器名和字段名的配置错误；真实函数只接收已经通过匹配的 args 与 kwargs。

def call_checked(handler, payload):
    signature = inspect.signature(handler)
    try:
        bound = signature.bind(**payload)
    except TypeError as exc:
        raise ValueError(f"invalid payload for {handler.__name__}: {exc}") from exc
    bound.apply_defaults()
    return handler(*bound.args, **bound.kwargs)

print(call_checked(publish_record, payload))
# 17:review:

验收时至少覆盖：缺少 record_id、未知关键字、重复传参、缺省值展开和带 *args/**kwargs 的目标函数。若还需要检查值的类型或业务取值范围，放在绑定成功之后、真正调用之前。

相关问题

bind 会检查类型注解吗？

不会。它检查的是调用签名和参数组织方式；record_id 即使传入字符串，只要调用形式匹配，绑定仍可能成功。类型与业务规则要单独校验。

什么时候用 bind_partial？

当参数还在分阶段收集，或你确实要模拟部分应用时使用。进入真实执行边界前，再用 bind 确认必需参数齐全。

为什么绑定结果里没有缺省参数？

BoundArguments 默认只记录显式传入值。需要完整参数快照时调用 apply_defaults()，它会补入普通缺省值以及空的可变参数容器。

可以直接修改 bound.arguments 吗？

可以，它是可变映射，修改后会影响 args 和 kwargs 的动态计算结果。修改前仍要重新做类型和业务范围校验。

动态函数调用真正需要防的是“参数错误已经进入业务流程”。把 inspect.signature、bind 和 apply_defaults 放在副作用之前，既能保留 Python 原生的参数语义，也能让错误日志更接近配置来源。