pythoninspect查看函数签名怎么用
本文深入讲解在 Python 中如何使用 inspect 模块的 inspect.signature() 查看并解析函数签名,涵盖基础操作步骤、Parameter 内部属性结构、实参预校验与常见避坑指南。
快速上手:获取并打印函数签名的三个步骤
使用 inspect 模块查看函数签名的核心操作只需三个步骤:第一步导入标准库并准备目标函数;第二步调用 inspect.signature(func) 获得签名对象;第三步通过对象的方法与属性提取详细信息。
import inspect
def calculate_discount(price: float, discount: float = 0.2, *tags, verbose: bool = False) -> float:
"""计算商品折扣价格"""
return price * (1 - discount)
# 步骤 2:生成 Signature 对象
sig = inspect.signature(calculate_discount)
# 直接打印 Signature 对象得到可读文本
print("完整签名展示:", sig)
print("返回值注解:", sig.return_annotation)
返回值注解: <class 'float'>
直接对 Signature 对象使用 str() 或打印,可以快速得到符合 Python 语法习惯的括号签名字符串。这在自动化接口文档生成或命令行工具提示中非常常用。
深入解析:Signature 与 Parameter 对象的内部属性
如果仅获取字符串表现形式,无法在程序中实现动态控制。Signature 对象的核心价值在于它的 parameters 属性。这是一个只读的有序映射字典(MappingProxyType),键是形参的名称字符串,值是对应的 inspect.Parameter 实例。
for name, param in sig.parameters.items():
print(f"参数名称: {name}")
print(f" - 默认值: {param.default}")
print(f" - 类型注解: {param.annotation}")
print(f" - 参数类型 (kind): {param.kind}")
每个 Parameter 实例包含四个核心属性:
- name:形参标识符字符串(例如
'price')。 - default:形参的默认值。如果该参数没有默认值,Python 不会返回
None,而是返回特殊的单例标记inspect.Parameter.empty。 - annotation:形参的类型注解。同样,若未标注类型,其值为
inspect.Parameter.empty。 - kind:参数种类,属于
_ParameterKind枚举类型,用来描述实参应如何传递给该参数。
if param.default is None,因为形参完全可能被显式定义为 def foo(x=None)。正确的判断逻辑是使用 if param.default is inspect.Parameter.empty。
参数种类(kind)的 5 种形态
Python 语法支持灵活的传参规则,inspect.Parameter 将其严格归纳为以下 5 种形态:
| 枚举成员 | 语法表现 | 调用说明 |
|---|---|---|
POSITIONAL_ONLY |
def f(x, /): |
仅位置参数,斜杠前的形参只能按位置传入,不可使用关键字传参。 |
POSITIONAL_OR_KEYWORD |
def f(x, y=1): |
普通参数,既可以通过位置传参,也可以通过关键字形参名传参。 |
VAR_POSITIONAL |
def f(*args): |
可变位置参数元组,接收任意数量的多余位置实参。 |
KEYWORD_ONLY |
def f(*, key): |
命名关键字参数,星号后的形参必须通过显式键值对传入。 |
VAR_KEYWORD |
def f(**kwargs): |
可变关键字参数字典,接收任意多余的键值对实参。 |
进阶实战:使用 bind() 进行实参预校验与默认值补齐
在编写通用框架、API 路由控制器或装饰器时,经常需要在函数尚未真正执行之前,预先验证外部传来的实参是否符合目标函数的签名要求。Signature.bind() 提供了这一原生能力。
调用 sig.bind(*args, **kwargs) 会模拟 Python 的参数绑定机制。如果参数个数不匹配、缺少必需的位置参数或传入了未声明的关键字,该方法会立即抛出 TypeError;如果传参完全合法,则返回一个 BoundArguments 对象。
def register_user(username: str, age: int, role: str = "member"):
pass
sig = inspect.signature(register_user)
# 场景 1:合法传参并自动填充默认值
try:
bound = sig.bind("alice", 25)
bound.apply_defaults() # 将未显式传入但存在默认值的参数自动补全
print("解析出的完整参数映射:", bound.arguments)
except TypeError as err:
print("参数校验失败:", err)
如果传入不符合签名规则的实参(例如漏传了必填参数 age,或者多传了未声明的 unknown_arg):
# 场景 2:非法传参触发 TypeError
try:
sig.bind("alice") # 缺失 age
except TypeError as err:
print("捕获错误:", err)
除了全量绑定的 bind() 外,inspect 还提供了 bind_partial()。它允许缺少部分必选参数,只要已传入的部分合法即可通过。该特性在实现函数柯里化、中间件逐级注入参数等高级设计模式时尤为实用。
特殊场景与常见避坑指南
在复杂的真实工程中,待分析的可调用对象形式多样,以下三个特殊场景需要针对性处理:
1. 被装饰器包装的函数与 follow_wrapped 选项
使用 functools.wraps 包装函数时,被装饰对象通常带有 __wrapped__ 链。默认情况下,inspect.signature(decorated_func, follow_wrapped=True) 会自动穿透装饰器外层包装,直接返回最底层原始函数的签名。
若开发场景中明确需要检查最外层包装器本身的参数接收能力,可显式指定 follow_wrapped=False,阻止内部追溯。
2. C 扩展与内置函数的签名限制
Python 标准库中的很多纯 Python 函数都有完备的签名元数据,但部分由 C 语言直接实现的内建函数(如部分旧版内建操作或未经 Argument Clinic 标注的 C 模块函数)可能没有内置签名信息。对它们调用 inspect.signature() 会引发 ValueError: no signature found for builtin function。
def safe_get_signature(func):
try:
return inspect.signature(func)
except (ValueError, TypeError):
# 降级处理:无法提取元数据时的防御方案
return None
inspect.signature() 包裹在 try-except (ValueError, TypeError) 中,避免因个别底层 C 对象崩溃整个分析任务。
3. 类方法与实例方法的签名差异
通过类直接访问方法与通过实例访问绑定方法时,签名返回的内容不同。类访问时包含 self 参数;而由实例调用 inspect.signature(instance.method) 时,self 已经完成隐式绑定,返回的签名中将不再出现 self 参数。
总结与核心 API 速查
掌握 inspect.signature 的使用,不仅能用于查看函数定义,更是构建轻量级依赖注入、自动校验框架和动态接口适配的基础工具。核心方法总结如下:
inspect.signature(callable):入口函数,获取目标对象的Signature实例。sig.parameters:包含全部参数定义的有序映射,每个元素为Parameter对象。inspect.Parameter.empty:专用的空标记,用于区分“未提供默认值/注解”与真实的None。sig.bind(*args, **kwargs):验证实参与形参匹配性,失败抛出TypeError。bound.apply_defaults():在匹配成功后一键填充默认参数,输出干净的入参字典。
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









