Python Parameterized Decorator: Syntax and Usage
Learn how to write a Python parameterized decorator using the three-layer nesting pattern, preserve metadata with functools.wraps, avoid common mistakes, and decide when a class-based implementation is useful.

A Python parameterized decorator — a decorator that accepts its own arguments, such as @retry(attempts=3) — requires one more nesting level than a plain decorator. The difference is easy to miss at first: a plain decorator receives a function and returns a function, while a parameterized decorator receives the configuration arguments first, then returns a decorator that receives the function.
Why a Parameterized Decorator Needs Three Layers
A plain decorator is a single callable that takes a function and returns a replacement:
def log_calls(func):
def wrapper(*args, **kwargs):
print(f"Calling {func.__name__}")
return func(*args, **kwargs)
return wrapperWhen you write @log_calls, Python calls log_calls with the function below it and replaces that function with the returned wrapper.
A parameterized decorator changes the contract. When you write @retry(attempts=3), Python evaluates retry(attempts=3) first. That call must return a decorator — a callable that accepts the function. That returned decorator then receives the function and returns the replacement. The extra layer exists because the configuration arguments must be captured before the function is even known.
Building a Minimal Parameterized Decorator
The canonical structure is three nested functions:
def retry(attempts=3):
def decorator(func):
def wrapper(*args, **kwargs):
for i in range(attempts):
try:
return func(*args, **kwargs)
except Exception:
if i == attempts - 1:
raise
return None
return wrapper
return decoratorretry is the outermost function. It receives the configuration value attempts and returns decorator. The decorator function receives the original function and returns wrapper. The wrapper function receives the actual call arguments and contains the retry logic.
Usage looks identical to a plain decorator from the caller's perspective:
@retry(attempts=5)
def fetch_data():
...The closure over attempts is what makes this work. wrapper can reference attempts because it is defined inside retry's scope, even though retry has already returned by the time wrapper runs.
How the Layers Interact at Call Time
The evaluation order matters. When Python sees @retry(attempts=5), it:
- Calls
retry(attempts=5), which returns thedecoratorfunction. - Calls
decorator(fetch_data), which returnswrapper. - Binds the name
fetch_datatowrapper.
Every subsequent call to fetch_data() invokes wrapper, which calls the original fetch_data through the closure. The original function is never lost — wrapper captures func from the enclosing call to decorator.
This evaluation order explains a common source of confusion: the outer function runs at decoration time, not at call time. If you put expensive setup logic in retry itself, it runs once when the module is imported. Logic that must run on every invocation belongs in wrapper.
Preserving Metadata with functools.wraps
Without intervention, wrapper replaces the original function's name and docstring. Tools that inspect function metadata — such as documentation generators, debuggers, and web frameworks that derive route names from function names — will see wrapper instead of fetch_data.
Applying functools.wraps copies __name__, __doc__, __module__, and other attributes from the original function to the wrapper:
import functools
def retry(attempts=3):
def decorator(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
for i in range(attempts):
try:
return func(*args, **kwargs)
except Exception:
if i == attempts - 1:
raise
return None
return wrapper
return decoratorThe @functools.wraps(func) line sits directly above wrapper inside decorator. This is the same placement as in a plain decorator; the parameterized structure does not change where wraps goes.
Common Mistakes with Parameterized Decorators
A common error is forgetting the middle layer. Writing a single function that tries to handle both @retry and @retry(attempts=3) with default arguments and branching can lead to subtle failure modes. The three-layer structure is simpler to reason about and should be the default.
A second mistake is using a mutable default argument for configuration. If the decorator stores configuration in a mutable default such as a list or dictionary, that value is shared across every function the decorator wraps. Configuration values should be treated as immutable after decoration.
A third mistake is swallowing exceptions too broadly. The retry example above catches Exception, which includes programming errors like TypeError and AttributeError. Retrying those usually makes the problem worse. Catching a specific exception type, such as a timeout exception from an HTTP client library, is usually the right call.
Using a Class Instead of Nested Functions
A class with __call__ can replace the outer function and the decorator layer:
import functools
class retry:
def __init__(self, attempts=3):
self.attempts = attempts
def __call__(self, func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
for i in range(self.attempts):
try:
return func(*args, **kwargs)
except Exception:
if i == self.attempts - 1:
raise
return None
return wrapperThe class approach keeps configuration state in instance attributes and can be easier to extend — for example, by adding helper methods for delay or logging behavior instead of nesting more functions. The tradeoff is that the control flow is less explicit than the nested-function version, and some developers find the function-based form easier to read.
When Parameterized Decorators Become Hard to Maintain
Three nested layers are manageable, but adding more configuration parameters increases cognitive load. If a decorator needs more than a few options, consider moving the logic into a helper class and keeping the decorator as a thin adapter. The decorator's job is to capture configuration and wrap the function; the actual behavior belongs in a separate, testable unit.
Parameterized decorators also interact with type checking. Static type checkers such as mypy can struggle to infer the wrapped function's original signature from nested closures. functools.wraps updates runtime metadata, but it does not by itself change what the type checker infers. For fully typed code, a common solution is to use typing.ParamSpec with explicit Callable annotations; the exact pattern depends on your type checker and Python version.
A parameterized decorator is ultimately a factory that produces a decorator. Keeping that relationship explicit — three layers, each with one responsibility — makes the pattern predictable and easy to debug when a wrapped function misbehaves.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.