How do decorators work and what are their pitfalls?

The @decorator syntax is sugar. Writing @log above def f is equivalent to f = log(f). Because the wrapper is a closure over the original function, it can run code before and after the call, retry it, cache results or register it.

import functools
import time

def timed(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        try:
            return func(*args, **kwargs)
        finally:
            elapsed = time.perf_counter() - start
            print(func.__name__, round(elapsed, 4))
    return wrapper

@timed
def work(n):
    return sum(range(n))

work(1000)

Variants and pitfalls

• Decorators with arguments need an extra outer function: @retry(times=3)
• Stacked decorators apply bottom-up: the closest decorator wraps first
• functools.lru_cache and cache are ready-made memoisation decorators
• Without wraps, introspection tools and debuggers see the wrapper signature

Decorators run at import time. A decorator that performs I/O, reads configuration or registers global state can make imports slow and order-dependent. They also obscure control flow, so use them for cross-cutting concerns such as logging, timing, authentication and caching rather than core business logic.