Advanced Python Decorator Techniques: Classes, Stacking, and Production Best Practices

Most decorator tutorials teach you the wrong mental model

Here’s the hot take: class-based decorators are underused, and the Python community’s obsession with closure-based patterns has led to an entire generation of developers writing fragile, hard-to-test decoration logic. The __call__ method on a class gives you state, inheritance, and composability that nested functions simply can’t match — and yet most “advanced” decorator guides barely mention them before pivoting back to functools.wraps.

I’ll defend that claim with code. But first, let me acknowledge what we’ve built up to. In Part 1, we covered how @syntax is just sugar for passing functions around. Part 2 showed how to write decorators that handle arguments and return values cleanly. Now we’re going to break things on purpose, then fix them with patterns that actually hold up in production.

Class-based decorators and why they matter

A decorator doesn’t have to be a function. It just has to be callable. That means any object with a __call__ method works, and this opens up a design space that closures can’t reach.

import time
import functools

class retry:
    """Retry a function on exception with exponential backoff."""

    def __init__(self, max_attempts=3, backoff_factor=2.0, exceptions=(Exception,)):
        self.max_attempts = max_attempts
        self.backoff_factor = backoff_factor
        self.exceptions = exceptions
        self._call_count = 0  # observable state — try doing this cleanly with closures

    def __call__(self, func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            delay = 1.0
            last_exception = None
            for attempt in range(1, self.max_attempts + 1):
                try:
                    self._call_count += 1
                    return func(*args, **kwargs)
                except self.exceptions as exc:
                    last_exception = exc
                    if attempt < self.max_attempts:
                        time.sleep(delay)
                        delay *= self.backoff_factor
            raise last_exception

        wrapper._retry_instance = self  # expose for testing
        return wrapper

    @property
    def call_count(self):
        return self._call_count

The _retry_instance attribute hanging off the wrapper is the key detail. In tests, you can reach into the decorator’s state:

@retry(max_attempts=2, exceptions=(ConnectionError,))
def fetch_data(url):
    import urllib.request
    return urllib.request.urlopen(url).read()

# In your test suite:
assert fetch_data._retry_instance.max_attempts == 2
assert fetch_data._retry_instance.call_count == 0

Try accessing max_attempts from a closure-based decorator without returning it somewhere awkward. You can’t — or rather, you end up stuffing attributes onto the wrapper function manually, which is exactly what a class already gives you for free.

But class decorators have a gotcha that bites people. When you use a class-based decorator on a method (not a standalone function), self gets shadowed. Watch what happens:

class log_calls:
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func

    def __call__(self, *args, **kwargs):
        print(f"Calling {self.func.__name__}")
        return self.func(*args, **kwargs)

class Server:
    @log_calls
    def start(self):
        return "running"

s = Server()
s.start()
# TypeError: start() missing 1 required positional argument: 'self'

The error is confusing until you realize that log_calls.__call__ becomes the bound method, so Python never passes the Server instance as the first argument. The fix is implementing __get__ to make your decorator a descriptor:

import types

class log_calls:
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func

    def __call__(self, *args, **kwargs):
        print(f"Calling {self.func.__name__}")
        return self.func(*args, **kwargs)

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return types.MethodType(self, obj)

Now s.start() works. The descriptor protocol (defined in Python’s data model docs) binds the decorator instance to the object instance, so *args correctly receives self as the first positional argument. My best guess is that most people avoid class-based decorators for methods specifically because they hit this TypeError and give up, not because the pattern is fundamentally worse.

Stacking decorators: execution order isn’t what you think

When you stack decorators, the bottom one wraps first. This is the standard explanation, and it’s correct — but it only tells half the story. The order in which the wrapper code executes depends on whether the logic runs before or after the wrapped call.

def decorator_a(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print("A: before")
        result = func(*args, **kwargs)
        print("A: after")
        return result
    return wrapper

def decorator_b(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print("B: before")
        result = func(*args, **kwargs)
        print("B: after")
        return result
    return wrapper

@decorator_a
@decorator_b
def greet(name):
    print(f"Hello, {name}")
    return name

greet("Alice")

Output:

A: before
B: before
Hello, Alice
B: after
A: after

It’s an onion. A wraps B wraps greet. The “before” code runs outside-in (A then B), the “after” code runs inside-out (B then A). This matters enormously when you’re stacking, say, a timing decorator with a caching decorator. If the cache decorator is on the outside, you’re timing cache hits too — which gives you meaningless numbers.

# Wrong order — timing includes cache lookup overhead
@timer
@cache
def expensive_computation(n):
    ...

# Better — only times actual computation on cache miss
@cache
@timer
def expensive_computation(n):
    ...

But wait — does the second version even make sense? If @timer wraps the function and @cache wraps the timer, then on a cache hit, the timer never runs and you get stale timing data from the first call. Whether that’s “better” depends on what you’re measuring. There isn’t a universally correct stacking order; you have to think through the call chain for your specific case.

Here’s where it gets subtle. When you stack $n$ decorators, you get $n$ nested wrapper calls on every invocation. For most applications this is irrelevant — we’re talking nanoseconds of overhead per layer. But if you’re decorating a function that gets called in a tight loop (say, millions of iterations), the overhead becomes $O(n \cdot k)$ where $k$ is the per-call function dispatch cost. On CPython 3.12, I measured roughly 50-80ns per wrapper layer on an Apple M1, which means 5 stacked decorators add ~300ns. Negligible for an API endpoint, noticeable inside a numerical inner loop.

The functools.wraps contract (and when it breaks)

By now you’ve seen functools.wraps everywhere. It copies __name__, __module__, __qualname__, __doc__, __dict__, and __wrapped__ from the original function to the wrapper. That __wrapped__ attribute is interesting — it creates a chain you can follow:

@decorator_a
@decorator_b
def greet(name):
    """Say hello."""
    return f"Hello, {name}"

print(greet.__wrapped__.__wrapped__.__name__)  # 'greet'

You can unwrap the whole chain with inspect.unwrap(greet), which follows __wrapped__ until it hits a function without one. This is how debuggers and documentation tools recover the original function signature.

But functools.wraps doesn’t preserve the original function’s signature in a way that IDE type checkers understand. If your decorator changes the return type or adds parameters, functools.wraps won’t help — mypy and pyright will still see the original signature. This is where typing.ParamSpec (introduced in Python 3.10 via PEP 612) comes in.

from typing import TypeVar, ParamSpec, Callable

P = ParamSpec('P')
R = TypeVar('R')

def log_result(func: Callable[P, R]) -> Callable[P, R]:
    @functools.wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        result = func(*args, **kwargs)
        print(f"{func.__name__} returned {result!r}")
        return result
    return wrapper

@log_result
def add(a: int, b: int) -> int:
    return a + b

# mypy now correctly infers: add(a: int, b: int) -> int

ParamSpec captures the parameter specification of the decorated function and forwards it to the wrapper. Before this existed, you had two options: Callable[..., R] (which throws away all parameter info) or a @overload nightmare. I’m not entirely sure why it took until Python 3.10 to get this — the need was obvious years earlier, and the typing_extensions backport was widely used.

For decorators that genuinely transform the signature — adding or removing parameters — you’re in harder territory. The Concatenate type from the same PEP handles prepending parameters:

$$\text{Callable}[P, R] \rightarrow \text{Callable}[\text{Concatenate}[T, P], R]$$

But arbitrary signature transformations still don’t type-check cleanly. Take this with a grain of salt, since the typing ecosystem evolves fast, but as of Python 3.12 there’s no elegant way to express “this decorator removes the first parameter” in the type system.

Production patterns that survive code review

Let me walk through three patterns I’d actually put in production code, with the rough edges included.

Decorator with optional parentheses

This is the single most annoying API decision in decorator design: should @my_decorator work without parentheses AND @my_decorator(timeout=5) work with them? Users expect both, and implementing it requires detecting whether the first argument is the decorated function or a configuration parameter.

def flexible_decorator(func=None, *, timeout=30, retries=1):
    def actual_decorator(f):
        @functools.wraps(f)
        def wrapper(*args, **kwargs):
            # timeout and retries available here via closure
            for attempt in range(retries):
                try:
                    return f(*args, **kwargs)
                except TimeoutError:
                    if attempt == retries - 1:
                        raise
        return wrapper

    if func is not None:
        # Called as @flexible_decorator without parens
        return actual_decorator(func)
    # Called as @flexible_decorator(timeout=60)
    return actual_decorator

# Both work:
@flexible_decorator
def quick_task(): ...

@flexible_decorator(timeout=60, retries=3)
def slow_task(): ...

The trick is that func=None as the first keyword-only-after-default parameter lets you distinguish the two calling conventions. All configuration arguments must be keyword-only (note the * after func). If you accidentally allow @flexible_decorator(30) to mean “timeout=30”, someone will inevitably write @flexible_decorator(some_function) and get a spectacular runtime error three layers deep.

Context-preserving decorator for async

Async decorators are mostly identical to sync ones, except you need async def wrapper and await. But here’s a pattern that handles both:

import asyncio
import inspect

def universal_timer(func):
    if inspect.iscoroutinefunction(func):
        @functools.wraps(func)
        async def async_wrapper(*args, **kwargs):
            start = time.perf_counter()
            result = await func(*args, **kwargs)
            elapsed = time.perf_counter() - start
            print(f"{func.__name__} took {elapsed:.4f}s (async)")
            return result
        return async_wrapper
    else:
        @functools.wraps(func)
        def sync_wrapper(*args, **kwargs):
            start = time.perf_counter()
            result = func(*args, **kwargs)
            elapsed = time.perf_counter() - start
            print(f"{func.__name__} took {elapsed:.4f}s")
            return result
        return sync_wrapper

@universal_timer
async def fetch_page(url):
    await asyncio.sleep(0.1)  # simulated network call
    return f"<html>{url}</html>"

@universal_timer
def compute_hash(data):
    import hashlib
    return hashlib.sha256(data).hexdigest()

The inspect.iscoroutinefunction check at decoration time (not call time) means you pay zero overhead for the wrong branch. One thing that surprised me: iscoroutinefunction returns False for functions decorated with a sync wrapper, even if the underlying function is async. So if you stack a naive sync decorator on top of an async function, then apply universal_timer, it’ll pick the sync path and you’ll get a coroutine object instead of a result. Stacking order matters, again.

Decorator registry for plugin systems

This is maybe the most powerful production pattern — using decorators to build a registry of handlers, routes, or plugins:

class CommandRegistry:
    def __init__(self):
        self._commands = {}

    def command(self, name=None, *, admin_only=False):
        def decorator(func):
            cmd_name = name or func.__name__
            if cmd_name in self._commands:
                # This shouldn't happen, but if someone registers
                # the same command twice during hot-reload...
                import warnings
                warnings.warn(f"Overwriting command '{cmd_name}'")
            self._commands[cmd_name] = {
                'handler': func,
                'admin_only': admin_only,
                'doc': func.__doc__ or '(no description)',
            }
            return func  # return unwrapped — the registry doesn't need to intercept calls
        return decorator

    def execute(self, cmd_name, *args, **kwargs):
        if cmd_name not in self._commands:
            raise KeyError(f"Unknown command: {cmd_name}")
        return self._commands[cmd_name]['handler'](*args, **kwargs)

    def list_commands(self):
        return {k: v['doc'] for k, v in self._commands.items()}

bot = CommandRegistry()

@bot.command("greet", admin_only=False)
def handle_greet(user):
    """Send a greeting to the user."""
    return f"Hello, {user}!"

@bot.command("shutdown", admin_only=True)
def handle_shutdown():
    """Shut down the bot gracefully."""
    return "Shutting down..."

print(bot.list_commands())
# {'greet': 'Send a greeting to the user.', 'shutdown': 'Shut down the bot gracefully.'}
print(bot.execute("greet", "Alice"))
# Hello, Alice!

Notice that return func gives back the original, unwrapped function. The decorator’s job here is registration, not interception. Flask’s @app.route works on exactly this principle (as does Click’s @cli.command and pytest’s @pytest.fixture). The decorator is a side-effect machine: it mutates the registry as a side effect of being applied, and the decorated function keeps its original behavior.

And that’s worth pausing on. Decorators aren’t always about wrapping. Sometimes they’re about registering, validating, or marking.

When not to use decorators

Why would someone argue against the claim I opened with — that class-based decorators deserve more use?

Fair counter-arguments exist. First, readability for the team. If your team is mostly junior developers, a nested closure is conceptually simpler than a class with __call__ and __get__. The descriptor protocol is genuinely confusing until you’ve internalized Python’s attribute lookup machinery. Adding a __get__ method to fix method decoration isn’t obvious, and the failure mode (the TypeError about missing self) doesn’t point toward the solution.

Second, overhead. Each class-based decorator instance is a full Python object with a __dict__, while a closure captures only the variables it references. For decorators applied to thousands of functions (think: large API codebases with per-endpoint auth decorators), the memory difference could add up. I haven’t benchmarked this at scale, so take that claim as theoretical.

Third, the ecosystem. Libraries like wrapt (Graham Dumpleton’s excellent wrapt library) solve the descriptor problem and more, giving you a framework for writing well-behaved decorators without implementing the boilerplate yourself. If you’re using wrapt, the closure-vs-class distinction matters less because wrapt handles the hard parts for both patterns.

Here’s my honest position: for simple decorators — logging, timing, basic validation — closures with functools.wraps are fine. The moment you need configurable state, testability, or inheritance, reach for a class. The overhead of learning the descriptor protocol pays for itself the first time you need to debug a decorator in production, because all the state is right there on the instance instead of captured in a closure you can’t inspect.

The part of decorator design I’m still not satisfied with is composability. Stacking five decorators and reasoning about their interaction is hard, and I don’t think the Python community has settled on a great pattern for it. Maybe something like Haskell’s monad transformers, but for decorators — a way to declare how wrappers compose rather than just hoping the stack order is right. If someone’s working on that, I’d like to see it.