CS Fundamentals Trainer · Guides

Python decorators, generators and async

Decorators built from closures, functools.wraps and lru_cache (and the method pitfall), lazy generator pipelines, coroutines and the event loop, gather against sequential await, cancellation, TaskGroup and never blocking the loop.

17 min read

Decorators, generators and async/await look like three unrelated features, and they share one idea: a function is a value, and a function can be suspended. A decorator receives a function and returns another one. A generator is a function that pauses at yield and keeps its local variables until it is asked to continue. A coroutine is the same machinery pointed at waiting for I/O. If you understand the first two, asyncio stops being magic. This guide builds each from the ground up and measures the parts that matter (the cost of a wrapper, what lru_cache buys and what it keeps alive, how lazy pipelines behave, what concurrency in asyncio really gives you). It assumes how Python works; the scripts, run on CPython 3.13, are in the appendix. For performance choices between threads, processes and asyncio, see Python performance and concurrency.

1. Decorators

A decorator is a function that takes a function

def shout(fn):
    def wrapper(*args, **kwargs):
        return fn(*args, **kwargs).upper()
    return wrapper

@shout
def greet(name):
    return f"hello {name}"

The @shout line is exactly greet = shout(greet). The name greet now refers to wrapper, which closes over the original function (see closures in how Python works). greet("ana") returned HELLO ANA.

Three facts explain nearly every decorator bug:

Always use functools.wraps

Without it, greet.__name__ was 'wrapper' and greet.__doc__ was None, which breaks tracebacks, documentation tools, and anything that inspects the function. Decorating the wrapper with @functools.wraps(fn) copies the metadata and also sets __wrapped__, which points back to the original (greet2.__wrapped__("x") returned hello x, unwrapped).

Decorators with arguments

@retry(3) is a call that must return a decorator, so there are three nested levels: the factory takes the argument, the decorator takes the function, the wrapper takes the call:

def retry(times):
    def deco(fn):
        @functools.wraps(fn)
        def wrapper(*a, **k):
            for attempt in range(1, times + 1):
                try:
                    return fn(*a, **k)
                except ValueError:
                    if attempt == times:
                        raise
        return wrapper
    return deco

A function that failed twice and succeeded on the third call returned ok, with the two failures logged. (Retrying belongs together with a delay, a limit on what you retry, and idempotent operations: see resilience patterns.)

A class can also be a decorator, by implementing __call__; this is convenient when the wrapper needs state. A Count class that stored a call counter reported 2 after two calls. Use functools.update_wrapper there for the same metadata copy. functools.partial is related but different: it pre-fills arguments (partial(int, base=2)("101") gave 5).

What a wrapper costs

A wrapper is an extra Python call on every invocation. One million calls took 73 ms for a plain function and 177 ms when it was wrapped by a pass-through decorator: about 100 ns extra per call. That is nothing next to a database query and noticeable in a function called tens of millions of times in a tight loop, which is when you would profile first.

functools.lru_cache

A cache decorator stores results by arguments. fib(27) computed recursively took 40 ms without a cache and 0.05 ms with @functools.lru_cache(maxsize=None); its cache_info() reported hits=25, misses=28, because each value was computed once. Four rules keep it from backfiring:

For results that must expire (a remote call, a database value), use a cache with a time limit; see caching strategies.

Common uses of decorators beyond these: timing and logging, authorisation checks, registering routes or handlers (@app.route), @staticmethod, @classmethod, @property and @dataclass, which are all decorators. For more than two or three levels of nesting, a class or a context manager is often clearer.

2. Generators

A function that pauses

A function containing yield is a generator function: calling it does not run the body; it returns a generator object. Each next() runs until the next yield, hands back the value, and freezes the local variables and the position until the next next(). When the body finishes, StopIteration is raised.

Generators can also receive values. In this accumulator, send(x) resumes the paused yield with x as its value:

def accumulator():
    total = 0
    while True:
        x = yield total
        if x is None: break
        total += x

After priming it with next(g), g.send(10), g.send(5) and g.send(1) returned 10, 15 and 16. That two-way channel is the idea coroutines are built on (section 3).

Pipelines are lazy

