Python functools.update_wrapper 怎样保留装饰器元数据

写装饰器时，最容易被忽略的不是调用逻辑，而是包装器把原函数的身份信息遮住了。直接返回内部 wrapper 后，调试器、文档工具和日志可能只能看到包装器自己的名称与说明。解决这个问题的标准做法是：通用场景使用 functools.wraps，需要精细控制字段时直接调用 functools.update_wrapper。

官方文档：https://docs.python.org/3/library/functools.html#functools.update_wrapper

记住三层关系：update_wrapper 负责把元数据同步到包装器，wraps 是更适合装饰器语法的便捷写法，__wrapped__ 则让检查工具有机会回到原函数。它们不会改变包装器的实际调用逻辑，也不会自动解决参数校验或线程安全问题。

为什么普通装饰器会把函数信息变成 wrapper

我在给一组函数加日志时遇到过这个现象：调用结果完全正常，但帮助页面显示的函数名统一成了 wrapper，自动生成的文档也丢了原来的说明。原因很直接，装饰器返回的是新函数，Python 默认不会把被包装函数的元数据全部复制过去。

from functools import update_wrapper

def trace_call(func):
    def wrapper(*args, **kwargs):
        # 包装器只负责记录调用，再把参数交给原函数
        print(f"calling {func.__name__}")
        return func(*args, **kwargs)

    # 不调用 update_wrapper 时，外部看到的函数名通常是 wrapper
    return wrapper

@trace_call
def load_profile(user_id: int) -> dict:
    """读取用户资料。"""
    # 示例只表达装饰器关系，不代表真实数据库查询
    return {"id": user_id}

这里的 load_profile 变量确实指向包装器。包装器仍然可以调用原函数，但它自己的 __name__、__doc__ 和注解信息来自内部定义，而不是来自 load_profile 的原始定义。这个差异会影响调试、文档生成、测试报告以及依赖函数元数据的工具。

update_wrapper 会复制哪些信息

functools.update_wrapper(wrapper, wrapped) 的第一个参数是要被更新的包装器，第二个参数是原函数。默认情况下，它会把模块名、名称、限定名称、注解、类型参数和文档字符串等字段赋给包装器，同时更新包装器的 __dict__，并设置指向原函数的 __wrapped__ 属性。

from functools import update_wrapper

def trace_call(func):
    def wrapper(*args, **kwargs):
        # 保留日志逻辑，真正的业务调用仍由 func 完成
        print(f"calling {func.__name__}")
        return func(*args, **kwargs)

    # 把原函数的公开元数据同步到 wrapper，并建立 __wrapped__ 链接
    update_wrapper(wrapper, func)
    return wrapper

@trace_call
def load_profile(user_id: int) -> dict:
    """读取用户资料。"""
    # 这里返回普通字典，重点是观察装饰器元数据
    return {"id": user_id}

调用 update_wrapper 只负责元数据处理，不会把 func 的代码体复制到 wrapper 中。包装器仍然可以增加日志、计时、权限判断或异常处理；复制的是让外部工具“认识它”的那部分信息。

为什么日常装饰器更适合用 wraps

如果只是给内部包装器套上原函数的元数据，wraps 更简洁。它是一个装饰器工厂，本质上预先固定了 update_wrapper 的 wrapped 参数。使用时把 @wraps(func) 放在内部 wrapper 上即可。

from functools import wraps

