Python Decorators — Why Missing @wraps Breaks Flask Routes

Every serious Python codebase you'll ever read uses decorators. Flask routes use them (@app.route). Django views use them (@login_required). pytest uses them (@pytest.mark.parametrize). They're not a niche feature — they're the language's primary tool for separating cross-cutting concerns like logging, authentication, caching, and validation from your core business logic. If you can't read a decorator confidently, you'll hit a wall the moment you open any real production codebase.

The problem decorators solve is repetition with a twist. You've got ten API endpoint functions and every single one needs to log how long it took, check that the user is authenticated, and catch exceptions gracefully. You could copy-paste that boilerplate into all ten functions — and then spend the next month tracking down why you missed updating it in two of them when the auth logic changed. Or you could write that logic once as a decorator and apply it with a single line above each function. The decorator pattern enforces the DRY principle at the function level, and it does it in a way that's composable and independently testable.

By the end of this article you'll understand exactly what happens when Python sees the @ symbol, you'll be able to write your own decorators from scratch including ones that accept arguments, and you'll know the one functools trick that prevents decorators from silently breaking your code in production. We'll build this up from first principles — starting with why the pattern is even possible in Python, not just how to use it.

What a Python Decorator Actually Does

A Python decorator is a callable that takes a function as input and returns a replacement function, typically augmenting or modifying behavior. The core mechanic is syntactic sugar: @decorator def func(): ... is equivalent to func = decorator(func). This means the decorator runs at definition time, not call time, and the name 'func' is rebound to whatever the decorator returns.

In practice, most decorators return a wrapper function that calls the original, adding logic before, after, or around it. The critical detail: the wrapper is a different function object. Without @functools.wraps, the wrapper inherits none of the original's metadata — __name__, __doc__, __module__, and __qualname__ are all lost. This breaks introspection tools, logging, and frameworks like Flask that rely on function names for route registration.

Use decorators for cross-cutting concerns: logging, timing, access control, caching, or retry logic. They keep business logic clean and reusable. But the moment a decorator wraps a function, you must preserve the original's identity — that's what @wraps does. Skipping it is not a style choice; it's a correctness bug that surfaces in production when your monitoring or routing silently fails.

Building Your First Decorator From Scratch

Now that you know functions are objects, writing a decorator is just writing a function that accepts a function and returns a (usually different) function. That returned function is called the 'wrapper' — it's the sleeve around your coffee cup. The original coffee is still in there. The wrapper just adds things around it.

Here's the anatomy every decorator shares: an outer function that accepts the original function as its only argument, an inner 'wrapper' function that adds the before/after behaviour and calls the original, and a return statement that hands back the wrapper object. When you use @my_decorator, Python passes your function into my_decorator and replaces the name with whatever comes back — the wrapper.

The example below builds a timing decorator — genuinely useful in production for performance monitoring and SLO measurement. Notice how the original fetch_user_data function has no idea it's being timed. That separation is the whole point. You can add, remove, or swap the decorator without touching the business logic. You can test the timing logic independently from the data logic. You can apply it to fifty functions with fifty single lines instead of fifty copy-pasted blocks.

Two things in the wrapper that are absolutely non-negotiable: args, *kwargs in the signature so it works with any function regardless of its parameters, and return result at the end so the wrapper doesn't swallow the original function's return value. Miss either one and the decorator silently breaks every function it touches.

import time
import functools

# ── The decorator ─────────────────────────────────────────────────────────────
# A function that accepts a function — that's the entire outer structure.
def measure_execution_time(original_function):
    """
    A decorator that logs how long the decorated function took to run.
    Works with any function regardless of its arguments or return value.
    """

    # @functools.wraps copies __name__, __doc__, __module__, and other metadata
    # from original_function onto wrapper. Without this line, original_function.__name__
    # would silently become 'wrapper' — breaking Flask, pytest, and Sphinx.
    @functools.wraps(original_function)
    def wrapper(*args, **kwargs):   # *args/**kwargs: accepts ANY function signature
        start_time = time.perf_counter()             # high-resolution timer

        result = original_function(*args, **kwargs)  # call the real function, capture result

        end_time = time.perf_counter()
        duration_ms = (end_time - start_time) * 1000

        print(f"[TIMER] {original_function.__name__} completed in {duration_ms:.2f}ms")

        return result   # CRITICAL: always return the result — never swallow it

    return wrapper   # return the wrapper OBJECT — no parentheses