Chaining generators builds a pipeline in which each value flows through all stages one at a time, and nothing is computed until someone asks. I built read_lines() (printing each line it produces), then nonempty() and lengths() stages. Asking for the first result printed only produced 'a' and returned 1: the source had read one line, not five. This is how you process a file larger than memory, or stop early without paying for the rest. Measured in how Python works: summing 10 million squares needed about 409 MB with a list and 1.4 KB with a generator.

Delegation and cleanup

Remember from the previous guide that a generator is one-shot: iterating it a second time yields nothing. If you need to loop twice, keep a list or call the generator function again.

3. async and await

Coroutines

A function defined with async def is a coroutine function: calling it returns a coroutine object and runs nothing. I called work("a", 0.1) and got an object of type coroutine. A coroutine is a generator-like object whose pauses happen at await. Something has to drive it: the event loop, which runs coroutines on one thread and, whenever one awaits something that is not ready (a timer, a socket), switches to another.

asyncio.run(main()) starts a loop and runs one top-level coroutine until it finishes.

Await in sequence is not concurrent

The most common mistake is writing await one after another and expecting overlap. Three 0.2 s waits:

How they were runTotal time
await a(); await b(); await c()0.60 s
await asyncio.gather(a(), b(), c())0.20 s

await means "wait here until this finishes". To overlap, start the work first (gather, create_task, or a TaskGroup) and await the group.

Forgetting to await

If you call a coroutine function and never await the result, nothing happens, except that Python warns when the object is destroyed: coroutine 'work' was never awaited. Treat that warning as a bug.

Timeouts, cancellation and groups

The rule that keeps asyncio fast

The loop runs on one thread, so a coroutine must never block. A time.sleep(0.2), a synchronous HTTP call, a database driver that is not async, or a big computation inside a coroutine freezes every other task for the whole duration. In the previous guide, five tasks calling time.sleep(0.2) took 1.00 s instead of 0.2 s. For blocking calls use await asyncio.to_thread(fn, ...) (a thread), or a process pool for CPU work, or an async library.

And asyncio does not make computing faster: it makes waiting concurrent. It shines for many connections that spend most of their time idle, such as servers, crawlers and API clients (compare the web crawler design).

Threads or async?

Threadsasyncio
Switchingthe OS preempts at any timeonly at await
Racespossible anywhere (use locks)only across await points, so far fewer
Librariesany blocking library worksneeds async-aware libraries
Scalethousands of threads is heavytens of thousands of tasks is routine
Debuggingharder to reason aboutone thread, easier to reason about, but "colouring" spreads: callers of async functions must be async

4. Common mistakes

5. Questions interviewers like to ask

"What does @decorator do?"

It is shorthand for f = decorator(f) at definition time. The decorator returns a replacement, usually a wrapper that closes over the original.

"Why use functools.wraps?"

To copy the wrapped function's name, docstring and other metadata onto the wrapper, and to expose the original as __wrapped__.

"How would you write a decorator that takes arguments?"

A function that takes the arguments and returns the real decorator, which returns the wrapper: three nested functions (or a class with __init__ and __call__).

"What is the difference between a generator and a list?"

A generator produces values lazily, one at a time, in constant memory, and can be consumed once. A list stores all values and supports indexing and reuse.

"How does yield relate to async/await?"

Both suspend a function and resume it later with its local state intact. Coroutines are driven by an event loop that resumes them when what they awaited is ready. In older Python, coroutines were literally generators with yield from.

"How do you run things concurrently in asyncio?"

Start them together with asyncio.gather, create_task or a TaskGroup, then await the group. Awaiting one after another is sequential.

"What happens if you call a blocking function inside a coroutine?"

The whole event loop stops until it returns, so all other tasks stall. Use an async library, asyncio.to_thread or a process pool.

"Why might lru_cache cause a memory leak?"

On a method, self becomes part of the key, so the cache keeps every instance alive; with maxsize=None it also grows without bound.

6. Things to mention in an interview

Quick recap

Appendix: the experiment code

Python 3.13 (CPython), standard library only (TaskGroup and except* need 3.11 or later). Run each file with python3 file.py. Timings vary by machine; the behaviours and the order of events should be the same.

decorators.py: decorators, wraps, arguments, stacking, lru_cache, class decorators and the wrapper cost:

import functools, time, timeit

