Introduction
Hello everyone! Today I'd like to discuss an interesting topic in Python - parameterized decorators. You might ask, why focus specifically on this? I've noticed that many developers tend to stay at a basic level when using decorators, such as writing simple timer decorators or logging decorators. However, when it comes to making decorators more flexible to adapt to different scenarios, many people struggle.
Starting with the Basics
Let's first review how to write the most basic decorator. Suppose we want to write a timer decorator:
import time
def timer(func):
def wrapper(*args, **kwargs):
start = time.time()
result = func(*args, **kwargs)
end = time.time()
print(f"Function {func.__name__} took {end - start:.2f} seconds to run")
return result
return wrapper
@timer
def slow_function():
time.sleep(1)
print("Function executed")
slow_function()
This code demonstrates a basic timer decorator. Its main function is to record the execution time of a function by recording timestamps before and after function execution to calculate the running duration. This decorator uses Python's time module to implement timing functionality, with the wrapper function acting as a closure that captures the decorated function and adds timing logic during execution. The characteristic of this basic decorator is that its functionality is fixed and cannot be adjusted for different scenarios.
The Decorator's Dilemma
But have you encountered situations like this: sometimes we want precision to the millisecond, sometimes only to the second; sometimes we want to write execution times to a log file, sometimes we just want to print to the console. With the simple decorator above, we would need to write several different decorators, making the code very redundant.
This is where parameterized decorators come in handy. They allow us to pass parameters when using decorators, enabling more flexible functionality customization. Let's look at an improved timer decorator:
import time
import logging
from functools import wraps
def advanced_timer(precision='s', output='console', log_file='timer.log'):
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
start = time.time()
result = func(*args, **kwargs)
end = time.time()
elapsed = end - start
if precision == 'ms':
elapsed *= 1000
time_str = f"{elapsed:.2f} milliseconds"
else:
time_str = f"{elapsed:.2f} seconds"
message = f"Function {func.__name__} took {time_str} to run"
if output == 'file':
logging.basicConfig(filename=log_file, level=logging.INFO)
logging.info(message)
else:
print(message)
return result
return wrapper
return decorator
@advanced_timer(precision='ms', output='file', log_file='my_timer.log')
def complex_calculation():
time.sleep(0.5)
return sum(i * i for i in range(1000))
result = complex_calculation()
This improved timer decorator demonstrates the power of parameterized decorators. It contains three layers of nested functions: the outermost advanced_timer function receives configuration parameters, the middle decorator function receives the decorated function, and the innermost wrapper function implements the actual decoration logic. The decorator maintains the original function's metadata using functools.wraps and provides flexible timing precision and output method options based on the input parameters. This decorator can not only choose the time precision (seconds or milliseconds) but also choose to output results to the console or log file.
Principles of Parameterized Decorators
At this point, you might wonder how these parameterized decorators work. The core lies in closure mechanisms and function nesting. Let's analyze its structure:
def outer_function(outer_param): # Outermost function, receives decorator parameters
def decorator(func): # Middle layer function, receives decorated function
def wrapper(*args, **kwargs): # Innermost function, implements decoration logic
# Can use outer_param parameter here
print(f"Using parameter: {outer_param}")
return func(*args, **kwargs)
return wrapper
return decorator
@outer_function("test")
def my_function():
pass
This code shows the basic framework of a parameterized decorator. It implements parameter passing and capture through three layers of function nesting: outer_function receives the decorator's parameters, decorator receives the decorated function, and wrapper implements the actual decoration logic. This structure utilizes Python's closure mechanism, allowing inner functions to access variables from outer functions.
Practical Application: Retry Decorator
Let's look at a more practical example - a decorator that can customize retry attempts and intervals:
import time
from functools import wraps
import random
def retry(max_attempts=3, delay_seconds=1, exponential_backoff=False):
def decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
attempts = 0
while attempts < max_attempts:
try:
return func(*args, **kwargs)
except Exception as e:
attempts += 1
if attempts == max_attempts:
raise e
wait_time = delay_seconds
if exponential_backoff:
wait_time = delay_seconds * (2 ** (attempts - 1))
print(f"Attempt {attempts} failed. Retrying in {wait_time} seconds...")
time.sleep(wait_time)
return None
return wrapper
return decorator
@retry(max_attempts=5, delay_seconds=2, exponential_backoff=True)
def unstable_network_call():
if random.random() < 0.8: # 80% chance of failure
raise ConnectionError("Network is unstable")
return "Success"
try:
result = unstable_network_call()
print(f"Final result: {result}")
except ConnectionError as e:
print(f"Failed after all attempts: {e}")
The implementation of this retry decorator is very clever. Through parameterized decoration, it allows users to customize the maximum number of retries, retry interval time, and whether to use exponential backoff strategy. The decorator catches exceptions during function execution and continuously attempts to re-execute before reaching the maximum retry count. The exponential backoff strategy is a common technique when handling network requests, which can prevent problems caused by frequent retries during network congestion.
Advanced Application: Stateful Decorators
Sometimes we need decorators to maintain some state, such as recording the number of times a function has been called. In this case, we can combine class decorators with parameterized decorators:
class CallCounter:
def __init__(self, threshold=None, callback=None):
self.threshold = threshold
self.callback = callback
self.count = 0
def __call__(self, func):
@wraps(func)
def wrapper(*args, **kwargs):
self.count += 1
if self.threshold and self.count >= self.threshold:
if self.callback:
self.callback(func.__name__, self.count)
print(f"Function {func.__name__} has been called {self.count} times")
return func(*args, **kwargs)
return wrapper
def alert_admin(func_name, count):
print(f"Alert: Function {func_name} has been called {count} times!")
@CallCounter(threshold=3, callback=alert_admin)
def frequently_called_function():
print("Function executed")
for _ in range(5):
frequently_called_function()
This example shows how to create a stateful parameterized decorator. It implements the decorator using a class, maintains state information through instance attributes, and can set thresholds and callback functions. When the function call count reaches the threshold, it triggers the callback function to perform corresponding operations. This implementation is particularly suitable for scenarios that need to track and respond to function call patterns.
Important Considerations
After discussing all these benefits, we should also note some potential issues with parameterized decorators:
First is the performance issue. Due to the nature of multiple function nesting, parameterized decorators will bring some performance overhead. In scenarios with particularly high performance requirements, this needs to be weighed carefully.
Second is the readability issue. Excessive use of parameterized decorators can make code difficult to understand. I suggest maintaining moderation when using them and adding clear documentation.
Finally, there's the debugging issue. Multiple nested function call chains can make debugging complex. This is where Python's functools.wraps decorator becomes particularly important, as it can maintain the original function's metadata and aid in debugging.
Practical Recommendations
At this point, I'd like to offer several usage suggestions:
First, when designing parameterized decorators, fully consider default values for parameters. This allows using default configurations in simple scenarios and passing parameters only when special customization is needed.
Second, try to maintain single responsibility for decorators. If you find a decorator handling too many different things, consider splitting it into multiple smaller decorators.
Third, remember to use functools.wraps to maintain function metadata. This helps not only with debugging but also with code maintainability.
Summary and Outlook
Parameterized decorators are a very powerful feature in Python, allowing us to write more flexible and reusable code. Through this article's study, you should have mastered the basic principles and implementation methods of parameterized decorators.
However, this is just the beginning, as there are many interesting application scenarios for decorators waiting to be explored. For instance, have you thought about how to implement function caching mechanisms using decorators? Or how to implement simple dependency injection using decorators?
These are all very interesting topics, and if you're interested, we can continue the discussion in the comments section. How do you use decorators in your daily work? What interesting application scenarios have you encountered? Feel free to share your experiences.
Previous 