# ── Apply the decorator ───────────────────────────────────────────────────────
# Python executes: fetch_user_data = measure_execution_time(fetch_user_data)
# The name 'fetch_user_data' now points to wrapper, not the original function.
@measure_execution_time
def fetch_user_data(user_id):
    """Simulates a database lookup with a small delay."""
    time.sleep(0.05)   # simulate 50ms database query
    return {"id": user_id, "name": "Alice", "role": "admin"}


@measure_execution_time
def calculate_monthly_report(year, month, include_tax=True):
    """Simulates a heavy report calculation."""
    time.sleep(0.1)   # simulate 100ms computation
    return {"year": year, "month": month, "total": 48250.75}


# ── Call site looks completely normal ─────────────────────────────────────────
# The timing is invisible to the caller — that's the point.
user = fetch_user_data(42)
print(f"Got user: {user['name']}\n")

report = calculate_monthly_report(2026, 6, include_tax=True)
print(f"Report total: ${report['total']}")

# ── Verify functools.wraps preserved the metadata ──────────────────────────────
print(f"\nFunction name: {fetch_user_data.__name__}")     # fetch_user_data, not 'wrapper'
print(f"Docstring:     {fetch_user_data.__doc__}")        # original docstring preserved

Decorators That Accept Their Own Arguments

The next level is writing decorators that are themselves configurable. Think of Flask's @app.route('/users', methods=['GET']) or @retry(max_attempts=3, delay_seconds=1.0) — those decorators take arguments. How does that work? You need one more layer of nesting.

The key insight: @app.route('/users') is not the decorator itself — it's a call that returns the decorator. The parentheses after route tell you it's being called as a factory function. So the structure is: a factory function that accepts your configuration and returns a standard decorator, which in turn returns the wrapper. Three layers total, three def keywords: factory → decorator → wrapper.

This pattern is extremely common in production code. Retry logic with configurable attempt counts. Rate limiting with a configurable threshold. Permission checks with a configurable required role. Caching with a configurable TTL. Anywhere you have behaviour that's the same in structure but different in parameters per function, you want a decorator factory.

The example below builds a @retry decorator with configurable attempts, delay, and exception types — the kind of thing you'd actually ship to wrap calls to unreliable external APIs. After building it, the usage line reads like English: @retry(max_attempts=3, delay_seconds=0.1, exceptions_to_catch=(ConnectionError,)). The three-layer pattern is what makes that possible.

import time
import functools

# ── LAYER 1: The factory ──────────────────────────────────────────────────────
# Accepts configuration, returns a decorator.
# This is what @retry(max_attempts=3) calls.
def retry(max_attempts=3, delay_seconds=1.0, exceptions_to_catch=None):
    """
    A configurable retry decorator.
    max_attempts:       how many times to try before giving up
    delay_seconds:      how long to wait between attempts
    exceptions_to_catch: only retry on these specific exception types
    """
    # Mutable default argument trap — use None and create inside the factory
    if exceptions_to_catch is None:
        exceptions_to_catch = (Exception,)

    # ── LAYER 2: The actual decorator ─────────────────────────────────────────
    # Accepts the function to wrap. This is what the factory returns.
    def decorator(original_function):

        # ── LAYER 3: The wrapper ───────────────────────────────────────────────
        # Runs every time the decorated function is called.
        @functools.wraps(original_function)
        def wrapper(*args, **kwargs):
            last_exception = None

            for attempt_number in range(1, max_attempts + 1):
                try:
                    print(f"  Attempt {attempt_number}/{max_attempts} for '{original_function.__name__}'")
                    result = original_function(*args, **kwargs)
                    print(f"  Success on attempt {attempt_number}!")
                    return result   # worked — return immediately

                except exceptions_to_catch as error:
                    last_exception = error
                    print(f"  Failed: {error}")

                    # Don't sleep after the final attempt — pointless to wait then fail
                    if attempt_number < max_attempts:
                        time.sleep(delay_seconds)

            # All attempts exhausted — surface the last error clearly
            raise RuntimeError(
                f"'{original_function.__name__}' failed after {max_attempts} attempts. "
                f"Last error: {last_exception}"
            )

        return wrapper      # decorator returns the wrapper
    return decorator        # factory returns the decorator