def trace_call(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        # wraps 不改变调用参数，日志和业务调用仍由这里编排
        print(f"calling {func.__name__}")
        return func(*args, **kwargs)

    return wrapper

@trace_call
def load_profile(user_id: int) -> dict:
    """读取用户资料。"""
    # 返回值保持原函数的约定，元数据由 wraps 负责保留
    return {"id": user_id}

对普通装饰器来说，wraps 是更不容易漏写的默认选择。只有当你需要改变复制字段、给包装器补充自己的元数据，或者要把一个可调用对象包装成函数风格时，才值得显式调用 update_wrapper。

自定义属性要分清 assigned 和 updated

两个可选参数决定复制策略。assigned 中的字段会直接从原对象赋给包装器；updated 中的字段会用原对象的对应映射更新包装器。默认的 assigned 包含名称、限定名称、注解、文档字符串和类型参数，默认的 updated 包含 __dict__。

from functools import update_wrapper

def mark_and_wrap(func):
    def wrapper(*args, **kwargs):
        # 包装器自己的状态可以先写入 __dict__
        wrapper.audit_enabled = True
        return func(*args, **kwargs)

    # 只同步名称和文档，避免把原函数的所有自定义属性合并进来
    update_wrapper(wrapper, func, assigned=("__name__", "__doc__"), updated=())
    return wrapper

@mark_and_wrap
def calculate_total(items: list[int]) -> int:
    """计算列表总和。"""
    # 示例函数不包含外部副作用
    return sum(items)

如果包装器没有可更新的映射属性，而 updated 仍要求更新它，可能会得到 AttributeError。另一方面，原对象缺少 assigned 中的某个字段时，标准库会忽略这个缺失字段。配置这些参数前，先明确“哪些信息属于公共身份，哪些信息属于包装器自身状态”。

__wrapped__ 和 inspect.unwrap 适合做什么

update_wrapper 会给包装器设置 __wrapped__，这让检查工具能够沿着多层装饰器追溯原函数。例如一个函数同时经过缓存、计时和权限装饰时，直接访问外层对象只能看到最后一层；inspect.unwrap 可以沿链条找到最内层对象。

import inspect
from functools import wraps

def add_tag(tag: str):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            # 每一层只增加自己的行为，再转发原调用
            return func(*args, **kwargs)

        # 用包装器自己的字典保存本层标签，不影响函数签名说明
        wrapper.decorator_tag = tag
        return wrapper

    return decorator

@add_tag("audit")
@add_tag("timing")
def export_report() -> str:
    """导出报表。"""
    # 原函数保持最小实现，重点观察解包链
    return "report"

# unwrap 会沿 __wrapped__ 逐层回到原函数
original = inspect.unwrap(export_report)
print(original.__name__)

这里的解包只用于检查、签名分析或文档处理，不等于绕过业务控制。真正调用 export_report 时，外层包装逻辑仍然存在；只有显式调用 inspect.unwrap 得到的对象才是原函数。如果手动构造了循环的 __wrapped__ 链，inspect.unwrap 会抛出 ValueError，所以不要随意改写这个属性。

我会怎样选择写法

发布前的装饰器检查清单

1. 确认外部看到的 __name__ 和 __doc__ 是否仍指向原函数语义。
2. 如果工具依赖注解或签名，确认默认复制字段是否满足需求，不要只看调用结果。
3. 多层包装时统一使用 wraps 或显式维护 __wrapped__，避免链条中间断开。
4. 包装器需要自己的属性时，审慎决定是否更新 __dict__。
5. 把 inspect.unwrap 当作检查工具，不要把它误解成跳过鉴权、日志或业务校验的开关。

相关问题

不使用 wraps 会影响函数调用吗？

通常不会直接改变调用结果，但会让包装器暴露自己的名称、说明和部分元数据，进而影响调试、文档和依赖反射的工具。

update_wrapper 会复制函数代码吗？

不会。它更新的是包装器的元数据和属性，并建立 __wrapped__ 引用；实际执行仍由包装器中的调用逻辑决定。

什么时候应该显式传 assigned 和 updated？

当包装器有不能被覆盖的状态，或你只希望公开少量身份字段时，可以显式传入元组，减少不必要的属性同步。

inspect.unwrap 一定能找到原函数吗？

前提是各层包装器正确维护了 __wrapped__。如果链条断开，它只能返回当前能到达的对象；如果链条形成循环，则会报告解包错误。

把装饰器元数据当成接口的一部分来维护，通常比事后修正文档和调试输出更省事：默认场景用 wraps，需要边界控制时用 update_wrapper，需要检查多层关系时用 inspect.unwrap。