理解 Python 中的 @wraps：保留函数元数据

一. 引言

在本文中，我们将探讨 @wraps 的使用。当在 Python 中使用装饰器时，您可能会遇到原始函数的元数据丢失的情况。这时，来自 functools 模块的 @wraps 装饰器就派上用场了。接下来，我们将深入了解 @wraps 的功能以及它的重要性。

二. 简单装饰器的问题

首先，让我们看看一个没有使用 @wraps 的简单装饰器。

def my_decorator(func):
    def wrapper(*args, **kwargs):
        print("在调用函数之前发生了一些事情。")
        result = func(*args, **kwargs)  # 调用原始函数
        print("在调用函数之后发生了一些事情。")
        return result
    return wrapper

@my_decorator
def say_hello(name):
    """这个函数根据名字向某人致以问候。"""
    print(f"你好, {name}!")

# 打印函数的名称和文档字符串
print(say_hello.__name__)  # 输出函数名称
print(say_hello.__doc__)   # 输出文档字符串

运行上述代码，您将看到以下输出：

wrapper
None

问题是，原始的 say_hello 函数的名称和文档字符串被包装函数覆盖了。这可能会导致调试、反射和文档生成的问题。

三. 使用 @wraps 的解决方案

现在，让我们通过使用 @wraps 来修改我们的装饰器。

from functools import wraps  # 从 functools 模块导入 wraps

def my_decorator(func):
    @wraps(func)  # 使用 @wraps 保留原始函数的元数据
    def wrapper(*args, **kwargs):
        print("在调用函数之前发生了一些事情。")
        result = func(*args, **kwargs)  # 调用原始函数
        print("在调用函数之后发生了一些事情。")
        return result
    return wrapper

@my_decorator
def say_hello(name):
    """这个函数根据名字向某人致以问候。"""
    print(f"你好, {name}!")

# 打印函数的名称和文档字符串
print(say_hello.__name__)  # 输出函数名称
print(say_hello.__doc__)   # 输出文档字符串

现在，当您运行上述代码时，您将获得以下输出：

say_hello
这个函数根据名字向某人致以问候。

四. @wraps 的工作原理

@wraps 本身是一个装饰器，用于更新包装函数，使其看起来像被包装的函数。它通过复制原始函数的几个属性到包装函数中来实现这一点，包括：

• name（函数名）
• doc（文档字符串）
• module（模块名）
• annotations（注解）
• qualname（限定名称）

通过保留这些属性，@wraps 确保原始函数的元数据在被装饰时不会丢失。

五. 为什么使用 @wraps？

在编写装饰器时，使用 @wraps 被认为是最佳实践，原因如下：

• 它维护准确的函数元数据，这对于文档工具和 IDE 来说至关重要。
• 它通过保留原始函数的名称和文档字符串来帮助调试。
• 它允许更好的对装饰函数的反射。

六. 总结

@wraps 装饰器是 Python 中一个简单而强大的工具，它有助于在使用装饰器时维护函数元数据的完整性。通过在您的装饰器中引入 @wraps，您确保代码更具可读性、可调试性和可维护性。