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:
- The decorator runs once, when the
defstatement executes; the wrapper runs on every call. I recorded the order of events:['decorated a', 'after def', 'called a']. Work done in the decorator body (registering the function, reading configuration) happens at import time. - Stacked decorators apply from the bottom up. With
@tag("b")above@tag("i")abovedef text(), the result was<b><i>x</i></b>:iwrapped the function first, thenbwrapped that. - The wrapper replaces the original, including its name and docstring, unless you copy them.
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:
- Arguments must be hashable.
f([1])raisedTypeError: unhashable type: 'list'. - The function must be pure (same arguments, same result, no side effects), or the cache returns stale or wrong answers.
- Set a
maxsizefor unbounded input spaces (the default is 128).maxsize=Nonegrows without limit. - Do not put it on a method without thinking.
selfis part of the cache key, so the cache holds a reference to every instance that called the method. I deleted the only reference to such an instance, ran the garbage collector, and a weak reference showed it still alive. Cache a module-level function that takes the data as arguments, or usefunctools.cached_propertyfor per-instance values.
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
yield from inner()passes through all values from another generator and evaluates to itsreturnvalue:list(outer())gave[1, 2, 'done'].- A generator that is abandoned can be closed.
c.close()raisesGeneratorExitat the pausedyield, so atry/finallyinside runs (cleanup ranprinted). Always wrap resource handling intry/finallyor awithblock inside generators. @contextlib.contextmanagerturns a generator with oneyieldinto a context manager: code beforeyieldis the setup, code after is the teardown. Atimerwritten that way printedcontextmanager: 50 msaround a 50 ms sleep, and thefinallymakes the teardown run even if the block raises.
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 run | Total 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
- Timeouts:
await asyncio.wait_for(slow(), 0.1)raisedTimeoutErrorafter 0.1 s (and cancelledslow). Every network call should have a timeout; see resilience patterns. - Cancellation:
task.cancel()raisesasyncio.CancelledErrorinside the task at its currentawait. My task printedtask saw CancelledError, re-raised it, andtask.cancelled()wasTrue. Do your cleanup infinally, and re-raiseCancelledErrorrather than swallowing it, or the cancellation is lost. - Structured concurrency:
asyncio.TaskGroup(Python 3.11+) owns its tasks. In my test one task failed after 0.05 s, the group cancelled its sibling (which would have finished at 0.5 s), and the error came out as an exception group (except*) listing['bad']. Withgather, you must handle the leftover tasks yourself; preferTaskGroupfor new code. - Limiting concurrency:
asyncio.Semaphore(3)allowed at most three jobs inside the guarded block. Twelve jobs of 0.05 s each had a peak concurrency of 3 and took 0.20 s (four rounds of three). Without a limit, ten thousand tasks can overwhelm the server you are calling or your own file-descriptor limit. - Async iteration:
async forandasync withwork likeforandwith, for sources that must await between items; an async generator (async defwithyield) produced[0, 1, 2]when consumed with an async comprehension.
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?
| Threads | asyncio | |
|---|---|---|
| Switching | the OS preempts at any time | only at await |
| Races | possible anywhere (use locks) | only across await points, so far fewer |
| Libraries | any blocking library works | needs async-aware libraries |
| Scale | thousands of threads is heavy | tens of thousands of tasks is routine |
| Debugging | harder to reason about | one thread, easier to reason about, but "colouring" spreads: callers of async functions must be async |
4. Common mistakes
- Forgetting
functools.wraps, losing names, docs and signatures. - Confusing decorator time and call time, for example doing slow work in the decorator body.
lru_cacheon a method (keeps instances alive), on impure functions, or without amaxsizefor unbounded inputs.- Reusing an exhausted generator.
- Doing cleanup outside
finallyin generators and coroutines. - Awaiting in sequence and calling it concurrency (0.60 s against 0.20 s).
- Forgetting
await(a warning, and a coroutine that never ran). - Blocking calls in coroutines, including innocent-looking
time.sleep,requests.getand CPU-heavy loops. - Swallowing
CancelledError, which makes timeouts and shutdowns hang. - Unbounded task creation; use a semaphore or a bounded queue.
- Creating a task and dropping the reference. The loop keeps only weak references to tasks, so keep them (or use a
TaskGroup) so they cannot be garbage-collected mid-flight.
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
- A decorator is
f = deco(f)at definition time; wrapper per call;wraps; arguments through a factory; stacking order. lru_cache: hashable arguments, purity, size limits, the method pitfall.- Generators as lazy, one-shot iterators;
send,yield from,closeandfinally; pipelines;contextmanager. - Coroutines as pausable functions driven by an event loop; sequential
awaitagainstgather; cancellation; timeouts;TaskGroup; semaphores. - Never block the loop;
to_thread; async is for waiting, not computing. - Threads against
asyncio: preemptive against cooperative switching, and what each does to race conditions.
Quick recap
@decoisf = deco(f); decorators run at definition time and wrappers on each call. Usefunctools.wraps. A pass-through wrapper added about 100 ns per call (73 ms against 177 ms for one million calls).lru_cacheturnedfib(27)from 40 ms into 0.05 ms, needs hashable arguments and pure functions, and on a method kept a deleted instance alive.- A generator pauses at
yield, keeps its state, is lazy and one-shot; chained generators process one item at a time and read only what they need. async defreturns a coroutine that does nothing until awaited by an event loop. Awaiting three 0.2 s tasks in sequence took 0.60 s; withgather0.20 s.- Cancellation raises
CancelledErrorat theawait;TaskGroupcancels siblings when one fails; a semaphore of 3 kept peak concurrency at 3. - Blocking calls inside coroutines freeze the loop; use
to_thread, a process pool or an async library.
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
- Python documentation,
functools(wraps,lru_cache,partial,cached_property) and Function definitions (decorators). - Python documentation, Generator expressions and
yieldexpressions, andcontextlib. - Python documentation,
asyncio: Coroutines and Tasks (gather,TaskGroup,wait_for, cancellation,to_thread) and Developing with asyncio (blocking calls, never-awaited coroutines). - 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*. - David Beazley, A Curious Course on Coroutines and Concurrency (PyCon 2009), for building coroutines from generators.
Practise this topic: Python