本文介绍一种基于 inspect 模块的可靠方法，通过动态重构函数签名，生成一个参数数量严格增加 1 且签名完全透明的新函数，确保 help()、IDE 参数提示、类型检查等均能正确识别新增参数。
本文介绍一种基于 `inspect` 模块的可靠方法，通过动态重构函数签名，生成一个参数数量严格增加 1 且签名完全透明的新函数，确保 `help()`、ide 参数提示、类型检查等均能正确识别新增参数。
在 Python 中，若需程序化地扩展函数签名（例如为任意函数新增一个带默认值的参数），同时要求新函数的 inspect.signature() 完全等价于手写定义（如 def my_new_func(first, second=2, exclamation='hello')），不能简单使用 *args, **kwargs 包装——因为那会丢失原始参数名、默认值、注解和调用约束。
核心思路是：提取原函数签名 → 构造新签名（追加参数）→ 绑定新逻辑 → 动态创建具有真实签名的函数对象。推荐使用 functools.wraps 配合 inspect.Signature 手动构建：
import inspect
from functools import wraps
def add_argument(func, new_param_name, new_default='hello', new_annotation=str):
"""
返回一个新函数，其签名比 func 多一个位置/关键字参数，
并在调用原函数前执行自定义逻辑（如打印）。
"""
# 获取原函数签名
sig = inspect.signature(func)
params = list(sig.parameters.values())
# 构建新增参数（支持位置+关键字，默认值 + 类型注解）
new_param = inspect.Parameter(
name=new_param_name,
kind=inspect.Parameter.KEYWORD_ONLY, # 确保为仅关键字参数，避免位置冲突
default=new_default,
annotation=new_annotation
)
new_params = params + [new_param]
# 创建新签名
new_sig = sig.replace(parameters=new_params)
@wraps(func)
def wrapper(*args, **kwargs):
# 提取新增参数值（安全获取，避免干扰原函数调用）
exclamation = kwargs.pop(new_param_name, new_default)
print(exclamation)
return func(*args, **kwargs)
# 关键：强制覆盖签名（否则 wrapper 仍显示 *args, **kwargs）
wrapper.__signature__ = new_sig
return wrapper
# 示例使用
def my_func(first: int, second: int = 2) -> int:
return first * second
my_new_func = add_argument(my_func, 'exclamation', 'hello', str)
# ✅ 签名完全匹配预期：
print(inspect.signature(my_new_func))
# (first: int, second: int = 2, *, exclamation: str = 'hello') → 注意：* 表示 exclamation 是 keyword-only
# ✅ 可正常调用（支持位置/关键字混合）
print(my_new_func(5)) # hello\n10
print(my_new_func(5, 3, exclamation='!')) # !\n15
⚠️ 注意事项：
- 新增参数设为 KEYWORD_ONLY（即签名中出现 * 分隔符）是最安全的做法，可避免与原函数的位置参数顺序冲突；若需支持位置传参，需更复杂的参数重排序逻辑（不推荐，易出错）。
- wrapper.__signature__ = new_sig 是关键一步，它覆盖了装饰器默认的泛化签名，使 help(my_new_func)、VS Code 参数提示、typing.get_type_hints 等全部生效。
- 此方案完全保留原函数的 __name__、__doc__、__annotations__ 和运行时行为，符合“签名精确”的核心需求。
总结：通过 inspect.Signature.replace() 动态构造签名 + functools.wraps 保持元数据 + 显式赋值 __signature__，即可实现工业级健壮的函数签名扩展，无需依赖 exec 或 AST 解析，简洁、可维护、兼容性好。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