# ── Simulate an unreliable external API ───────────────────────────────────────
call_counter = 0

@retry(max_attempts=3, delay_seconds=0.1, exceptions_to_catch=(ConnectionError,))
def fetch_weather_data(city):
    """Simulates a flaky HTTP call that succeeds on the 3rd attempt."""
    global call_counter
    call_counter += 1

    if call_counter < 3:
        raise ConnectionError(f"Connection timed out reaching weather API (call #{call_counter})")

    return {"city": city, "temperature_c": 22, "condition": "Sunny"}


# Usage is clean — all retry logic is invisible at the call site
print("Fetching weather...")
weather = fetch_weather_data("London")
print(f"\nFinal result: {weather['city']} is {weather['temperature_c']}°C and {weather['condition']}")

# Verify functools.wraps preserved the function name across three layers
print(f"\nFunction name preserved: {fetch_weather_data.__name__}")

Decorators with Arguments

The wrapper-factory pattern is the standard way to write configurable decorators, but it's worth unpacking it under the name 'Decorators with Arguments' because it's the single most requested pattern in interviews and the most frequently misunderstood by intermediate developers. When you see @decorator(...) with parentheses that contain arguments, you're not applying the decorator directly — you're calling a factory that returns the actual decorator. This extra level of indirection is what makes the configuration possible.

Let's build a different example: a @log_with_config decorator that lets you specify a log prefix and a logging level for each decorated function. This pattern is exactly what you'd use in production to tag logs by service or endpoint name. The structure is identical to the retry example: the outer factory captures the configuration, the middle function captures the original function, and the inner wrapper handles the call-time logic.

The factory must be invoked at decoration time — that's why you see @log_with_config(prefix="API") with parentheses. If you wrote @log_with_config without parentheses, Python would treat log_with_config as a decorator (the middle layer), but it would receive a function as its argument instead of configuration, and everything would break in confusing ways. The presence or absence of parentheses at the @ line is the single visual clue that tells you which pattern is in use.

Once you internalise that the parentheses mean 'call a factory', you can read any configurable decorator from any framework confidently. The factory receives configuration and returns a decorator. The decorator receives a function and returns a wrapper. The wrapper receives the call arguments and returns the result. Three layers, three responsibilities.

import functools
import logging

# ── Factory that creates a configurable logging decorator ─────────────────────
# The @log_with_config(prefix="API", level=logging.INFO) syntax calls this factory.
def log_with_config(prefix="APP", level=logging.DEBUG):
    """
    Factory that returns a decorator which logs function calls with a custom prefix and log level.
    """
    # LAYER 2: The actual decorator — receives the function to wrap
    def decorator(original_function):

        # LAYER 3: The wrapper — runs at call time
        @functools.wraps(original_function)
        def wrapper(*args, **kwargs):
            # Log before execution using the configuration from the factory closure
            logging.log(level, f"[{prefix}] Calling {original_function.__name__} with args={args}, kwargs={kwargs}")

            result = original_function(*args, **kwargs)

            # Log after execution
            logging.log(level, f"[{prefix}] {original_function.__name__} returned {result}")

            return result

        return wrapper

    return decorator


# ── Set up logging to see output ──────────────────────────────────────────────
logging.basicConfig(level=logging.DEBUG, format="%(message)s")


# ── Apply the configurable decorator ──────────────────────────────────────────
# Note the parentheses with arguments — this calls the factory at decoration time.
@log_with_config(prefix="API", level=logging.INFO)
def fetch_user(user_id):
    return {"id": user_id, "name": "Alice"}


@log_with_config(prefix="DB")
def get_product(sku):
    return {"sku": sku, "price": 29.99}


# ── Usage is transparent ──────────────────────────────────────────────────────
user = fetch_user(42)
product = get_product("ABC-123")


