68. Function Wrapping with wraps

1. Basic Usage of functools.wraps

Preserve function metadata like name and docstring when wrapping a function with a decorator.

Copy

import functools

def simple_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@simple_decorator
def example_function():
    """This is a decorated function."""
    return "Hello"

print(example_function.__name__)  # Output: example_function
print(example_function.__doc__)   # Output: This is a decorated function.

---

2. Preserving Metadata with Multiple Decorators

When using multiple decorators, functools.wraps ensures that the function’s metadata is retained.

Copy

import functools

def decorator_one(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

def decorator_two(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@decorator_one
@decorator_two
def example_function():
    """This function is wrapped with two decorators."""
    return "Hello"

print(example_function.__name__)  # Output: example_function
print(example_function.__doc__)   # Output: This function is wrapped with two decorators.

---

3. Function Signature Preservation

functools.wraps helps preserve the function's signature even after being wrapped by a decorator.

Copy

import functools

def decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@decorator
def example_function(x, y):
    """Function that adds two numbers."""
    return x + y

print(example_function.__name__)  # Output: example_function
print(example_function.__signature__)  # Output: (x, y)

---

4. Handling Arguments with functools.wraps

Use functools.wraps to ensure the function arguments are handled properly when wrapped.

Copy

import functools

def decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Function {func.__name__} called with arguments {args} and {kwargs}")
        return func(*args, **kwargs)
    return wrapper

@decorator
def example_function(x, y):
    """Adds two numbers."""
    return x + y

example_function(3, 5)

Output:

Copy

Function example_function called with arguments (3, 5) and {}

---

5. Preserving Function's Docstring

Preserve the docstring of the wrapped function using functools.wraps.

Copy

import functools

def decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@decorator
def example_function():
    """This function adds two numbers."""
    return 42

print(example_function.__doc__)  # Output: This function adds two numbers.

---

6. Preserving Function's Original Return Value

Ensure that the function’s original return value is returned properly after being wrapped.

Copy

import functools

def decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        print(f"Result of {func.__name__}: {result}")
        return result
    return wrapper

@decorator
def example_function():
    return "Hello, world!"

example_function()

Output:

Copy

Result of example_function: Hello, world!

---

7. Example with Arguments and Keyword Arguments

Ensure that both arguments and keyword arguments are passed correctly.

Copy

import functools

def decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Function {func.__name__} called with arguments {args} and keyword arguments {kwargs}")
        return func(*args, **kwargs)
    return wrapper

@decorator
def example_function(x, y, z=5):
    return x + y + z

example_function(2, 3, z=7)

Output:

Copy

Function example_function called with arguments (2, 3) and keyword arguments {'z': 7}

---

8. Debugging with functools.wraps

Use functools.wraps to retain function metadata for debugging purposes.

Copy

import functools

def decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__} with arguments: {args} and keyword arguments: {kwargs}")
        result = func(*args, **kwargs)
        print(f"Returned from {func.__name__}: {result}")
        return result
    return wrapper

@decorator
def example_function(x, y):
    return x * y

example_function(5, 3)

Output:

Copy

Calling example_function with arguments: (5, 3) and keyword arguments: {}
Returned from example_function: 15

---

9. Preserving Function Attributes

You can preserve custom attributes of the wrapped function using functools.wraps.

Copy

import functools

def decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@decorator
def example_function():
    """This function prints a message."""
    print("Hello, world!")

# Adding a custom attribute
example_function.custom_attribute = "Custom value"

print(example_function.custom_attribute)  # Output: Custom value

---

10. Dynamic Function Wrapping with functools.wraps

Dynamically wrap functions and preserve their metadata.

Copy

import functools

def dynamic_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Function {func.__name__} called with {args} and {kwargs}")
        return func(*args, **kwargs)
    return wrapper

def apply_decorator(func, decorator):
    return decorator(func)

@apply_decorator
def example_function(a, b):
    return a + b

print(example_function.__name__)  # Output: example_function

---

These examples demonstrate how functools.wraps is used to ensure that the decorated function retains its original metadata such as name, docstring, and signature. This is especially important when writing decorators, as it allows for better introspection, debugging, and clarity in the code.