Principles and Applications of Decorators in Python

Problem Description
Decorators are a high-level syntactic feature in Python that allow adding extra functionality (such as logging, permission checking, performance monitoring, etc.) to functions or classes without modifying their original code. Please explain how decorators work and provide examples of their specific application scenarios.

1. Basic Concepts of Decorators

The essence of a decorator is a higher-order function that takes a function as an argument and returns a new function (or callable object). Its core idea is that functions are first-class objects, meaning they can be assigned, passed around, or returned as values.

Key Points:

• Functions can be nested in Python (closures), allowing inner functions to access variables from outer functions.
• The @decorator_name syntactic sugar is used to apply decorators to target functions.

2. Implementation Steps of Decorators

Step 1: Define a Simple Decorator

The following is an example of a decorator that measures function execution time:

import time

def timer_decorator(func):  # Takes the original function as an argument
    def wrapper(*args, **kwargs):  # Inner function supporting arbitrary arguments
        start_time = time.time()
        result = func(*args, **kwargs)  # Call the original function
        end_time = time.time()
        print(f"{func.__name__} execution time: {end_time - start_time:.2f} seconds")
        return result  # Return the result of the original function
    return wrapper  # Return the new function

# Using the decorator
@timer_decorator
def example_function(n):
    time.sleep(n)
    return "Done"

# Calling the function
example_function(2)

Execution Result:

example_function execution time: 2.00 seconds

Step 2: Understanding the Role of Decorator Syntactic Sugar

@timer_decorator is equivalent to the following code:

def example_function(n):
    time.sleep(n)
    return "Done"

example_function = timer_decorator(example_function)  # Manually replace the original function

3. Advanced Usage of Decorators

(1) Decorators with Parameters

If the decorator itself requires parameters (e.g., setting log levels), an additional layer of nesting is needed:

def repeat(n):  # Outer function takes decorator parameters
    def decorator(func):  # Middle layer takes the decorated function
        def wrapper(*args, **kwargs):
            for i in range(n):
                result = func(*args, **kwargs)
                print(f"Execution {i+1} result: {result}")
            return result
        return wrapper
    return decorator

@repeat(3)  # Execute 3 times
def greet(name):
    return f"Hello, {name}"

greet("Alice")

Output:

Execution 1 result: Hello, Alice  
Execution 2 result: Hello, Alice  
Execution 3 result: Hello, Alice  

(2) Preserving Original Function Metadata

Decorators override the __name__, __doc__, and other attributes of the original function. Use functools.wraps to preserve them:

from functools import wraps

def timer_decorator(func):
    @wraps(func)  # Preserve original function metadata
    def wrapper(*args, **kwargs):
        # ... same as above
        return result
    return wrapper

(3) Class Decorators

By implementing the __call__ method, a class can also act as a decorator:

class CountCalls:
    def __init__(self, func):
        self.func = func
        self.call_count = 0

    def __call__(self, *args, **kwargs):
        self.call_count += 1
        print(f"Function has been called {self.call_count} times")
        return self.func(*args, **kwargs)

@CountCalls
def say_hello():
    print("Hello!")

say_hello()  # Output: Function has been called 1 time  
say_hello()  # Output: Function has been called 2 times  

4. Application Scenarios of Decorators

1. Logging: Automatically record function call parameters and return values.
2. Permission Checking: Verify user permissions before executing a function (e.g., @login_required in web frameworks).
3. Caching: Cache function results to avoid repeated calculations (e.g., functools.lru_cache).
4. Performance Testing: Measure function execution time (e.g., the timer_decorator example).

5. Summary

• Decorators are implemented based on closures and functional programming, making them a metaprogramming feature in Python.
• The @ syntactic sugar simplifies usage, but the essence is function replacement.
• Pay attention to the execution order when nesting decorators (from bottom to top).
• In practice, use functools.wraps to preserve original function metadata.