# ── Verify metadata survives three layers ────────────────────────────────────
print(f"\nfetch_user.__name__: {fetch_user.__name__}")
print(f"get_product.__name__: {get_product.__name__}")

Real-World Pattern — A Decorator for Route Authentication

Let's cement everything with a pattern you'll write within your first month on any web backend: an authentication guard. This is exactly how Flask's @login_required and Django's @permission_required work under the hood. Understanding it means you'll never be intimidated by framework decorator magic again — because you'll be looking at the same structure you just built.

The decorator below simulates checking a user session before allowing a function to execute. If the session is invalid, execution stops immediately and an error response is returned. If the required role is missing, same thing. Only if all checks pass does the original function run — with session data injected into its kwargs so it doesn't need to fetch the session itself.

Notice that this decorator doesn't time anything or retry anything. It's purely about access control. This is the single-responsibility principle applied at the decorator level. Each decorator does one job well, and you compose multiple jobs by stacking decorators. A route handler that needs auth and timing gets @measure_execution_time stacked above @require_authentication — two clean lines, two independent concerns, each independently testable and replaceable.

This composition model is why decorators are the idiomatic solution to cross-cutting concerns in Python. The alternative — putting auth and timing and logging code directly inside every route handler — produces functions that are hard to read, impossible to test in isolation, and painful to update when any one concern changes.

import functools

# ── Simulated session store ────────────────────────────────────────────────────
# In production this would be Redis, a database, or a JWT verification service.
active_sessions = {
    "token_abc123": {"user_id": 7,  "username": "alice", "role": "admin"},
    "token_xyz789": {"user_id": 12, "username": "bob",   "role": "viewer"},
}


# ── The decorator factory ─────────────────────────────────────────────────────
def require_authentication(required_role=None):
    """
    Decorator factory that guards a function behind session authentication.
    Optionally enforces a specific role (e.g., 'admin').
    Returns 401 for invalid sessions, 403 for insufficient permissions.
    """
    def decorator(original_function):
        @functools.wraps(original_function)
        def wrapper(session_token, *args, **kwargs):
            # Step 1: Check token exists in active sessions
            session = active_sessions.get(session_token)

            if session is None:
                # Guard fails — return immediately, never call original_function
                return {"error": "Unauthorised. Invalid or expired session token.", "status": 401}

            # Step 2: Check role if one is required
            if required_role and session["role"] != required_role:
                return {
                    "error": f"Forbidden. Requires role '{required_role}', got '{session['role']}'.",
                    "status": 403
                }

            # Step 3: Inject session data — the handler gets it via kwargs, no extra lookup needed
            kwargs["current_user"] = session

            # Step 4: All checks passed — call the real function
            return original_function(session_token, *args, **kwargs)

        return wrapper
    return decorator


# ── Protected route handlers ───────────────────────────────────────────────────
# Any authenticated user can view their own profile
@require_authentication()
def get_user_profile(session_token, **kwargs):
    user = kwargs["current_user"]
    return {"status": 200, "profile": {"username": user["username"], "role": user["role"]}}


# Only admins can delete accounts
@require_authentication(required_role="admin")
def delete_user_account(session_token, target_user_id, **kwargs):
    admin = kwargs["current_user"]
    return {"status": 200, "message": f"Account {target_user_id} deleted by {admin['username']}"}


# ── Test all scenarios ────────────────────────────────────────────────────────
print("=== Valid admin token ===")
print(get_user_profile("token_abc123"))
print(delete_user_account("token_abc123", target_user_id=99))

print("\n=== Valid viewer token (no admin rights) ===")
print(get_user_profile("token_xyz789"))
print(delete_user_account("token_xyz789", target_user_id=99))

print("\n=== Invalid token ===")
print(get_user_profile("token_fake999"))

# ── Verify metadata is intact across two-layer decorator ─────────────────────
print(f"\nget_user_profile.__name__:      {get_user_profile.__name__}")
print(f"delete_user_account.__name__:   {delete_user_account.__name__}")

Built-in Decorators: @property vs @staticmethod vs @classmethod

Python ships with three built-in decorators that every developer should understand at a glance: @property, @staticmethod, and @classmethod. They're all used inside class definitions to change how methods are called, but they serve fundamentally different purposes. Knowing when to use each — and, more importantly, when not to — is a common interview topic and a frequent source of confusion in code reviews.