# 1. a decorator is just f = deco(f)
def shout(fn):
    def wrapper(*a, **k):
        return fn(*a, **k).upper()
    return wrapper
@shout
def greet(name):
    """Say hello."""
    return f"hello {name}"
print(greet("ana"), "| name:", greet.__name__, "| doc:", greet.__doc__)

def shout2(fn):
    @functools.wraps(fn)
    def wrapper(*a, **k): return fn(*a, **k).upper()
    return wrapper
@shout2
def greet2(name):
    """Say hello."""
    return f"hello {name}"
print("with wraps:", greet2.__name__, "|", greet2.__doc__, "| original:", greet2.__wrapped__("x"))

# 2. decorator with arguments = a function that returns a decorator
def retry(times):
    def deco(fn):
        @functools.wraps(fn)
        def wrapper(*a, **k):
            for attempt in range(1, times + 1):
                try: return fn(*a, **k)
                except ValueError as e:
                    print(f"  attempt {attempt} failed: {e}")
                    if attempt == times: raise
        return wrapper
    return deco
calls = {"n": 0}
@retry(3)
def flaky():
    calls["n"] += 1
    if calls["n"] < 3: raise ValueError("boom")
    return "ok"
print("retry result:", flaky())

# 3. decorators run at definition time, wrappers at call time
order = []
def trace(fn):
    order.append(f"decorated {fn.__name__}")
    def w(*a, **k): order.append(f"called {fn.__name__}"); return fn(*a, **k)
    return w
@trace
def a(): pass
order.append("after def"); a()
print(order)

# 4. stacking: bottom decorator applies first
def tag(name):
    def d(fn):
        def w(): return f"<{name}>{fn()}</{name}>"
        return w
    return d
@tag("b")
@tag("i")
def text(): return "x"
print(text())

# 5. lru_cache
@functools.lru_cache(maxsize=None)
def fib(n): return n if n < 2 else fib(n - 1) + fib(n - 2)
def fib_plain(n): return n if n < 2 else fib_plain(n - 1) + fib_plain(n - 2)
t = time.perf_counter(); fib_plain(27); plain = time.perf_counter() - t
t = time.perf_counter(); fib(27); cached = time.perf_counter() - t
print(f"fib(27) plain {plain*1e3:.0f} ms | lru_cache {cached*1e3:.2f} ms | {fib.cache_info()}")
@functools.lru_cache(maxsize=None)
def f(x): return x
try: f([1])
except TypeError as e: print("unhashable arg:", e)
# cache on a method keeps instances alive
import gc, weakref
class S:
    @functools.lru_cache(maxsize=None)
    def m(self): return 1
s = S(); s.m(); r = weakref.ref(s); del s; gc.collect()
print("instance still alive after del (lru_cache on method):", r() is not None)

# 6. partial, class-based decorator
from functools import partial
p2 = partial(int, base=2); print("partial:", p2("101"))
class Count:
    def __init__(self, fn): self.fn = fn; self.n = 0; functools.update_wrapper(self, fn)
    def __call__(self, *a, **k): self.n += 1; return self.fn(*a, **k)
@Count
def hi(): return "hi"
hi(); hi(); print("class decorator calls:", hi.n)

# 7. cost of a wrapper
def plain_fn(x): return x
@shout2
def w_fn(x): return str(x)
def deco_id(fn):
    @functools.wraps(fn)
    def w(*a, **k): return fn(*a, **k)
    return w
wrapped = deco_id(plain_fn)
n = 1_000_000
print(f"1M calls: plain {timeit.timeit(lambda: plain_fn(1), number=n)*1e3:.0f} ms, wrapped {timeit.timeit(lambda: wrapped(1), number=n)*1e3:.0f} ms")

gen_async.py: generators, pipelines, send, yield from, contextmanager, coroutines, gather, cancellation, TaskGroup and a semaphore:

import asyncio, time, inspect
from contextlib import contextmanager

# generators: send, close, yield from, pipeline
def accumulator():
    total = 0
    while True:
        x = yield total
        if x is None: break
        total += x
g = accumulator(); next(g)
print("send:", g.send(10), g.send(5), g.send(1))
def read_lines():
    for line in ["a", "bb", "", "ccc", "dd"]:
        print("  produced", repr(line)); yield line
def nonempty(src):
    for x in src:
        if x: yield x
