Python装饰器保留函数名和文档说明方法

文章不知道大家是否熟悉？今天我将给大家介绍《Python装饰器保留函数名和文档字符串的方法》，这篇文章主要会讲到等等知识点，如果你在看完本篇文章后，有更好的建议或者发现哪里有问题，希望大家都能积极评论指出，谢谢！希望我们能一起加油进步！

被装饰函数的__name__和__doc__丢失是因为装饰器用新函数替换了原函数，而wrapper默认携带自身元数据；functools.wraps可自动同步__name__、__doc__等属性，避免手动赋值遗漏，类装饰器及嵌套装饰器中同样必须使用。

为什么被装饰函数的 __name__ 和 __doc__ 会丢失

Python 装饰器本质是用新函数替换了原函数对象。如果装饰器内部直接返回一个普通闭包（比如 def wrapper(*args, **kwargs): ...），那么这个 wrapper 的 __name__ 就是 "wrapper"，__doc__ 也来自它自身，和原函数无关。常见现象包括：help(my_decorated_func) 显示的是装饰器里的文档，而不是原函数的；my_decorated_func.__name__ 返回 "wrapper" 而非预期名称。

用 functools.wraps 一键同步元数据

functools.wraps 是标准解法，它本身是个装饰器，作用是把被装饰函数的 __module__、__name__、__qualname__、__doc__、__annotations__ 等属性复制到包装函数上。

使用方式很简单：

from functools import wraps
<p>def my_decorator(func):
@wraps(func)  # ← 关键：加在这儿
def wrapper(*args, *<em>kwargs):
print("Before")
result = func(</em>args, **kwargs)
print("After")
return result
return wrapper</p><p>@my_decorator
def say_hello():
"""Say hello to the world."""
return "Hello!"
</p>

此时 say_hello.__name__ 是 "say_hello"，say_hello.__doc__ 也是 "Say hello to the world."。

不使用 @wraps 时手动同步的隐患

有人尝试手动赋值，比如在 wrapper 内部写 wrapper.__name__ = func.__name__，但这只解决表面问题：

• __doc__、__module__、__annotations__、__dict__ 等都得逐个处理，容易遗漏
• __wrapped__ 属性不会自动建立，导致无法通过 inspect.unwrap() 反向获取原始函数
• 某些框架（如 Flask、Click）依赖完整的元数据，手动同步可能引发兼容性问题
• Python 3.12+ 对 __qualname__ 和嵌套函数名更敏感，漏掉会导致调试困难

装饰器类里也要用 wraps 吗

要。即使你写的是类装饰器，只要返回的是可调用对象（比如实现了 __call__），且希望保留原函数元数据，就必须在 __call__ 内部或返回的包装函数上应用 @wraps。

例如：

from functools import wraps
<p>class CountCalls:
def <strong>init</strong>(self, func):
self.func = func
self.count = 0</p><h1>注意：这里不能直接 wraps(self)，因为 self 不是函数</h1><pre class="brush:php;toolbar:false"><code>def __call__(self, *args, **kwargs):
    self.count += 1
    @wraps(self.func)  # ← 必须在这里 wrap 包装逻辑
    def wrapped(*a, **kw):
        return self.func(*a, **kw)
    return wrapped(*args, **kwargs)</code>

不过更常见的写法是把 @wraps 放在 __call__ 返回的闭包上，或者直接在 __init__ 中用 wraps 处理 self 的属性 —— 但最稳妥、最符合直觉的方式仍是：**只要你在返回一个新函数，且它替代了原函数，就对那个新函数用 @wraps(func)**。

真正容易被忽略的，是装饰器嵌套场景：比如 @retry @cache @log，每一层都必须正确使用 wraps，否则最外层拿到的就不是原始函数的 __doc__，而是中间某层包装函数的。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Python装饰器保留函数名和文档说明方法》文章吧，也可关注golang学习网公众号了解相关技术文章。