Python函数如何用 functools.wraps 保留函数元信息 Python函数装饰器元信息保护的方法-Python教程-PHP中文网

要解决装饰器“吞噬”原始函数元信息的问题，必须使用functools.wraps装饰器，它能将原始函数的__name__、__doc__、__module__等属性复制到包装函数上，并保留__wrapped__属性指向原函数，从而确保被装饰函数在调试、文档生成、ide提示、测试发现等场景中仍表现得像原始函数一样，避免元数据丢失带来的各种问题，最终实现装饰器的透明性，完整保留函数的身份和元信息。

Python函数如何用 functools.wraps 保留函数元信息 Python函数装饰器元信息保护的方法

在Python中，当你使用装饰器（decorator）来修改或增强一个函数时，原始函数的一些重要元信息，比如它的名字（

__name__

登录后复制

）、文档字符串（

__doc__

登录后复制

）、模块（

__module__

登录后复制

）等，往往会被装饰器内部的“包装”函数（wrapper function）所覆盖。为了避免这种元信息丢失，并确保被装饰的函数在调试、内省或文档生成时依然能正确地显示其原始身份，你需要使用标准库

functools

登录后复制

中的

wraps

登录后复制

装饰器。它能将原始函数的元信息自动复制到包装函数上，让一切看起来都像是原始函数本身。

解决方案

要解决装饰器“吞噬”原始函数元信息的问题，核心在于在你的自定义装饰器内部，将

functools.wraps

登录后复制

应用到你用来包装原始函数的那个内部函数（通常是

wrapper

登录后复制

或

inner

登录后复制

）上。

这里是一个直观的对比：

立即学习“Python免费学习笔记（深入）”；

1. 没有使用

functools.wraps

登录后复制

的情况：

def my_simple_decorator(func):
    def wrapper(*args, **kwargs):
        """这是一个包装函数的文档字符串。"""
        print(f"Calling {func.__name__}...")
        result = func(*args, **kwargs)
        print(f"{func.__name__} finished.")
        return result
    return wrapper

@my_simple_decorator
def greet(name):
    """向指定的人打招呼。"""
    return f"Hello, {name}!"

print(f"函数名（不使用wraps）：{greet.__name__}")
print(f"文档字符串（不使用wraps）：{greet.__doc__}")
print(f"模块（不使用wraps）：{greet.__module__}")
# 调用函数，功能正常
print(greet("Alice"))

# 预期输出会是 wrapper 的信息，而不是 greet 的
# 函数名（不使用wraps）：wrapper
# 文档字符串（不使用wraps）：这是一个包装函数的文档字符串。
# 模块（不使用wraps）：__main__

登录后复制

你会发现

greet

登录后复制

函数的

__name__

登录后复制

变成了

wrapper

登录后复制

，

__doc__

登录后复制

也变成了

wrapper

登录后复制

的文档字符串。这在调试时可能会让人困惑，因为堆栈跟踪会显示

wrapper

登录后复制

而不是

greet

登录后复制

。

2. 使用

functools.wraps

登录后复制

的情况：

import functools

def my_decorator_with_wraps(func):
    @functools.wraps(func) # 关键在这里！
    def wrapper(*args, **kwargs):
        """这是一个包装函数的文档字符串，但会被原始函数的覆盖。"""
        print(f"Calling {func.__name__}...")
        result = func(*args, **kwargs)
        print(f"{func.__name__} finished.")
        return result
    return wrapper

@my_decorator_with_wraps
def say_hello(name):
    """这是一个原始函数的文档字符串，用于问候。"""
    return f"Hello there, {name}!"

print(f"函数名（使用wraps）：{say_hello.__name__}")
print(f"文档字符串（使用wraps）：{say_hello.__doc__}")
print(f"模块（使用wraps）：{say_hello.__module__}")
print(f"原始函数（使用wraps）：{say_hello.__wrapped__.__name__}") # functools.wraps 还会添加 __wrapped__ 属性
# 调用函数，功能正常
print(say_hello("Bob"))

# 预期输出会是 say_hello 的信息
# 函数名（使用wraps）：say_hello
# 文档字符串（使用wraps）：这是一个原始函数的文档字符串，用于问候。
# 模块（使用wraps）：__main__
# 原始函数（使用wraps）：say_hello

登录后复制

通过在

wrapper

登录后复制

函数上应用

@functools.wraps(func)

登录后复制

，

say_hello

登录后复制

函数现在正确地保留了它原始的名称、文档字符串和模块信息。此外，

wraps

登录后复制

还会添加一个

__wrapped__

登录后复制

属性，指向被包装的原始函数，这对于多层装饰器链或更深度的内省非常有用。

为什么装饰器会“吞噬”原始函数的元信息？

这其实是Python函数和作用域机制的一个自然结果，并非什么“bug”。当你定义一个装饰器时，它的本质是一个接受函数A作为参数，然后返回一个新函数B的函数。这个新函数B（也就是我们常说的

wrapper

登录后复制

函数）才是最终被赋值给原始函数名（比如

greet

登录后复制

或

say_hello

登录后复制

）的对象。

Python中的每个函数对象都有它自己的属性，比如

__name__

登录后复制

（函数名）、

__doc__

登录后复制

（文档字符串）、

__module__

登录后复制

（所在模块）等等。当你不使用

functools.wraps

登录后复制

时，你实际上是将

wrapper

登录后复制

函数的这些固有属性暴露给了外部世界。换句话说，

greet = my_simple_decorator(greet)

登录后复制

这行代码，并不是修改了原始的

greet

登录后复制

函数，而是让

greet

登录后复制

这个变量名现在指向了

my_simple_decorator

登录后复制

返回的那个