@property transforms a method into an attribute descriptor — it lets you call obj.attribute without parentheses while the method runs arbitrary logic behind the scenes. Use this for computed attributes or read-only access that needs validation or lazy loading. @staticmethod is like a regular function that lives inside the class namespace for organisational reasons — it receives neither self nor cls and cannot access instance or class state. @classmethod receives the class (cls) instead of the instance, and is used for factory methods (e.g., MyClass.from_json(data)) or for methods that need to access or modify class-level state.

The decision tree for choosing among them: if you need access to the instance (self), use a regular method. If you need to return a value computed from instance data but want attribute-style access, decorate with @property. If you need access to the class (cls) but not the instance, decorate with @classmethod. If you need neither self nor cls — the method is just a helper that happens to be in the class — use @staticmethod. If you find yourself using @staticmethod, consider whether the function could live outside the class entirely; sometimes it's cleaner as a module-level function.

class User:
    # ── Class-level attribute ───────────────────────────────────────────────────
    user_count = 0

    def __init__(self, first_name, last_name, birth_year):
        self.first_name = first_name
        self.last_name = last_name
        self.birth_year = birth_year
        User.user_count += 1   # increment class-level counter

    # ── @property: computed attribute, called without parentheses ───────────────
    @property
    def full_name(self):
        """Returns a computed full name. Access as user.full_name, not user.full_name()."""
        return f"{self.first_name} {self.last_name}"

    @property
    def age(self):
        """Calculates age based on current year. Read-only property."""
        from datetime import date
        return date.today().year - self.birth_year

    # ── @classmethod: receives the class (cls), not the instance (self) ───────
    @classmethod
    def from_csv_string(cls, csv_line):
        """Factory method: creates a User instance from a comma-separated string."""
        first_name, last_name, birth_year = csv_line.split(",")
        return cls(first_name, last_name, int(birth_year))   # uses cls, not hardcoded User

    @classmethod
    def get_user_count(cls):
        """Returns the total number of User instances created."""
        return cls.user_count

    # ── @staticmethod: neither self nor cls ─────────────────────────────────────
    @staticmethod
    def is_valid_name(name):
        """Validates that a name is not empty and contains only letters."""
        return bool(name) and name.replace(" ", "").isalpha()


# ── Usage ─────────────────────────────────────────────────────────────────────
user = User("Alice", "Johnson", 1990)

# @property — note: no parentheses
print(f"Full name: {user.full_name}")
print(f"Age: {user.age}")

# @classmethod — called on the class, not the instance
user2 = User.from_csv_string("Bob,Smith,1985")
print(f"Created from CSV: {user2.full_name}")
print(f"Total users: {User.get_user_count()}")

# @staticmethod — no self or cls
print(f"Name valid?: {User.is_valid_name('Alice')}")

Class-based Decorators Using __call__

Not all decorators need to be functions. Python classes that implement __call__ (the callable protocol) can also serve as decorators. This approach is less common but powerful when the decorator needs to maintain state across invocations, manage configuration more explicitly, or be part of a class hierarchy.

A class-based decorator looks like a function-based one at the @ line — @MyDecorator above a function definition — but the class's __init__ receives the original function, and __call__ replaces the wrapper. Each time the decorated function is called, __call__ runs instead of the original. Because __call__ is a method on an instance, the instance can store state between invocations.

This is especially useful for stateful decorators like call counters, memoization caches, or rate limiters that accumulate data. Compare this to a function-based decorator where state must be stored in mutable closures or global variables — the class version is cleaner because all state lives in self.

The example below implements a call counter decorator as a class. Every time the decorated function is called, the counter increments. The class stores the count, the original function reference, and the metadata. Notice we still need to copy function metadata — we can do it manually or use functools.update_wrapper in __init__.

import functools

