Class Decorators, Stacking and Decorator Factories

As your decorator library grows, you need to understand how multiple decorators interact when stacked, how to build stateful decorators using classes, and how to write decorator factories that accept arguments cleanly. These advanced patterns unlock the full power of Python’s decorator system. Understanding decorator stacking order is also critical when working with FastAPI — route handlers often have multiple decorators from different sources (FastAPI, authentication, caching) and the order determines how they interact. Class-based decorators add state without closures, making certain patterns cleaner and more explicit.

Stacking Multiple Decorators #

import functools

def bold(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return f"<b>{func(*args, **kwargs)}</b>"
    return wrapper

def italic(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return f"<i>{func(*args, **kwargs)}</i>"
    return wrapper

def underline(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return f"<u>{func(*args, **kwargs)}</u>"
    return wrapper

# ── Stacking order: applied bottom-up, executed top-down ─────────────────────
@bold        # applied third (outermost wrapper)
@italic      # applied second
@underline   # applied first (innermost wrapper)
def greet(name: str) -> str:
    return f"Hello, {name}"

# Equivalent to:
# greet = bold(italic(underline(greet_original)))

print(greet("Alice"))
# <b><i><u>Hello, Alice</u></i></b>

# Execution order (call greet("Alice")):
# bold wrapper  → calls italic wrapper
# italic wrapper → calls underline wrapper
# underline wrapper → calls original greet
# underline result → "<u>Hello, Alice</u>"
# italic result   → "<i><u>Hello, Alice</u></i>"
# bold result     → "<b><i><u>Hello, Alice</u></i></b>"

# ── Key rule: decorators are applied bottom to top ────────────────────────────
# The decorator closest to 'def' is applied first (innermost)
# The decorator furthest from 'def' is applied last (outermost)
# When called, the outermost decorator runs first

Class-Based Decorators #

import functools
import time

class RateLimit:
    """Class-based decorator that enforces a rate limit on function calls."""

    def __init__(self, max_calls: int, period_seconds: float):
        self.max_calls     = max_calls
        self.period        = period_seconds
        self.call_times    = []

    def __call__(self, func):
        """Return a wrapper function that enforces the rate limit."""
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            now    = time.time()
            cutoff = now - self.period

            # Remove calls outside the window
            self.call_times = [t for t in self.call_times if t > cutoff]

            if len(self.call_times) >= self.max_calls:
                raise RuntimeError(
                    f"Rate limit exceeded: {self.max_calls} calls per {self.period}s"
                )

            self.call_times.append(now)
            return func(*args, **kwargs)
        return wrapper

# Usage — RateLimit(10, 60) creates an instance, __call__ makes it a decorator
@RateLimit(max_calls=10, period_seconds=60)
def send_email(recipient: str, subject: str) -> bool:
    print(f"Sending '{subject}' to {recipient}")
    return True

# ── CallCount — simpler stateful decorator ────────────────────────────────────
class CallCount:
    def __init__(self, func):
        functools.update_wrapper(self, func)   # same as @wraps for classes
        self.func  = func
        self.count = 0

    def __call__(self, *args, **kwargs):
        self.count += 1
        return self.func(*args, **kwargs)

@CallCount
def greet(name): return f"Hello, {name}"

greet("Alice")
greet("Bob")
print(greet.count)   # 2

Decorator Factories with Optional Arguments #

import functools

# Pattern: make decorator work both with and without arguments
def log(func=None, *, level: str = "INFO", prefix: str = ""):
    """Log function calls. Works as @log or @log(level="DEBUG")."""
    if func is None:
        # Called with arguments: @log(level="DEBUG")
        # Return an actual decorator
        return lambda f: log(f, level=level, prefix=prefix)

    # Called without arguments: @log
    tag = f"[{prefix}] " if prefix else ""

    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"{tag}{level}: Calling {func.__name__}")
        result = func(*args, **kwargs)
        print(f"{tag}{level}: {func.__name__} returned")
        return result
    return wrapper

# Both forms work:
@log
def quick():
    pass

@log(level="DEBUG", prefix="DB")
def database_query():
    pass

# Called with wrong argument type triggers the right path
@log()   # func=None, uses defaults
def another():
    pass

Common Mistakes #

Mistake 1 — Wrong stacking order for auth + cache #

❌ Wrong — cache runs before auth, serves cached responses to unauthenticated users:

@require_auth   # runs second (inner) — too late!
@cache          # runs first (outer) — cached before auth check!

✅ Correct — auth (outermost) runs first:

@cache          # runs second — only reached after auth passes ✓
@require_auth   # runs first (outermost) — checks auth before caching

Mistake 2 — Shared state between decorated instances #

❌ Wrong — single class instance shared across all decorated functions:

rate_limiter = RateLimit(10, 60)

@rate_limiter   # ALL uses of this decorator share the same call_times list!
def api_a(): pass

@rate_limiter   # api_a and api_b share the rate limit pool
def api_b(): pass

✅ Correct — create a new instance per decoration:

@RateLimit(10, 60)   # new RateLimit instance for each ✓
def api_a(): pass

@RateLimit(10, 60)   # separate rate limit pool ✓
def api_b(): pass

Mistake 3 — Applying class-based decorator to a method without testing #

❌ Wrong — the class instance is passed as the first arg, not the method’s self:

class MyClass:
    @CallCount   # CallCount.__call__ receives (MyClass_instance, *args)
    def method(self):   # 'self' here is the MyClass instance, NOT the CallCount instance
        pass   # Descriptor protocol needed for this to work correctly

✅ Correct — use function-based decorators for methods, class-based for module-level functions.

Quick Reference — Stacking Order #