wrapper

登录后复制

函数。那么，自然而然地，当你查询

greet.__name__

登录后复制

时，你得到的就是

wrapper

登录后复制

的名字，而不是你期望的

greet

登录后复制

。

从某种角度看，这就像你把一本书（原始函数）放进了一个漂亮的包装盒（

wrapper

登录后复制

函数），然后把这个包装盒递给了别人。别人看到的当然是包装盒的描述，而不是里面书的描述。虽然包装盒里确实装着那本书，但它的外部特征已经变了。

functools.wraps

登录后复制

的作用，就是把书的封面信息复制一份贴到包装盒外面，让别人一眼就能知道里面是什么书。

functools.wraps

登录后复制

的实现原理与核心作用是什么？

functools.wraps

登录后复制

本身也是一个装饰器，但它比较特殊，它接受一个参数：被包装的原始函数

func

登录后复制

。它的内部机制，主要是通过调用

functools.update_wrapper

登录后复制

函数来完成的。

微信 WeLM

WeLM不是一个直接的对话机器人，而是一个补全用户输入信息的生成模型。

查看详情

update_wrapper

登录后复制

函数的核心工作就是：

复制属性： 它会将被包装函数（
```
func
```
登录后复制
）的特定属性（默认包括
```
__module__
```
登录后复制
,
```
__name__
```
登录后复制
,
```
__qualname__
```
登录后复制
,
```
__doc__
```
登录后复制
,
```
__annotations__
```
登录后复制
）复制到包装函数（
```
wrapper
```
登录后复制
）上。这意味着，当你查询被装饰后的函数（比如
```
say_hello
```
登录后复制
）的
```
__name__
```
登录后复制
或
```
__doc__
```
登录后复制
时，你得到的就是原始
```
say_hello
```
登录后复制
函数的这些信息，而不是
```
wrapper
```
登录后复制
的。
设置
__wrapped__
登录后复制
属性：
```
update_wrapper
```
登录后复制
还会给
```
wrapper
```
登录后复制
函数添加一个
```
__wrapped__
```
登录后复制
属性，这个属性指向被它包装的原始函数
```
func
```
登录后复制
。这个特性非常有用，尤其是在处理多层装饰器链时。你可以通过
```
func.__wrapped__
```
登录后复制
来访问到原始的、未被装饰的函数对象，或者逐层剥离装饰器，这对于调试、内省以及一些高级功能（比如框架在运行时检查原始函数签名）至关重要。

所以，

functools.wraps

登录后复制

的核心作用，就是让装饰器对外部表现得“透明”。它确保了经过装饰器处理的函数，在行为上虽然增强了，但在其元数据层面，依然保持着原始函数的“身份”。这极大地提高了代码的可读性、可维护性和调试效率。没有它，很多依赖函数元信息的工具（如文档生成器、测试框架、IDE的自动补全等）都会失效。

除了

functools.wraps

登录后复制

，还有哪些场景需要关注函数元信息？

函数元信息的重要性远不止于解决装饰器的问题，它在Python生态系统的多个层面都扮演着关键角色。

调试和错误追踪： 当程序出现异常时，堆栈跟踪会显示函数名。如果函数名被
```
wrapper
```
登录后复制
覆盖，那么在复杂系统中，你很难一眼看出是哪个业务逻辑函数出了问题。
```
wraps
```
登录后复制
能确保堆栈跟踪显示正确的函数名，大大提升调试效率。我的经验是，没有
```
wraps
```
登录后复制
的装饰器，调试起来简直是噩梦。
自动化文档生成： 像Sphinx这样的文档生成工具，会大量依赖函数的
```
__doc__
```
登录后复制
属性来提取文档。如果
```
__doc__
```
登录后复制
被
```
wrapper
```
登录后复制
的文档字符串覆盖，那么生成的文档就会不准确或缺失关键信息。同样，函数的
```
__name__
```
登录后复制
和
```
__module__
```
登录后复制
对于构建清晰的模块和函数索引也至关重要。
IDE和静态分析工具： 现代集成开发环境（IDE），比如PyCharm或VS Code，以及像MyPy这样的静态类型检查工具，都会利用函数的元信息来提供代码补全、参数提示、类型检查和重构等功能。如果
```
__name__
```
登录后复制
或
```
__annotations__
```
登录后复制
（类型提示）丢失，这些智能辅助功能就会大打折扣，甚至误导开发者。
Web框架和路由： 许多Python Web框架（如Flask、Django、FastAPI）广泛使用装饰器来定义路由、视图函数或权限控制。它们常常需要内省这些被装饰的函数，例如，Flask可能会根据函数名生成URL，或者根据函数签名来自动处理请求参数。如果元信息丢失，这些框架的魔力就会消失。
测试框架： Pytest等测试框架在发现测试函数时，通常会查找以
```
test_
```
登录后复制
开头的函数名。如果你的测试函数被装饰器改变了
```
__name__
```
登录后复制
，那么测试框架可能就无法正确地发现并执行它们。
序列化和反序列化： 在某些高级场景中，你可能需要序列化函数引用，并在之后反序列化它们。函数的
```
__module__
```
登录后复制
和
```
__qualname__
```
登录后复制
（合格名称）对于在运行时重新定位和加载这些函数至关重要。
函数签名检查和适配： 比如，一些RPC框架或者插件系统，可能需要动态地检查函数的签名（参数列表、返回值类型）来确保兼容性。
```
inspect
```
登录后复制
模块可以帮助你获取这些信息，但如果元信息不正确，这些检查就会失败。
```
functools.wraps
```
登录后复制
确保
```
inspect.signature()
```
登录后复制
也能正确地获取到原始函数的签名。