Decorators — Writing and Using Them

def loud(func):
    def wrapper():
        print("About to call the function...")
        func()
        print("...function finished.")
    return wrapper

def greet():
    print("Hello!")

greet = loud(greet)   # manually "decorating" greet by reassigning it
greet()
# About to call the function...
# Hello!
# ...function finished.

def loud(func):
    def wrapper():
        print("About to call the function...")
        func()
        print("...function finished.")
    return wrapper

@loud
def greet():
    print("Hello!")

# The line above is EXACTLY equivalent to:
#     def greet():
#         print("Hello!")
#     greet = loud(greet)

greet()   # identical output to Part 01

def loud(func):
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__} with args={args}, kwargs={kwargs}")
        result = func(*args, **kwargs)
        print(f"{func.__name__} returned {result!r}")
        return result       # critical — forget this and every decorated function silently returns None
    return wrapper

@loud
def add(a, b):
    return a + b

total = add(3, 4)
# Calling add with args=(3, 4), kwargs={}
# add returned 7
print(total)   # 7 — the real return value made it through

def loud(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

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

print(add.__name__)   # "wrapper" — WRONG! Should be "add"
print(add.__doc__)    # None — WRONG! The real docstring is lost

from functools import wraps

def loud(func):
    @wraps(func)              # copies __name__, __doc__, and more from func onto wrapper
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

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

print(add.__name__)   # "add" — correct
print(add.__doc__)    # "Add two numbers together." — correct

from functools import wraps
import time

def retry(times):                          # layer 1: takes the CONFIGURATION
    def decorator(func):                    # layer 2: takes the FUNCTION
        @wraps(func)
        def wrapper(*args, **kwargs):       # layer 3: runs on each CALL
            last_error = None
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except ConnectionError as e:
                    last_error = e
                    print(f"Attempt {attempt} failed, retrying...")
                    time.sleep(1)
            raise last_error
        return wrapper
    return decorator

@retry(times=3)
def fetch_data():
    ...

@decorator_a
@decorator_b
def my_function():
    ...

# Equivalent to:
# my_function = decorator_a(decorator_b(my_function))

from functools import wraps

def announce(label):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            print(f"[{label}] entering")
            result = func(*args, **kwargs)
            print(f"[{label}] exiting")
            return result
        return wrapper
    return decorator

@announce("OUTER")
@announce("INNER")
def task():
    print("  doing the actual work")

task()
# [OUTER] entering
# [INNER] entering
#   doing the actual work
# [INNER] exiting
# [OUTER] exiting

A function that looks up flight-route metadata from a slow internal database is called repeatedly with the same handful of popular routes, hundreds of times a minute, each call taking 200ms. An engineer reaches for Python's built-in functools.lru_cache decorator rather than hand-rolling a caching layer.

def get_route_info(origin, destination):
    return slow_database_lookup(origin, destination)   # ~200ms every time

from functools import lru_cache

@lru_cache(maxsize=256)
def get_route_info(origin, destination):
    return slow_database_lookup(origin, destination)

get_route_info("JFK", "LAX")   # ~200ms — cache miss, runs the real lookup
get_route_info("JFK", "LAX")   # ~0ms  — cache hit, returns the stored result instantly

Why this is exactly the kind of thing decorators are for

The caching logic — checking whether this exact combination of arguments was seen before, storing results, evicting the oldest entries once maxsize is reached — is completely generic and has nothing to do with flight routes specifically. lru_cache is itself just a decorator, written using exactly the pattern covered in this module, and applying it required changing precisely one line, with zero changes to get_route_info's own logic. This is the real payoff of decorators: cross-cutting behaviour (caching, logging, timing, retries, access control) added without touching the function's actual implementation at all.