Decorators

What it is and why it exists

A Python decorator transforms one callable into another object. The usual function decorator receives a function and returns a wrapper that adds behavior around a call; a class can also be the input. When @trace appears above a def, the name ultimately refers to the value returned by trace(), which needn’t be the original function.

The mechanism depends on first-class functions : a function can be passed as an argument and returned as a result. A wrapper is often also a closure that reaches the original function and configuration through enclosing bindings. A decorator itself may be a function, a class, or another callable object.

Decorators fit narrow rules that many functions must follow, such as call recording, authorization checks, retry entry points, or registration declarations. They keep the rule in one implementation while leaving each decorated function’s business body intact. If a rule changes return types, swallows exceptions, or depends on hidden global state, the @ syntax hides consequential behavior; an explicit function call or object composition is clearer.

You meet decorators in standard-library tools including @property, @classmethod, @staticmethod, @functools.cache, and @functools.singledispatch. Web routing, test fixtures, and command registration often use the same syntax, but each framework adds a contract for the returned object. Python’s replacement rule is the foundation for reading those framework conventions.

A decorator isn’t a switch temporarily enabled when the function runs. As execution reaches the definition, Python evaluates the decorator expressions, invokes the decorators, and binds the resulting name; importing a module normally triggers this work. A wrapper’s function body waits until a later call.

How it works

When a decorated function definition executes, Python evaluates each decorator expression in the surrounding scope from top to bottom, then creates the original function object. The resulting callables receive that object from the inside out. The outermost decorator’s return value is finally bound to the function name.

One equivalence is worth memorizing. If the source reads @outer(config), @inner, and def handle(...): ... from top to bottom, the final binding is approximately handle = outer(config)(inner(handle)); unlike that assignment, the original function isn’t temporarily bound to handle. Decorator expressions are evaluated in written order, while application proceeds outward from the decorator closest to def.

Keep definition time separate from call time. The factory outer(config) runs during definition and produces the actual decorator, and both inner(handle) and the outer application complete in that phase. A later handle() call enters the outermost wrapper, moves through each layer to the original function, and returns in the opposite direction.

A wrapper must preserve its contract

A transparent function decorator must at least forward every argument, return the original result, and let unhandled exceptions propagate. *args and **kwargs forward a call shape, but don’t themselves preserve a function signature . If a wrapper intentionally adds parameters, changes the sync model, or transforms the result type, treat that as a new public API instead of claiming transparency.

functools.wraps(func) copies common metadata to the wrapper and sets __wrapped__ to the wrapped object. inspect.signature() follows that chain by default, and documentation tools and some frameworks rely on it. wraps() doesn’t repair bad argument forwarding, return values, exception policy, or sync/async boundaries.

Runtime metadata and static typing are separate mechanisms. A type-preserving decorator can use ParamSpec for the original parameter list and TypeVar for the return type; @wraps is still needed for the runtime introspection chain. Type annotations neither validate calls nor prove that the wrapper really returns the result unchanged.

Functions, methods, and classes

Plain functions implement descriptor binding, so a function stored as a class attribute becomes a bound method when accessed through an instance. A decorator that returns a plain function generally retains that behavior. If it returns an instance with __call__() but no suitable __get__(), obj.method() won’t inject self automatically.

@classmethod, @staticmethod, and @property return descriptor objects, and ordering controls what an outer decorator receives. A decorator written only for plain functions and reading __name__ may not wrap every descriptor. Constrain each supported target explicitly, then test both class and instance access paths.

A class decorator receives a class after its class object has been created and binds the return value to the class name. It can register or modify that class, but defining a subclass later doesn’t rerun the decoration automatically. If a class decorator returns a function to implement a singleton, the original name is no longer a class, so isinstance(), inheritance, and type tooling encounter a completely different object.

Examples

The four examples cover transparent wrapping, a parameterized factory, stacking order, and the async boundary. Their output came from local Python 3.12.13; the examples were also checked against the target Python 3.14 documentation and use no APIs that differ between those versions.

Recording a call transparently

trace() returns a new function that records entry and result, then gives the result back to its caller. @wraps(func) keeps the name, documentation, and default inspected signature pointed at total()’s public contract.

total is the wrapper, while total.__wrapped__ retains an explicit link to the original function. Calling that attribute bypasses logging, so it belongs in introspection, tests, or a deliberate bypass, not as a routine application entry point.

The logger uses repr() for deterministic sample output. A real system shouldn’t record passwords, tokens, or personal data without redaction, and printing a complete return object may be both sensitive and expensive. Redaction belongs in the decorator’s contract.

Configuring retry with a decorator factory

retry_on() first receives an exception type and attempt count, then returns the decorator that accepts a function. The actual wrapper catches only the declared exception, and the factory rejects an invalid attempt count immediately at definition time.

from functools import wraps