# ── Class-based decorator: maintains a call counter ───────────────────────────
class CountCalls:
    """
    A decorator that counts how many times the decorated function is called.
    The count is stored as an instance attribute (self.count).
    """
    def __init__(self, original_function):
        """
        __init__ receives the function being decorated.
        This is equivalent to the outer function in a function-based decorator.
        """
        self.original_function = original_function
        self.count = 0

        # Manually copy metadata — functools.update_wrapper does what @wraps does
        functools.update_wrapper(self, original_function)

    def __call__(self, *args, **kwargs):
        """
        __call__ runs every time the decorated function is called.
        This is equivalent to the wrapper function.
        """
        self.count += 1
        print(f"[CountCalls] {self.original_function.__name__} called {self.count} time(s)")

        # Call the original function and return its result
        return self.original_function(*args, **kwargs)


# ── Apply the class-based decorator ───────────────────────────────────────────
@CountCalls
def greet(name):
    """Say hello to someone."""
    return f"Hello, {name}!"


@CountCalls
def add(a, b):
    """Add two numbers."""
    return a + b


# ── Call site remains unchanged ───────────────────────────────────────────────
print(greet("Alice"))
print(greet("Bob"))
print(greet("Carol"))

print(f"\n{add(2, 3)}")
print(f"{add(5, 7)}")

# ── Access the call count — unique to class-based decorators ─────────────────
# Since the decorator is an instance, we can access its attributes.
print(f"\ngreet was called {greet.count} times")
print(f"add was called {add.count} times")

# ── Metadata preserved ───────────────────────────────────────────────────────
print(f"\ngreet.__name__: {greet.__name__}")

Why Stacking Multiple Decorators Breaks in Production

You've seen the neat examples: three decorators stacked with @ signs like a tidy sandwich. In production, that stack often explodes. Here is why. Each decorator wraps the previous one. But if even one decorator loses the original function's metadata — __name__, __doc__, signature — debugging turns into a nightmare. Your call stack reads wrapper for every single layer. And if you apply a decorator that returns a class instead of a function (yes, people do that), the next decorator in the stack silently fails because it expects a callable with different attributes. The fix is non-negotiable: use functools.wraps on every single decorator you write. It copies the original function's metadata to the wrapper. Without it, your stack trace becomes a wall of anonymous wrappers, and your logging pipeline starts showing wrapper instead of meaningful function names. Don't learn this during a PagerDuty alert at 3 AM.

// io.thecodeforge
import functools

