Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~4 min readPython
#decorators#closures#functools#function-wrapping
Three nested layers of a Python parameterized decorator wrapping a function, with configuration arguments flowing through each layer.

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:

python
def log_calls(func): def wrapper(*args, **kwargs): print(f"Calling {func.__name__}") return func(*args, **kwargs) return wrapper

When 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:

python
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 decorator

retry 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:

python
@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:

  1. Calls retry(attempts=5), which returns the decorator function.
  2. Calls decorator(fetch_data), which returns wrapper.
  3. Binds the name fetch_data to wrapper.

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:

python
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 decorator

The @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:

python
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 wrapper

The 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 tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.