def retry_on(exception_type, *, attempts):
    if attempts < 1:
        raise ValueError("attempts must be at least 1")

    def decorate(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(1, attempts + 1):
                try:
                    return func(*args, **kwargs)
                except exception_type as error:
                    print(f"attempt {attempt}: {error}")
                    if attempt == attempts:
                        raise

        return wrapper

    return decorate


responses = iter([
    ConnectionError("temporary outage"),
    ConnectionError("temporary outage"),
    "12 units",
])


@retry_on(ConnectionError, attempts=3)
def fetch_inventory():
    outcome = next(responses)
    if isinstance(outcome, Exception):
        raise outcome
    return outcome


print(fetch_inventory())

attempt 1: temporary outage
attempt 2: temporary outage
12 units

The three call layers have distinct jobs: retry_on(...) configures the factory, decorate(func) receives the decorated function, and wrapper(...) handles each call. Collapsing two of them often leaves @retry_on(...) returning something that isn’t a decorator or calls the business function during definition.

This example deliberately adds no delay. A production retry policy must also define backoff, jitter, deadlines, cancellation, and idempotency, and it should retry only errors classified as transient. A decorator can reuse the policy; it can’t decide whether repeating a business operation is safe.

Seeing both stacking orders

layer() prints build during definition, its returned decorator prints apply, and the wrapper prints enter and leave during a call. One output exposes expression evaluation, decorator application, and wrapper invocation as separate orders.

from functools import wraps


def layer(name):
    print(f"build {name}")

    def decorate(func):
        print(f"apply {name} to {func.__name__}")

        @wraps(func)
        def wrapper():
            print(f"enter {name}")
            result = func()
            print(f"leave {name}")
            return result

        return wrapper

    return decorate


@layer("outer")
@layer("inner")
def render_invoice():
    print("body")
    return "done"


print(render_invoice())

build outer
build inner
apply inner to render_invoice
apply outer to render_invoice
enter outer
enter inner
body
leave inner
leave outer
done

Expressions evaluate from top to bottom, so build outer appears first. Application proceeds bottom to top, calls proceed outside in, and returns unwind inside out. Saying only that “decorators execute bottom to top” conflates three different phases.

Order changes real semantics. Auditing outside authorization can record rejected attempts; auditing inside it sees only accepted calls. Transaction, cache, and retry order also changes which results are cached and whether each attempt gets a new transaction.

Preserving the async boundary

A transparent wrapper for an async function must also use async def and await the original inside its own try scope. Exceptions and cleanup then occur while the wrapper still controls execution, and callers still see a coroutine function.

import asyncio
import inspect
from collections.abc import Awaitable, Callable
from functools import wraps
from typing import ParamSpec, TypeVar


P = ParamSpec("P")
R = TypeVar("R")


def trace_async(func: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
    @wraps(func)
    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        print(f"start {func.__name__}")
        try:
            return await func(*args, **kwargs)
        finally:
            print(f"finish {func.__name__}")

    return wrapper


@trace_async
async def load_order(order_id: int) -> str:
    await asyncio.sleep(0)
    return f"order:{order_id}"


async def main():
    print(inspect.iscoroutinefunction(load_order))
    print(await load_order(42))


asyncio.run(main())

True
start load_order
finish load_order
order:42

If a regular def wrapper merely returns func(...), it returns an unexecuted coroutine object. Timing, exception handling, and cleanup in that wrapper cover coroutine creation rather than execution, and inspect.iscoroutinefunction() sees the outer layer as synchronous.

The finally suite runs on success, exceptions, and cancellation, but it shouldn’t swallow the exception or cancellation. To support both sync and async functions, inspect the target during decoration and generate two distinct wrappers instead of making a sync wrapper guess whether a returned value is awaitable.

Pitfalls

Forgetting functools.wraps

Fix: use @wraps(func) on every transparent layer that returns a plain function, then assert __name__, inspect.signature(), and __wrapped__. If the decorator intentionally changes the signature, publish that new signature explicitly instead of using wraps() to imply nothing changed.

Losing the return value or exception

Fix: a transparent wrapper returns the original result directly and catches only exceptions the policy explicitly handles. Test a non-None result, an expected exception, and failures in the wrapper’s own pre-call and post-call logic.

Treating definition-time effects as call-time behavior

Fix: keep only stable configuration validation and necessary registration at definition time. Acquire resources in a call or application startup path with an explicit lifetime, and test “import the module” separately from “call the function.”

Ordering multiple decorators by intuition

Fix: expand the stack into nested calls and write down each layer’s inputs, outputs, and exception boundary. Assert entry and exit events in a list, covering rejection, cache hits, success after one failure, and final failure.

Using one implementation for sync and async functions

Fix: branch with inspect.iscoroutinefunction() at decoration time and generate separate def and async def wrappers, or expose two explicit decorators. Test success, exceptions, and metadata on both paths, plus cancellation on the async path.

Sharing decorator-instance state accidentally

Fix: state whether data belongs to the decorator configuration, decorated function, instance, request, or call. Decorate at least two functions and interleave calls. If sharing isn’t the contract, create independent state during each decoration or use a class that exposes ownership more clearly.

Further reading

• Python glossary: decorator
• Python language reference: function definitions and decorator application
• Python functools.wraps()
• Python inspect.signature()
• Python typing.ParamSpec
• Python descriptor guide: functions and methods