def lengths(src):
    for x in src: yield len(x)
it = lengths(nonempty(read_lines()))
print("first result:", next(it))                       # only reads what it needs
def inner(): yield 1; yield 2; return "done"
def outer():
    r = yield from inner(); yield r
print("yield from:", list(outer()))
def cleanup():
    try: yield 1; yield 2
    finally: print("  cleanup ran")
c = cleanup(); next(c); c.close()

@contextmanager
def timer(label):
    t = time.perf_counter()
    try: yield
    finally: print(f"{label}: {1e3*(time.perf_counter()-t):.0f} ms")
with timer("contextmanager"): time.sleep(0.05)

# coroutines
async def work(name, delay):
    await asyncio.sleep(delay); return name
co = work("a", 0.1)
print("calling an async def gives:", type(co).__name__, "| nothing ran yet")
co.close()
async def seq():
    t = time.perf_counter()
    await work("a", .2); await work("b", .2); await work("c", .2)
    return time.perf_counter() - t
async def conc():
    t = time.perf_counter()
    await asyncio.gather(work("a", .2), work("b", .2), work("c", .2))
    return time.perf_counter() - t
print(f"awaited one after another: {asyncio.run(seq()):.2f} s | gather: {asyncio.run(conc()):.2f} s")

# forgotten await
async def forgot():
    work("x", 0.01)          # coroutine created, never awaited
import warnings
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always"); asyncio.run(forgot()); import gc; gc.collect()
print("forgotten await warns:", [str(x.message) for x in w][:1])

# timeouts and cancellation
async def slow(): await asyncio.sleep(5)
async def with_timeout():
    try: await asyncio.wait_for(slow(), 0.1)
    except asyncio.TimeoutError: return "timed out after 0.1 s"
print(asyncio.run(with_timeout()))
async def cancel_demo():
    async def task():
        try: await asyncio.sleep(5)
        except asyncio.CancelledError: print("  task saw CancelledError"); raise
    t = asyncio.create_task(task()); await asyncio.sleep(0.05); t.cancel()
    try: await t
    except asyncio.CancelledError: return f"cancelled={t.cancelled()}"
print(asyncio.run(cancel_demo()))

# TaskGroup (3.11+): one failure cancels the siblings
async def tg():
    done = []
    async def ok(): await asyncio.sleep(0.5); done.append("ok")
    async def bad(): await asyncio.sleep(0.05); raise RuntimeError("bad")
    msg = None
    try:
        async with asyncio.TaskGroup() as g:
            g.create_task(ok()); g.create_task(bad())
    except* RuntimeError as eg:
        msg = [str(e) for e in eg.exceptions]
    return f"group raised {msg}, sibling finished: {bool(done)}"
print(asyncio.run(tg()))

# async generator and semaphore
async def ticker(n):
    for i in range(n): await asyncio.sleep(0.01); yield i
async def consume():
    return [x async for x in ticker(3)]
print("async for:", asyncio.run(consume()))
async def limited():
    active = peak = 0
    sem = asyncio.Semaphore(3)
    async def job():
        nonlocal active, peak
        async with sem:
            active += 1; peak = max(peak, active); await asyncio.sleep(0.05); active -= 1
    t = time.perf_counter(); await asyncio.gather(*(job() for _ in range(12)))
    return peak, time.perf_counter() - t
peak, el = asyncio.run(limited()); print(f"12 jobs, semaphore(3): peak concurrency {peak}, {el:.2f} s")

Sources

  1. Python documentation, functools (wraps, lru_cache, partial, cached_property) and Function definitions (decorators).
  2. Python documentation, Generator expressions and yield expressions, and contextlib.
  3. Python documentation, asyncio: Coroutines and Tasks (gather, TaskGroup, wait_for, cancellation, to_thread) and Developing with asyncio (blocking calls, never-awaited coroutines).
  4. Python Enhancement Proposals, PEP 318: Decorators for Functions and Methods, PEP 342: Coroutines via Enhanced Generators, PEP 380: Syntax for Delegating to a Subgenerator, PEP 492: Coroutines with async and await syntax, and PEP 654: Exception Groups and except*.
  5. David Beazley, A Curious Course on Coroutines and Concurrency (PyCon 2009), for building coroutines from generators.

Practise this topic: Python

More guides