Decorators

Decorators in Python provide a powerful and elegant way to extend or modify the behavior of functions or methods without permanently altering their source code. They are essentially higher-order functions that take another function as an argument, add some functionality to it, and return a new function (or a modified version of the original). This concept aligns with the 'Don't Repeat Yourself' (DRY) principle, promoting code reusability and maintainability.

How Decorators Work:
At their core, decorators leverage Python's ability to define functions inside other functions (closures) and pass functions as arguments. The process typically involves:
1. A Decorator Function: This function takes another function (the 'decorated' function) as its argument.
2. A Nested Wrapper Function: Inside the decorator, a new function, often called `wrapper` or `inner`, is defined. This `wrapper` function is where the additional logic (before, after, or around the original function's execution) is implemented.
3. Calling the Original Function: The `wrapper` function typically calls the original decorated function, usually passing along its arguments (`-args`, `kwargs`) to ensure full functionality.
4. Returning the Wrapper: The decorator function returns this `wrapper` function. When you call the decorated function, you are actually calling this `wrapper`.

The `@` Syntax:
Python provides syntactic sugar with the `@decorator_name` syntax. Placing `@decorator_name` directly above a function definition is equivalent to:
`my_function = decorator_name(my_function)`

Common Use Cases:
- Logging: Automatically log function calls, arguments, and return values.
- Timing: Measure the execution time of functions.
- Authentication/Authorization: Check user permissions or roles before allowing a function to execute.
- Caching: Store results of expensive function calls to avoid recomputation on subsequent calls with the same arguments.
- Input Validation: Validate function arguments before the main logic runs.
- Retries: Automatically retry a function call a certain number of times if it fails.

`functools.wraps`:
When creating decorators, it is best practice to use `@functools.wraps(func)` on the `wrapper` function. This decorator from the `functools` module helps preserve the original function's metadata (like `__name__`, `__doc__`, `__module__`, `__annotations__`). Without `wraps`, introspection on a decorated function would incorrectly show the metadata of the `wrapper` function instead of the original function.

import time
import functools

 Define a simple decorator for timing function execution
def timer(func):
     @functools.wraps(func) preserves the original function's metadata
    @functools.wraps(func)
    def wrapper(-args, kwargs):
        start_time = time.perf_counter()   Record start time
        result = func(-args, kwargs)    Call the original function
        end_time = time.perf_counter()     Record end time
        run_time = end_time - start_time
        print(f"Executing {func.__name__!r}. Elapsed time: {run_time:.4f} seconds")
        return result
    return wrapper

 Apply the timer decorator to a function using the '@' syntax
@timer
def calculate_power(base, exponent):
    """Calculates base raised to the power of exponent."""
    time.sleep(0.5)  Simulate a time-consuming operation
    return base  exponent

@timer
def greet(name):
    """Greets the given name."""
    time.sleep(0.2)  Simulate another operation
    return f"Hello, {name}!"

 Call the decorated functions
print(f"Result 1: {calculate_power(2, 10)}")
print(f"Result 2: {greet('Alice')}")

 Demonstrate accessing metadata (preserved thanks to @functools.wraps)
print(f"\nName of calculate_power: {calculate_power.__name__}")
print(f"Docstring of calculate_power: {calculate_power.__doc__}")

 Example of manual decoration (without '@' syntax) for understanding
def manual_decorated_function():
    """This function will be decorated manually."""
    print("Inside manual_decorated_function.")

print("\n--- Manual Decoration Example ---")
 Manually apply the decorator
decorated_manual_function = timer(manual_decorated_function)
decorated_manual_function()
print(f"Name of decorated_manual_function: {decorated_manual_function.__name__}")