Metadata preservation

Ensures decorated functions retain their original metadata for proper introspection and documentation.

Python decorators: preserving function metadata when wrapping a function with another function; Framework middleware: copying __name__ and __doc__ from original handler to wrapper for logging and debugging

Python standard library, web frameworks (Flask, Django), library development, any code using decorators

functools.update_wrapper(wrapper, func)

functools.update_wrapper(..., ...)

wrapper: callable object to be updated, func: callable object serving as source

• functools.wraps (common alternative)
• decorator syntax
• inner wrapper functions

• functools.wraps(wrapper) — simpler
• preserves more attributes automatically
• manual attribute copying — flexible but error-prone
• using __wrapped__ — exposes original function but less common

Swapping argument order (update_wrapper(func, wrapper)) — cause: misunderstanding parameter order — consequence: wrapper loses its own attributes and fails to copy source metadata; Omitting the func argument — cause: forgetting to pass source function — consequence: AttributeError when accessing copied attributes; Applying update_wrapper to a class instead of a function — cause: treating class as callable — consequence: TypeError or missing attribute copying; Not returning the wrapper from a decorator — cause: overlooking return statement — consequence: decorator returns None, breaking the decorated function; Using update_wrapper inside a nested decorator without preserving __wrapped__ — cause: chaining wrappers incorrectly — consequence: lost original function reference in introspection tools.

functools.wraps — decorator-friendly wrapper that calls update_wrapper internally; manual attribute copying — direct assignment of __module__, __name__, __doc__ without helper; __wrapped__ attribute — exposes original function but does not copy metadata

Coming from Java: may expect method metadata to be preserved automatically → Python's update_wrapper must be called explicitly to copy __module__, __name__, __doc__

• functools.wraps
• decorator pattern
• __wrapped__ attribute

When NOT to use: if you do not need to preserve function metadata (e.g., internal helper decorators where introspection is irrelevant); Performance/resource implications: negligible overhead, microsecond-level cost per call; Boundary conditions: only works on callable objects; missing attributes in the source are not set; chaining wrappers may accumulate __wrapped__ links.

Using update_wrapper correctly ensures decorated functions retain correct metadata, enabling reliable introspection, documentation, debugging, and compatibility with tools that rely on __name__, __doc__, __module__, and __annotations__.

Like a photocopier that preserves all the original document's stamps and signatures when making a copy.

Returns the wrapper object, allowing chaining; available since Python 2.5; in Python 3.4+ also copies __annotations__ by default.