{"title":"Decorators","description":"","content":"A decorator is a function that takes another function, wraps it in some extra behavior, and returns the wrapped version. The `@decorator` line above a `def` is Python's syntax for this pattern, but the mechanics are functions taking functions and returning functions. Decorators are used for timing, logging, caching, authentication, retries, and registering routes in a web framework. This lesson covers the basic shape, the `@` sugar, decorators that take their own arguments, the `functools.wraps` helper that keeps the wrapped function's identity intact, stacking, common patterns, and a few performance notes.\n\n---\n\n# What a Decorator Does\n\nA decorator is a function that takes a function as input and returns a function as output. That sentence is the whole idea. Everything else is mechanics.\n\nConsider timing an order-pricing function. Placing `time.perf_counter()` calls around every call site is noisy and easy to forget. A decorator allows the timing logic to be written once and applied to any function with one line.\n\n\n```python\nimport time\n\ndef time_it(func):\n def wrapper(*args, **kwargs):\n start = time.perf_counter()\n result = func(*args, **kwargs)\n elapsed = time.perf_counter() - start\n print(f\"{func.__name__} took {elapsed:.6f}s\")\n return result\n return wrapper\n\ndef price_order(quantity, unit_price, discount):\n return quantity * unit_price * (1 - discount)\n\nprice_order = time_it(price_order)\nprint(price_order(3, 29.99, 0.10))\n```\n\n\nThree things happened. `time_it(price_order)` took the original function as input. It defined a new function `wrapper` that does the timing around a call to the original. It returned `wrapper`. The name `price_order` was then rebound to point at the wrapper instead of the original.\n\nThe next call, `price_order(3, 29.99, 0.10)`, runs the wrapper. The wrapper records the start time, calls the real pricing function (which it captured as `func`), records the end time, prints the elapsed time, and returns the result. From the caller's point of view, `price_order` still computes an order price. From the inside, every call now also reports its timing.\n\nThe pattern is common enough that Python has dedicated syntax for it.\n\n---\n\n# The `@decorator` Syntax\n\nWriting `price_order = time_it(price_order)` after every definition is repetitive. Python provides the `@` syntax to do the same rebinding inline:\n\n\n```python\nimport time\n\ndef time_it(func):\n def wrapper(*args, **kwargs):\n start = time.perf_counter()\n result = func(*args, **kwargs)\n elapsed = time.perf_counter() - start\n print(f\"{func.__name__} took {elapsed:.6f}s\")\n return result\n return wrapper\n\n@time_it\ndef price_order(quantity, unit_price, discount):\n return quantity * unit_price * (1 - discount)\n\nprint(price_order(3, 29.99, 0.10))\n```\n\n\nThe `@time_it` line above the `def` is syntactic sugar. It means the same thing as writing `price_order = time_it(price_order)` after the definition. Python sees the `@`, runs the decorator on the function it precedes, and rebinds the name.\n\n\n```mermaid\nflowchart LR\n Source[\"@time_it
def price_order(...): ...\"]:::cyan\n Step1[\"1. Python defines
price_order normally\"]:::orange\n Step2[\"2. Python calls
time_it(price_order)\"]:::orange\n Step3[\"3. time_it returns
wrapper function\"]:::green\n Step4[\"4. Python rebinds
price_order = wrapper\"]:::teal\n\n Source --> Step1 --> Step2 --> Step3 --> Step4\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe decorator runs **once**, at the time the function is defined. The wrapper it returns runs **every time** the decorated function is called. That distinction matters: any setup the decorator does (parsing config, opening a connection, allocating a cache) happens once at definition time, while the wrapper logic happens on every call.\n\nWhat is `func` bound to inside the wrapper after `time_it` has returned? The original, undecorated function. The wrapper captured it as a free variable (a closure cell). When the wrapper runs, it can still call `func` and get the original behavior, even though the name `price_order` now points at the wrapper.\n\n---\n\n# A Logging Decorator\n\nA second example shows the same shape applied to a different problem. Logging is a common reason to write a decorator: every call to a particular function should record its arguments and result somewhere.\n\n\n```python\ndef log_calls(func):\n def wrapper(*args, **kwargs):\n print(f\"calling {func.__name__}({args}, {kwargs})\")\n result = func(*args, **kwargs)\n print(f\" -> {result!r}\")\n return result\n return wrapper\n\n@log_calls\ndef add_to_cart(customer, product, quantity=1):\n return f\"{quantity}x {product} added to {customer}'s cart\"\n\nadd_to_cart(\"alice\", \"Wireless Mouse\")\nadd_to_cart(\"bob\", \"USB Cable\", quantity=3)\n```\n\n\nThe decorator has the same shape as the timing one: take a function, define a wrapper that runs extra code around a call to the original, return the wrapper. The wrapper signature is always `(*args, **kwargs)` because the decorated function's signature isn't known in advance, and the wrapper must forward whatever the caller passes.\n\nThe `*args` and `**kwargs` pattern makes decorators reusable. The same `log_calls` decorator can wrap a function that takes one argument, three arguments, or any other shape, because the wrapper accepts everything and forwards everything.\n\nThe output shows that the wrapper's `print` calls happen before and after the original function runs. The wrapped function's behavior is unchanged; the decorator sandwiches extra code around it.\n\nEach call through a decorator adds one extra function call (the wrapper) and the overhead of building `args` and `kwargs`. For most code this is nanoseconds and invisible. For a function called millions of times in a tight loop, decorators can become a measurable cost; profile before assuming so.\n\n---\n\n# Preserving Metadata with `functools.wraps`\n\nThe decorators above have a problem: the wrapper takes over the original function's identity. The name and docstring change accordingly:\n\n\n```python\ndef time_it(func):\n def wrapper(*args, **kwargs):\n return func(*args, **kwargs)\n return wrapper\n\n@time_it\ndef price_order(quantity, unit_price, discount):\n \"\"\"Compute the price of an order.\"\"\"\n return quantity * unit_price * (1 - discount)\n\nprint(price_order.__name__)\nprint(price_order.__doc__)\n```\n\n\nThe name `price_order.__name__` is now `\"wrapper\"`, because `price_order` is bound to the wrapper function and the wrapper was named `wrapper`. The docstring is gone for the same reason: the wrapper has no docstring of its own. Tools that read `__name__` (debuggers, logging, traceback printers) and tools that read `__doc__` (help systems, doc generators) get the wrong information.\n\nThe fix is `functools.wraps`, a decorator-for-decorators that copies the original function's metadata onto the wrapper. Apply it inside the decorator, to the wrapper:\n\n\n```python\nfrom functools import wraps\nimport time\n\ndef time_it(func):\n @wraps(func)\n def wrapper(*args, **kwargs):\n start = time.perf_counter()\n result = func(*args, **kwargs)\n elapsed = time.perf_counter() - start\n print(f\"{func.__name__} took {elapsed:.6f}s\")\n return result\n return wrapper\n\n@time_it\ndef price_order(quantity, unit_price, discount):\n \"\"\"Compute the price of an order.\"\"\"\n return quantity * unit_price * (1 - discount)\n\nprint(price_order.__name__)\nprint(price_order.__doc__)\n```\n\n\n`@wraps(func)` copies `func.__name__`, `func.__doc__`, `func.__module__`, `func.__qualname__`, `func.__annotations__`, and a few other attributes onto the wrapper. From the outside, the wrapper now looks like the original. Tools and humans both see the right name and docstring.\n\nThe rule: **always use `@wraps(func)` on the wrapper inside a decorator**. There's no reason not to, and forgetting it produces subtle bugs that show up only when something inspects the function's metadata.\n\n\n```python\nfrom functools import wraps\n\ndef log_calls(func):\n @wraps(func)\n def wrapper(*args, **kwargs):\n print(f\"calling {func.__name__}\")\n return func(*args, **kwargs)\n return wrapper\n\n@log_calls\ndef cart_total(prices):\n \"\"\"Sum the prices in the cart.\"\"\"\n return sum(prices)\n\nhelp(cart_total)\n```\n\n\n`help` reads `__name__` and `__doc__`, and because of `@wraps`, it sees the right function. Without `@wraps`, `help(cart_total)` would show `Help on function wrapper`, which is wrong and confusing.\n\n---\n\n# Decorators with Arguments\n\nThe decorators so far take only the function. Some decorators need configuration: a retry decorator that takes a count, a cache decorator that takes a maximum size, a timing decorator that takes a label. The way to do this is to write a **decorator factory**: a function that takes the configuration and returns a real decorator.\n\n\n```python\nfrom functools import wraps\n\ndef retry(times):\n def decorator(func):\n @wraps(func)\n def wrapper(*args, **kwargs):\n for attempt in range(1, times + 1):\n try:\n return func(*args, **kwargs)\n except Exception as exc:\n print(f\"attempt {attempt} failed: {exc}\")\n raise RuntimeError(f\"{func.__name__} failed after {times} attempts\")\n return wrapper\n return decorator\n\n@retry(times=3)\ndef charge_card(amount):\n raise ConnectionError(\"payment gateway timeout\")\n\ntry:\n charge_card(50.00)\nexcept RuntimeError as exc:\n print(exc)\n```\n\n\nThree layers of functions. `retry(times=3)` is the outermost call; it captures `times` and returns the real decorator. That decorator takes `charge_card` and returns the wrapper. The wrapper does the retry loop, calling the original function up to `times` times.\n\nThe shape `@retry(times=3)` is now a function call, not a bare name. Python evaluates `retry(times=3)` first, which produces a decorator. Then it applies that decorator to `charge_card` like any other decorator. The difference from a plain `@time_it` (no parentheses) is that this one has parentheses with arguments inside.\n\n\n```mermaid\nflowchart LR\n Source[\"@retry(times=3)
def charge_card(...): ...\"]:::cyan\n Step1[\"1. retry(times=3) runs\"]:::orange\n Step2[\"2. retry returns decorator
(closure over times)\"]:::orange\n Step3[\"3. decorator(charge_card) runs\"]:::green\n Step4[\"4. decorator returns wrapper
(closure over func + times)\"]:::green\n Step5[\"5. charge_card = wrapper\"]:::teal\n\n Source --> Step1 --> Step2 --> Step3 --> Step4 --> Step5\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe pattern is \"factory returns a decorator, decorator returns a wrapper\". Every decorator with arguments follows this shape.\n\nA more realistic version uses a real delay between retries:\n\n\n```python\nimport time\nfrom functools import wraps\n\ndef retry(times=3, delay=1.0):\n def decorator(func):\n @wraps(func)\n def wrapper(*args, **kwargs):\n for attempt in range(1, times + 1):\n try:\n return func(*args, **kwargs)\n except Exception as exc:\n print(f\"attempt {attempt}/{times} failed: {exc}\")\n if attempt < times:\n time.sleep(delay)\n raise RuntimeError(f\"{func.__name__} failed after {times} attempts\")\n return wrapper\n return decorator\n\n@retry(times=2, delay=0.01)\ndef fetch_inventory(product_id):\n raise ConnectionError(\"inventory service unavailable\")\n\ntry:\n fetch_inventory(\"SKU-42\")\nexcept RuntimeError as exc:\n print(exc)\n```\n\n\nThe factory takes two arguments with defaults; the decorator captures both and uses them inside the wrapper. The shape is the same; the wrapper has more to do.\n\nOne technique sometimes used: making the parentheses optional, so `@retry` and `@retry(times=3)` both work. It's occasionally useful, but it makes the decorator harder to read. The straightforward approach (always require parentheses for configurable decorators) is more common.\n\n---\n\n# Stacking Decorators\n\nMore than one decorator can be applied to the same function. The order matters, and the rule is: decorators apply **from bottom up**, meaning the one closest to the `def` runs first, then the one above it, and so on.\n\n\n```python\nfrom functools import wraps\n\ndef log_calls(func):\n @wraps(func)\n def wrapper(*args, **kwargs):\n print(f\"[log] calling {func.__name__}\")\n return func(*args, **kwargs)\n return wrapper\n\ndef add_exclamation(func):\n @wraps(func)\n def wrapper(*args, **kwargs):\n return func(*args, **kwargs) + \"!\"\n return wrapper\n\n@log_calls\n@add_exclamation\ndef greet(name):\n return f\"Hello, {name}\"\n\nprint(greet(\"alice\"))\n```\n\n\nRead the stack from bottom to top. `@add_exclamation` is closest to the `def`, so Python applies it first: `greet = add_exclamation(greet)`. Then `@log_calls` applies to the result: `greet = log_calls(greet)`. The final `greet` is `log_calls`'s wrapper, which wraps `add_exclamation`'s wrapper, which wraps the real `greet`.\n\nCalling `greet(\"alice\")` flows control through the layers from outside in. First the `log_calls` wrapper runs and prints `[log] calling greet`. Then it calls the next layer, the `add_exclamation` wrapper. That wrapper calls the real `greet`, which returns `\"Hello, alice\"`, then appends `\"!\"`, returning `\"Hello, alice!\"`. Control returns to `log_calls`, which returns the same value to the caller.\n\nSwap the order and the behavior changes:\n\n\n```python\n@add_exclamation\n@log_calls\ndef greet(name):\n return f\"Hello, {name}\"\n\nprint(greet(\"alice\"))\n```\n\n\nSame output in this case, but the call order is different. Now `log_calls` is the inner wrapper and `add_exclamation` is the outer one. When `greet(\"alice\")` runs, `add_exclamation`'s wrapper calls `log_calls`'s wrapper, which prints the log line and then calls the real function. The `[log] calling greet` happens **after** entering `add_exclamation` but **before** entering the real function.\n\nThe order matters more when the decorators do non-commutative things. A `@cache` outside a `@log_calls` means cached results don't get logged; a `@log_calls` outside a `@cache` means every call gets logged, even cached ones. Choose the order based on the desired behavior.\n\n\n```mermaid\nflowchart TB\n Call[\"greet('alice')\"]:::cyan\n Outer[\"log_calls wrapper
(outermost)\"]:::orange\n Middle[\"add_exclamation wrapper
(middle)\"]:::orange\n Inner[\"original greet
(innermost)\"]:::green\n Return[\"'Hello, alice!'\"]:::teal\n\n Call -->|\"enters\"| Outer\n Outer -->|\"calls\"| Middle\n Middle -->|\"calls\"| Inner\n Inner -->|\"returns 'Hello, alice'\"| Middle\n Middle -->|\"returns 'Hello, alice!'\"| Outer\n Outer -->|\"returns\"| Return\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram shows the call cycle for the first stack (`@log_calls` on top). Each wrapper passes through to the next layer, the innermost function runs, and the result bubbles back out, picking up modifications on the way.\n\n---\n\n# Common Decorator Patterns\n\nSome decorators appear frequently enough that recognizing them is part of reading Python. The most common shapes follow, in compact form.\n\n### Caching with `functools.lru_cache`\n\nA cache decorator stores the results of a function so repeat calls with the same arguments don't recompute. Python's `functools.lru_cache` is the standard implementation:\n\n\n```python\nfrom functools import lru_cache\n\n@lru_cache(maxsize=128)\ndef fibonacci(n):\n if n < 2:\n return n\n return fibonacci(n - 1) + fibonacci(n - 2)\n\nprint(fibonacci(30))\nprint(fibonacci.cache_info())\n```\n\n\nWithout the cache, `fibonacci(30)` would make millions of recursive calls. With it, each unique argument is computed once and reused. `cache_info()` shows the hit and miss counts. One of the most useful real-world decorators (`lru_cache`) ships in the standard library.\n\n### Authorization Checks\n\nWeb frameworks and APIs often use a decorator to check that the current user is allowed to call a function. The wrapper checks a permission and either calls the wrapped function or raises an error.\n\n\n```python\nfrom functools import wraps\n\ndef admin_only(func):\n @wraps(func)\n def wrapper(user, *args, **kwargs):\n if user.get(\"role\") != \"admin\":\n raise PermissionError(f\"{user['name']} is not an admin\")\n return func(user, *args, **kwargs)\n return wrapper\n\n@admin_only\ndef delete_product(user, product_id):\n return f\"{user['name']} deleted {product_id}\"\n\nalice = {\"name\": \"alice\", \"role\": \"admin\"}\nbob = {\"name\": \"bob\", \"role\": \"customer\"}\n\nprint(delete_product(alice, \"SKU-42\"))\n\ntry:\n delete_product(bob, \"SKU-42\")\nexcept PermissionError as exc:\n print(exc)\n```\n\n\nThe wrapper checks the user's role before calling the real function. If the check fails, the original function never runs. This is the shape underlying most web framework `@login_required` and `@requires_permission` decorators.\n\n### Input Validation\n\nA decorator can validate arguments before they reach the function, raising a clear error if something is wrong.\n\n\n```python\nfrom functools import wraps\n\ndef validate_positive(func):\n @wraps(func)\n def wrapper(*args, **kwargs):\n for value in list(args) + list(kwargs.values()):\n if isinstance(value, (int, float)) and value < 0:\n raise ValueError(f\"{func.__name__} received negative value: {value}\")\n return func(*args, **kwargs)\n return wrapper\n\n@validate_positive\ndef apply_discount(price, percent):\n return price * (1 - percent / 100)\n\nprint(apply_discount(100, 10))\n\ntry:\n apply_discount(100, -10)\nexcept ValueError as exc:\n print(exc)\n```\n\n\nThe validation logic lives in one place and applies to any function that needs it. The wrapped function doesn't need to know that validation happens; it runs with the assurance that its arguments are sane.\n\n### Registering Functions\n\nA decorator can have a side effect: registering the decorated function in a list, dict, or other registry. The function is still returned unchanged, so it works normally, but the registry now knows about it.\n\n\n```python\nhandlers = {}\n\ndef handler(event_type):\n def decorator(func):\n handlers[event_type] = func\n return func\n return decorator\n\n@handler(\"order_placed\")\ndef on_order_placed(order):\n return f\"sending confirmation for {order['id']}\"\n\n@handler(\"order_shipped\")\ndef on_order_shipped(order):\n return f\"sending shipping notice for {order['id']}\"\n\nprint(handlers)\nprint(handlers[\"order_placed\"]({\"id\": \"ORD-42\"}))\n```\n\n\nThe decorator doesn't wrap the function in this case; it stores a reference and returns the original. Frameworks like Flask use this pattern for route registration: `@app.route(\"/cart\")` doesn't change the function; it tells the framework \"when a request comes for `/cart`, call this function\".\n\nThe exact memory address in the function repr varies between runs; the shape is what matters.\n\n---\n\n# Class-Based Decorators (Brief)\n\nA decorator doesn't have to be a function. Any callable will do, and the most common alternative is a class with a `__call__` method. The class version is useful when the decorator has state that should persist across calls, or when methods on the decorator itself are needed.\n\n\n```python\nfrom functools import wraps\n\nclass CountCalls:\n def __init__(self, func):\n wraps(func)(self)\n self.func = func\n self.count = 0\n\n def __call__(self, *args, **kwargs):\n self.count += 1\n return self.func(*args, **kwargs)\n\n@CountCalls\ndef cart_total(prices):\n return sum(prices)\n\ncart_total([29.99, 14.99])\ncart_total([9.99])\ncart_total([19.99, 4.99, 14.99])\n\nprint(f\"cart_total was called {cart_total.count} times\")\n```\n\n\n`@CountCalls` rebinds `cart_total` to an instance of the `CountCalls` class. Each call goes through `__call__`, which increments the counter and forwards to the real function. The `count` attribute is accessible from outside, which would be awkward with a closure-based decorator.\n\nFor now, the takeaway is that a decorator is anything callable that takes and returns a function, and a class with `__call__` is one shape that fits.\n\n---\n\n# Performance Considerations\n\nDecorators have a real but usually negligible runtime cost. Three sources contribute:\n\nThe first is the **extra function call per invocation**. The wrapper is itself a function, so every call to the decorated function does at least two function calls instead of one. On modern Python, that's tens to hundreds of nanoseconds. For most code this is invisible.\n\nThe second is **building `args` and `kwargs`**. The standard `def wrapper(*args, **kwargs)` pattern builds a new tuple and a new dict for every call, then unpacks them when calling the underlying function. Usually invisible, but in a tight loop calling a decorated function millions of times, this can dominate.\n\nThe third is **whatever the wrapper itself does**. A logging decorator that does I/O on every call is slow because logging is slow, not because decorators are slow. A caching decorator that hashes complex arguments to look them up is slow because hashing complex arguments is slow.\n\n\n```python\nimport time\nfrom functools import wraps\n\ndef pass_through(func):\n @wraps(func)\n def wrapper(*args, **kwargs):\n return func(*args, **kwargs)\n return wrapper\n\ndef add(a, b):\n return a + b\n\n@pass_through\ndef add_decorated(a, b):\n return a + b\n\n# Time both.\nn = 1_000_000\n\nstart = time.perf_counter()\nfor _ in range(n):\n add(1, 2)\nplain = time.perf_counter() - start\n\nstart = time.perf_counter()\nfor _ in range(n):\n add_decorated(1, 2)\ndecorated = time.perf_counter() - start\n\nprint(f\"plain: {plain:.3f}s\")\nprint(f\"decorated: {decorated:.3f}s\")\nprint(f\"overhead per call: {(decorated - plain) / n * 1e9:.0f} ns\")\n```\n\n\nThe exact numbers depend on the machine and Python version; the shape is what matters. Per-call overhead is in the tens of nanoseconds for a pass-through wrapper. That's roughly the time it takes a modern CPU to execute a few hundred instructions, far below the threshold where any normal program would notice.\n\nA pass-through decorator typically adds 50 to 150 ns per call on modern Python. If the decorated function does any real work (a database query, an HTTP request, a hash, a list iteration over more than a handful of elements), the decorator overhead is rounding error. Optimize away from decorators only when measurement says the wrapper is a bottleneck.\n\n---\n\n# Real Built-In Decorators\n\nThree decorators appear in everyday Python code, all from the standard library or built-ins. Knowing what they do makes a lot of real code easier to read.\n\n**`@property`** turns a method into a read-only attribute. `obj.some_property` runs the method and returns the result, as if reading an attribute.\n\n\n```python\nclass Cart:\n def __init__(self, items):\n self.items = items\n\n @property\n def total(self):\n return sum(item[\"price\"] for item in self.items)\n\ncart = Cart([{\"name\": \"Mouse\", \"price\": 29.99}, {\"name\": \"Cable\", \"price\": 4.99}])\nprint(cart.total)\n```\n\n\n`cart.total` is written like an attribute access (no parentheses) but actually runs the method. `@property` is a decorator like any other.\n\n**`@staticmethod`** marks a method that doesn't depend on the instance or the class. It's used inside class bodies and doesn't receive `self`.\n\n\n```python\nclass Pricing:\n @staticmethod\n def with_tax(price, rate):\n return price * (1 + rate)\n\nprint(Pricing.with_tax(100, 0.08))\n```\n\n\nNo `self` parameter, no instance needed. The decorator changes how Python treats the function inside the class.\n\n**`@cache`** (Python 3.9+) and **`@lru_cache`** memoize a function's results. The functools lesson covers them in detail.\n\n\n```python\nfrom functools import cache\n\n@cache\ndef slow_lookup(product_id):\n print(f\"computing for {product_id}\")\n return product_id.upper()\n\nprint(slow_lookup(\"sku-1\"))\nprint(slow_lookup(\"sku-1\"))\nprint(slow_lookup(\"sku-2\"))\n```\n\n\nThe second call to `slow_lookup(\"sku-1\")` doesn't print \"computing\"; the cache returned the previous result. The function only runs once per unique argument.\n\nThese three decorators (and a few others like `@classmethod` and `@dataclass`) cover most of the decorator usage in real code. Once the mechanism is clear, recognizing them is a matter of knowing what each one does.","pageType":"python"}

Decorators

Get Premium