def log_execution(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

def validate_auth(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        if not kwargs.get('token'):
            raise PermissionError("Missing auth token")
        return func(*args, **kwargs)
    return wrapper

@log_execution
@validate_auth
def fetch_user_data(user_id: int, token: str) -> dict:
    """Fetch user data from internal API."""
    return {"id": user_id, "name": "Alice"}

print(fetch_user_data.__name__)  # 'fetch_user_data', not 'wrapper'
print(fetch_user_data.__doc__)   # 'Fetch user data from internal API.'

Decorating Classes Without Losing State

Decorators aren't just for functions. You can decorate a class to inject behavior across all instances — think logging every method call or enforcing a singleton pattern. But there's a catch: if you naively replace the class with a function, you lose isinstance checks and the ability to subclass. The better way: write a decorator that returns a class, either by subclassing or by modifying the original class's __init__ and methods. For production scenarios like audit logging, wrap each method individually inside the decorator. This preserves the class hierarchy and keeps your type checking honest. Remember: isinstance(obj, MyDecoratedClass) must still work. If it returns False after decoration, your testing pipeline will fail silently until someone merges a broken hotfix. I've seen it happen. The pattern below shows how to wrap a class while keeping its identity intact — no magic, just a function that returns a new class with the same name and bases.

// io.thecodeforge
import functools

def audit_methods(cls):
    """Decorator that logs all method calls on a class."""
    class AuditWrapper(cls):
        def __getattribute__(self, name):
            attr = super().__getattribute__(name)
            if callable(attr) and not name.startswith('_'):
                @functools.wraps(attr)
                def wrapper(*args, **kwargs):
                    print(f"AUDIT: calling {cls.__name__}.{name}")
                    return attr(*args, **kwargs)
                return wrapper
            return attr
    AuditWrapper.__name__ = cls.__name__
    AuditWrapper.__qualname__ = cls.__qualname__
    return AuditWrapper

@audit_methods
class PaymentProcessor:
    def charge(self, amount: float) -> str:
        return f"Charged ${amount}"

p = PaymentProcessor()
print(p.charge(100.0))
print(isinstance(p, PaymentProcessor))  # True

Decorators with Arguments: Nested Function Pattern

Decorators with arguments require an additional layer of nesting. The outermost function accepts the decorator arguments, returns a decorator function that takes the original function, and that decorator returns a wrapper. This pattern is essential for configurable decorators like route authentication with permissions.

Example: A decorator that checks user role before allowing access.

```python def require_role(role): def decorator(func): def wrapper(args, kwargs): if get_current_user_role() != role: raise PermissionError("Insufficient role") return func(args, **kwargs) return wrapper return decorator

@require_role("admin") def delete_user(user_id): # delete user logic pass ```

This pattern is equivalent to require_role("admin")(delete_user). The outer function captures the role argument, the middle function receives the decorated function, and the inner wrapper adds behavior. Without this nesting, you cannot pass arguments to the decorator itself.

def require_role(role):
    def decorator(func):
        def wrapper(*args, **kwargs):
            if get_current_user_role() != role:
                raise PermissionError("Insufficient role")
            return func(*args, **kwargs)
        return wrapper
    return decorator

@require_role("admin")
def delete_user(user_id):
    # delete user logic
    pass

functools.wraps: Preserving Metadata

When you create a decorator, the wrapper function replaces the original function's metadata (name, docstring, module, etc.). This breaks introspection tools, debugging, and frameworks like Flask that rely on function names for routing. The functools.wraps decorator copies the original function's metadata to the wrapper.

Without @wraps:

def my_decorator(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper
@my_decorator
def greet(name):
    """Say hello"""
    return f"Hello {name}"
print(greet.__name__)  # Output: wrapper
print(greet.__doc__)   # Output: None

With @wraps:

from functools import wraps
def my_decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper
@my_decorator
def greet(name):
    """Say hello"""
    return f"Hello {name}"
print(greet.__name__)  # Output: greet
print(greet.__doc__)   # Output: Say hello

Flask uses func.__name__ to register routes. Without @wraps, your route names become 'wrapper', causing 404 errors or incorrect endpoint resolution. Always use @wraps in your decorators.

from functools import wraps

def my_decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@my_decorator
def greet(name):
    """Say hello"""
    return f"Hello {name}"

print(greet.__name__)  # Output: greet
print(greet.__doc__)   # Output: Say hello

Class-based Decorators with __call__

Instead of nested functions, you can implement decorators as classes with a __call__ method. This is useful when the decorator needs to maintain state or has multiple methods. The class instance acts as the decorator, and __call__ is invoked when the decorated function is called.

Example: A decorator that counts how many times a function is called.

```python class CountCalls: def __init__(self, func): self.func = func self.count = 0

def __call__(self, args, kwargs): self.count += 1 print(f"Call {self.count} of {self.func.__name__}") return self.func(args, **kwargs)

@CountCalls def say_hello(name): return f"Hello {name}"

say_hello("Alice") # Output: Call 1 of say_hello say_hello("Bob") # Output: Call 2 of say_hello ```

Class-based decorators can also accept arguments by adding an extra level: a factory function that returns a class, or using __init__ to store arguments and __call__ to return the wrapper.

```python class Retry: def __init__(self, max_retries=3): self.max_retries = max_retries

def __call__(self, func): def wrapper(args, kwargs): for attempt in range(self.max_retries): try: return func(args, **kwargs) except Exception: if attempt == self.max_retries - 1: raise return None return wrapper

@Retry(max_retries=5) def unstable_api_call(): pass ```

Class-based decorators are more readable for complex stateful behavior, but they require careful handling of metadata (use @wraps inside __call__).

class CountCalls:
    def __init__(self, func):
        self.func = func
        self.count = 0

    def __call__(self, *args, **kwargs):
        self.count += 1
        print(f"Call {self.count} of {self.func.__name__}")
        return self.func(*args, **kwargs)

@CountCalls
def say_hello(name):
    return f"Hello {name}"

say_hello("Alice")  # Output: Call 1 of say_hello
say_hello("Bob")    # Output: Call 2 of say_hello