ITERATORS · PIPELINES · CONTEXT MANAGERS · STRATEGIES · CHAINS · HOOKS · VISITORS

Design patterns in Python, part 3:
how objects share the work

Behavioral patterns decide which object does which part of a job, and how work passes between them: one walks a collection, one picks the algorithm, one reacts to an event. Each chapter follows one pattern through a project you already use, then shows the Python you would write.

Every chapter reads the same way. A card sums the pattern up: its intent, its roles, when to reach for it, how to spot it in code you read. Then come the problem it solves, the shape of its roles, the same shape with a real project’s classes in every box, and an annotated excerpt of that project’s source. Core chapters follow one call through the project, and every chapter ends with the code you would write. Chapters can be read in any order.

You need to know Python’s classes, functions, decorators and modules. Code runs on Python 3.15. Excerpts are trimmed, marked with the file, project and version they come from, and link to the source at that release: Django 6.1.3, requests 2.34.2, Flask 3.1.3, blinker 1.9.0, pytest 9.2.0, pluggy 1.7.0, Alembic 1.20.1, Starlette 1.10.0, h11 0.16.0, Jinja2 3.1.6 and jmespath 1.1.0. Tap any figure to open it full screen and zoom. Dotted terms are tappable. This is part 3 of 3; part 1 covers how objects get made, and part 2 how they fit together.

Iterator: walk a collection without knowing how it’s stored

An iterator is a separate object that hands out a collection’s items one at a time, so the code that loops never learns how they are stored. You use one in every for loop. Over a Django QuerySet with millions of rows, the loop looks exactly like one over a three-item list, yet one way of writing it reads every row into memory first and another reads a chunk at a time. How does Django hand you rows one at a time, and when does it read them all first?

THE PATTERN

you’ll write it often

Give a collection a separate object that hands out its items one at a time, so loops never depend on how the items are stored.

ROLES
  • iterablethe collection; its __iter__() returns a new iterator
  • iteratorremembers the position; __next__() returns the next item or raises StopIteration
  • clientthe for loop, list() or sum(), which only asks for the next item
REACH FOR IT WHEN
Your object holds items other code loops over, or the items arrive in pages, rows, lines or chunks.
SKIP IT WHEN
A list already holds every item and fits in memory: return the list.
HOW TO SPOT IT
__iter__ that returns self or contains yield, __next__ raising StopIteration, classes named *Iterator or *Iterable.
IN PYTHON
Built in. The for statement calls iter() and next() for you, and a generator function writes the iterator.
SEEN IN
  • Django 6.1 · django/db/models/query.pyModelIterable turns database rows into model instances, one per next(), for every QuerySet loop.
  • Jinja2 3.1 · jinja2/lexer.pyTokenStreamIterator hands the template parser one token at a time and stops at the end of the template.
  • requests 2.34 · requests/models.pyLooping over a Response yields its body in chunks of 128 bytes through iter_content().
  • CPython 3.15 · Lib/os.pyos.walk() yields one directory at a time, so a walk over a whole disk starts at once.
STEP 01 / 05

WITHOUT AN ITERATOR, EVERY LOOP DRIVES THE CURSOR

Fig 1.1Compare the bottom rows: the red one is the cost of every loop knowing the storage.

A database cursor already hands out rows, but only in pages and only as tuples. Code that loops over articles straight from the cursor has to run the query, call fetchmany() until it returns an empty list, and turn each tuple into something useful. The sample does exactly that with sqlite3 from the standard library.

That loop knows three things it shouldn’t: the query, the page size and the shape of a row. Add a column or move to a database that streams rows differently, and every loop written like it has to change. Django’s ORM exists partly so that no loop in your code touches a cursor.

THE LOOP DOES THE PAGING ITSELF
import sqlite3

db = sqlite3.connect(":memory:")
db.execute("create table article (id integer, title text)")
db.executemany(
    "insert into article values (?, ?)",
    [(1, "Iterators"), (2, "Pipelines"), (3, "Context managers")],
)

# Without an iterator, this loop knows the query, the paging and the row shape.
cur = db.execute("select id, title from article order by id")
titles = []
while rows := cur.fetchmany(2):
    for article_id, title in rows:
        titles.append(title)
titles  # → ['Iterators', 'Pipelines', 'Context managers']
STEP 02 / 05

THE COLLECTION HANDS OUT A SEPARATE WALKER

Fig 1.2Follow the accent arrow: the loop talks only to the iterator, never to the storage.

The pattern has three roles. The iterable is the collection, and its job is to create an iterator when asked. The iterator remembers where the walk has got to and returns one item per call. The client is whatever loops: a for statement, list(), sum() or a comprehension.

In Python the roles are two dunder methods. iter(x) calls x.__iter__(), and next(it) calls it.__next__(), which raises StopIteration when nothing is left. The for statement makes both calls for you, so every for loop you have written is a client of this pattern.

STEP 03 / 05

DJANGO’S QUERYSET NEVER WALKS ITS OWN ROWS

Fig 1.3The boxes sit where the shape’s did; the accent box turns rows into model instances.

A QuerySet is lazy: building one runs no SQL. It holds the query and, in _iterable_class, the iterator class to create. That is ModelIterable unless you call values() or values_list(), which swap in iterators that yield dicts or tuples. Your loop never learns which one it got.

The first loop over a QuerySet calls _fetch_all(), which runs list(self._iterable_class(self)) and keeps every object in _result_cache. A second loop over the same QuerySet reads the cache and runs no query. That is the plain loop’s trade: every row in memory, in exchange for loops that cost nothing after the first.

THE QUERYSET CREATES ITS ITERATOR
# django/db/models/query.py · Django 6.1.3 (trimmed)
class QuerySet(AltersData):  # ← the collection
    def __init__(self, model=None, query=None, using=None, hints=None):
        ...
        self._result_cache = None
        ...
        self._iterable_class = ModelIterable  # ← the iterator it will create

    def __iter__(self):
        self._fetch_all()  # ← a plain for loop reads every row first
        return iter(self._result_cache)

    def _fetch_all(self):
        if self._result_cache is None:
            self._result_cache = list(self._iterable_class(self))
        ...

    def iterator(self, chunk_size=None):  # ← streams, keeps no cache
        ...
        return self._iterator(use_chunked_fetch, chunk_size)
STEP 04 / 05

A PLAIN LOOP CACHES, ITERATOR() STREAMS

Fig 1.4Calls 3 and 4 are the same call; between them, your loop takes 2,000 steps.

iterator() skips the cache. It builds the same ModelIterable with chunked fetching on and a chunk size of 2,000 unless you pass another, and yields from it. Each next() runs the generator up to its next yield obj, so Django builds one Article at a time from rows it has already fetched.

When the chunk is used up, the generator asks the cursor for the next fetchmany(). On PostgreSQL that cursor is server-side, so the database holds the rows not read yet, unless the DISABLE_SERVER_SIDE_CURSORS setting is on. The price is a fresh query for every loop: nothing is cached.

MODELITERABLE BUILDS ONE ARTICLE PER NEXT()
# django/db/models/query.py · Django 6.1.3 (trimmed)
class ModelIterable(BaseIterable):  # ← the iterator
    """Iterable that yields a model instance for each row."""

    def __iter__(self):
        queryset = self.queryset
        db = queryset.db
        compiler = queryset.query.get_compiler(using=db)
        results = compiler.execute_sql(  # ← rows arrive in chunks
            chunked_fetch=self.chunked_fetch, chunk_size=self.chunk_size
        )
        ...
        for row in compiler.results_iter(results):
            obj = from_db(
                db,
                init_list,
                row[model_fields_start:model_fields_end],
            )
            ...
            yield obj  # ← one Article per next()
STEP 05 / 05

WRITE __ITER__ AS A GENERATOR

Fig 1.5The accent panel is the form to write; the faint row is why the left one surprises people.

You rarely write __next__ by hand. Make __iter__ a generator function instead, and each call returns a new generator: an iterator Python wrote for you, which remembers its place between yields and raises StopIteration when the function returns.

The sample wraps a paged API. Nothing is fetched until the first next(), each loop starts again from page 1, and the walk stops on the first empty page. That is why the last line shows page 3 being asked for.

AN ITERABLE OVER A PAGED API
from collections.abc import Callable, Iterator


class Pages:
    def __init__(self, fetch: Callable[[int], list[str]]) -> None:
        self.fetch = fetch

    def __iter__(self) -> Iterator[str]:  # a generator: a new iterator per loop
        page = 1
        while batch := self.fetch(page):
            yield from batch
            page += 1


asked: list[int] = []
def fetch(page: int) -> list[str]:
    asked.append(page)
    return {1: ["ada", "grace"], 2: ["linus"]}.get(page, [])

users = Pages(fetch)
next(iter(users))  # → 'ada'
asked  # → [1]
list(users)  # → ['ada', 'grace', 'linus']
asked  # → [1, 1, 2, 3]

COMMON QUESTIONS

Is an iterator also an iterable?
Yes. Its __iter__() returns itself, which is why you can loop over a generator. The reverse isn’t true: a list is iterable, but it has no __next__().
Why does len() fail on a generator?
A generator doesn’t know how many items it will produce until it has produced them. Call list() first if you need the count, and accept the memory.
When should I call QuerySet.iterator()?
When you loop once over many rows and won’t need them again: exports, batch jobs, data migrations. For a page of twenty rows, the cache is cheaper.

WHAT YOU NOW KNOW

  • An iterable creates iterators; an iterator returns one item per next() and raises StopIteration at the end.
  • A QuerySet creates a ModelIterable: a plain loop caches every row, and iterator() streams them 2,000 at a time.
  • Write __iter__ as a generator, and each loop gets a fresh, lazy iterator.
DEEP DIVE: also in Jinja2, the two-argument iter(), async iteration, typing it, its cost, looks like

Also in Jinja2: an iterator the parser steps by hand

Jinja2’s lexer turns a template into tokens, and TokenStream holds them. Its __iter__() returns a separate TokenStreamIterator, the textbook split between collection and iterator. The parser, though, rarely loops: it calls next() to step and look() to peek at the token after the current one, which a for loop can’t do.

JINJA2: THE TOKEN STREAM AND ITS ITERATOR
# src/jinja2/lexer.py · Jinja2 3.1.6 (trimmed)
class TokenStreamIterator:  # ← the iterator
    def __init__(self, stream: "TokenStream") -> None:
        self.stream = stream

    def __iter__(self) -> "TokenStreamIterator":
        return self

    def __next__(self) -> Token:
        token = self.stream.current
        if token.type is TOKEN_EOF:
            self.stream.close()
            raise StopIteration  # ← the end of the template
        next(self.stream)
        return token


class TokenStream:  # ← the collection, with look() and skip() for the parser
    def __iter__(self) -> TokenStreamIterator:
        return TokenStreamIterator(self)

The two-argument iter()

iter(callable, sentinel) builds an iterator from a function: it calls the function until the result equals the sentinel. Django’s cursor_iter() uses it to call fetchmany() until the database returns its empty value, and closes the cursor in a finally block even if your loop stops early.

DJANGO: FETCHMANY() UNTIL THE SENTINEL
# django/db/models/sql/compiler.py · Django 6.1.3
def cursor_iter(cursor, sentinel, col_count, itersize):
    """
    Yield blocks of rows from a cursor and ensure the cursor is closed when
    done.
    """
    try:
        for rows in iter((lambda: cursor.fetchmany(itersize)), sentinel):  # ← until []
            yield rows if col_count is None else [r[:col_count] for r in rows]
    finally:
        cursor.close()

Async iteration

The async version of the protocol is __aiter__() and __anext__(), driven by async for. Django’s QuerySet has aiterator(), and the base iterable class runs the synchronous generator in chunks through sync_to_async, because each database call still happens on a thread.

Typing it

Accept Iterable[T] when a function only loops over its argument, so callers can pass a list, a generator or a QuerySet. Return Iterator[T] from __iter__() and from generator functions. Both live in collections.abc, and typing.Generator is needed only when the generator also receives values through send().

Its cost

A generator step costs a function resume, more than indexing a list. That rarely matters next to a database round trip, but in a hot numeric loop a list, or NumPy, is faster. The bigger cost is surprise: an exhausted iterator fails silently, with an empty loop rather than an error.

LOOKS LIKE

Generator pipelines
A pipeline chains iterators, each one pulling from the one before it.
Generators passed into other generators, not one class with __iter__().
Composite (part 2)
A composite is a tree of items; an iterator is one way to walk it.
A children list and recursion; an iterator over it yields from each child.
Visitor
A visitor runs an operation on each node, chosen by the node’s type; an iterator only hands nodes out.
Methods named visit_ plus a class name.

Generator pipelines: process a stream one item at a time

A generator pipeline is a chain of generators, each pulling items from the one before it and yielding its own, so data flows through one item at a time and never as whole lists. You build one whenever you stream a file, a socket or a query that won’t fit in memory. requests streams a response body this way: your loop asks for a line, and only then does a chunk leave the socket. How does iter_lines() turn a stream of bytes into lines without reading the whole body?

THE PATTERN

you’ll write it often

Process a stream one item at a time by chaining generators, each pulling from the one before it, so nothing waits for the whole input.

ROLES
  • sourceproduces raw items when asked: a file, a socket, a database cursor
  • stagea generator that pulls items, changes or filters them, and yields its own
  • consumerthe loop, sum() or list() that pulls from the last stage
REACH FOR IT WHEN
The input is large, endless or slow to arrive, and each item can be handled on its own.
SKIP IT WHEN
You need random access, several passes or a sort over everything: build a list.
HOW TO SPOT IT
Functions with yield that take an iterable and return an iterator, yield from, stream=True, methods named iter_*().
IN PYTHON
A function with yield is a stage. Generator expressions, map(), filter() and itertools are ready-made stages.
SEEN IN
  • requests 2.34 · requests/models.pyiter_lines() pulls chunks from iter_content(), which pulls from urllib3, and yields one line at a time.
  • Django 6.1 · django/db/models/sql/compiler.pyresults_iter() chains chunks of rows into rows, then converts each through a generator stage.
  • CPython 3.15 · Lib/tokenize.pygenerate_tokens() pulls source lines through readline and yields one token at a time.
STEP 01 / 05

READING THE WHOLE BODY FIRST HOLDS ALL OF IT IN MEMORY

Fig 2.1Compare the bottom rows: one grows with the body, the other stays at one chunk.

Response.content reads the entire body into one bytes object, and .text decodes all of it. For an API reply of a few kilobytes that is fine. For a log export, a feed of JSON lines or a large CSV, the process holds every byte before your code sees the first line.

Splitting afterwards adds to it: content.splitlines() builds a list of every line while the bytes are still in memory, and your loop starts only after the last byte has arrived.

STEP 02 / 05

EACH STAGE PULLS FROM THE ONE BEFORE IT

Fig 2.2Follow the accent arrows right: each next() asks the stage to its right for one item.

A pipeline has three roles. The source produces raw items when asked: a file, a socket, a database cursor. Each stage is a generator that pulls items from the stage before it, changes or filters them, and yields its own. The consumer pulls from the last stage.

Nothing runs until the consumer asks. Its next() runs the last stage up to its next yield, which asks the stage before it for an item, and so on back to the source. That pull is what makes the chain lazy: work happens one item at a time, when the consumer needs it.

STEP 03 / 05

REQUESTS BUILDS ITER_LINES() ON ITER_CONTENT()

Fig 2.3The boxes sit where the shape’s did; iter_lines() is the accent stage.

With stream=True, requests reads only the headers and leaves the body on the connection. iter_content() returns a generator that pulls from urllib3’s raw.stream() in chunks of the size you ask for. Decoding to text, when you ask for it, is one more generator wrapped around that one.

Calling iter_content() reads nothing: it builds the generator and returns it. Bytes leave the socket only when something calls next() on it, and the response marks its content consumed when the generator runs out.

ITER_CONTENT(): A GENERATOR OVER THE SOCKET
# src/requests/models.py · requests 2.34.2 (trimmed)
class Response:
    ...
    def iter_content(self, chunk_size=1, decode_unicode=False):
        def generate():  # ← stage 1: a generator over the socket
            # Special case for urllib3.
            if hasattr(self.raw, "stream"):
                try:
                    yield from self.raw.stream(chunk_size, decode_content=True)
                except ProtocolError as e:
                    raise ChunkedEncodingError(e)
                ...
            self._content_consumed = True
        ...
        if self._content_consumed:
            ...
        else:
            chunks = generate()  # ← nothing is read yet
        if decode_unicode:
            chunks = stream_decode_response_unicode(chunks, self)  # ← an optional stage
        return chunks
STEP 04 / 05

AN UNFINISHED LINE WAITS FOR THE NEXT CHUNK

Fig 2.4Calls 1 to 3 fetch the first line; call 4 is answered without touching the socket.

iter_lines() pulls 512-byte chunks from iter_content() and splits each one into lines. A chunk rarely ends exactly at a newline, so when its last line is cut off, iter_lines() keeps it in pending and glues it to the front of the next chunk.

One chunk often holds several lines. The first next() reads a chunk and yields its first line; the next calls are answered from lines already split, and the socket is read again only when they run out.

ITER_LINES(): CHUNKS IN, LINES OUT
# src/requests/models.py · requests 2.34.2 (trimmed)
class Response:
    ...
    def iter_lines(self, chunk_size=ITER_CHUNK_SIZE, decode_unicode=False, delimiter=None):
        pending = None
        for chunk in self.iter_content(  # ← pulls from stage 1, 512 bytes at a time
            chunk_size=chunk_size, decode_unicode=decode_unicode
        ):
            if pending is not None:
                chunk = cast("str | bytes", pending + chunk)
            if delimiter:
                lines = chunk.split(delimiter)
            else:
                lines = chunk.splitlines()
            if lines and lines[-1] and chunk and lines[-1][-1] == chunk[-1]:
                pending = lines.pop()  # ← a cut-off line waits for the next chunk
            else:
                pending = None
            yield from lines  # ← one line per next()
        if pending is not None:
            yield pending
READING A FEED OF JSON LINES
import json

import requests

with requests.get("https://example.com/events.ndjson", stream=True) as r:
    r.raise_for_status()
    for line in r.iter_lines():  # bytes, one line per step
        if line:  # keep-alive newlines arrive as empty lines
            event = json.loads(line)
            print(event["type"])
STEP 05 / 05

CHAIN GENERATORS, NOT LISTS

Fig 2.5The bottom rows are the difference: one grows with the input, the other doesn’t.

Your own pipeline is a few small generator functions, each taking an iterable and returning an iterator. The sample parses an access log, drops server errors and adds up response times. Building the chain reads nothing, as the 0 from tell() shows.

Keep each stage to one job. A stage that only filters can be a generator expression. One that keeps state between items, the way iter_lines() keeps its pending line, needs a function.

A LOG PIPELINE IN THREE STAGES
import io
from collections.abc import Iterable, Iterator

log = io.StringIO("""GET /cart 200 31
GET /pay 500 120
POST /pay 200 88
GET /cart 200 29
""")

def parse(lines: Iterable[str]) -> Iterator[tuple[str, int, int]]:
    for line in lines:
        method, path, status, ms = line.split()
        yield path, int(status), int(ms)

def ok(rows: Iterable[tuple[str, int, int]]) -> Iterator[tuple[str, int, int]]:
    return (row for row in rows if row[1] < 500)

rows = ok(parse(log))  # builds the chain, reads nothing
log.tell()  # → 0
next(rows)  # → ('/cart', 200, 31)
sum(ms for _, _, ms in rows)  # → 117

COMMON QUESTIONS

What does yield from do?
It passes every item of another iterable to the caller, one per next(), as if the current generator had yielded each itself. iter_content() uses it to pass urllib3’s chunks straight through.
Can a stage look at the next item before yielding?
Only by pulling it early and holding on to it, the way iter_lines() holds its pending line. itertools.pairwise() and groupby() do this for you.
Is a generator expression a pipeline stage?
Yes. A filter such as (row for row in rows if row[1] < 500) is a complete stage written in one line.

WHAT YOU NOW KNOW

  • A pipeline is generators pulling from generators, and nothing runs until the consumer asks.
  • requests streams a body through iter_content() and iter_lines(), holding one 512-byte chunk and one unfinished line.
  • Each of your stages takes an iterable and returns an iterator, so the chain works on input of any size.
DEEP DIVE: also in Django, itertools, sending values in, typing it, its cost, looks like

Also in Django: rows through a chain of stages

Django’s SQLCompiler turns a cursor’s chunks into rows with chain.from_iterable(), then passes them through apply_converters(), a generator that turns database values into Python ones, and finally through map(tuple) when tuples are wanted. Each stage is added only when it is needed, and none of them reads ahead.

DJANGO: RESULTS_ITER() BUILDS A PIPELINE
# django/db/models/sql/compiler.py · Django 6.1.3 (trimmed)
class SQLCompiler:
    ...
    def results_iter(self, results=None, tuple_expected=False, chunked_fetch=False,
                     chunk_size=GET_ITERATOR_CHUNK_SIZE):
        """Return an iterator over the results from executing this query."""
        ...
        rows = chain.from_iterable(results)  # ← chunks of rows become rows
        if converters:
            rows = self.apply_converters(rows, converters)  # ← a generator stage
        if self.has_composite_fields(fields):
            rows = self.composite_fields_to_tuples(rows, fields)
        if tuple_expected:
            rows = map(tuple, rows)  # ← map() is lazy too
        return rows

itertools: the standard stages

itertools is a box of stages written in C. The islice() stage takes the first n items and stops the chain; chain() joins iterables; batched() groups items into tuples of n. The pairwise() stage yields overlapping pairs, and groupby() groups runs of equal keys. The tee() function splits one iterator in two, but buffers whatever one copy has seen and the other hasn’t.

Sending values in

A generator can also receive values: x = yield y pauses, and gen.send(value) resumes it with x set. Before async and await, that was how Python wrote coroutines. In a data pipeline you rarely need it; pass configuration as arguments when you build the stage.

Typing it

Annotate a stage as taking Iterable[T] and returning Iterator[U]. That lets callers pass a list in a test and a generator in production. Generator[Y, S, R] is needed only when the stage uses send() or returns a value at the end.

Its cost

Each stage adds a frame resume per item, so a long chain over millions of tiny items is slower than one loop doing all the work. Debugging is harder too, because a stage runs only when pulled. When memory is not the problem and the data is small, a list is simpler to inspect.

LOOKS LIKE

Iterator
An iterator walks one collection; a pipeline chains iterators that each change the items.
One class with __iter__() against several generator functions passed into each other.
Chain of Responsibility
A chain passes one request along until a handler deals with it; a pipeline passes every item through every stage.
A handler that can stop the request and answer it, against stages that only transform.
Decorator (part 2)
A decorator wraps one object and keeps its interface; a stage turns one stream into another.
The wrapper has the same methods as the thing inside it.

Context managers: cleanup that always runs

A context manager is an object that runs setup code when a with block starts and cleanup code when it ends, however it ends. You use one every time you open a file, take a lock or start a database transaction with with. The standard library’s contextlib turns an ordinary generator function into one, so a few lines around a yield can guarantee a connection is closed. How does a function with a yield become something a with statement can call, and how does an error in the block reach its cleanup?

THE PATTERN

you’ll write it often

Pair setup with cleanup so the cleanup always runs when a block ends, whether it returns, breaks or raises.

ROLES
  • clientthe with statement, which calls __enter__() and __exit__()
  • context managerthe object with __enter__() and __exit__(type, value, traceback)
  • resourcewhat is set up and cleaned up: a lock, a file, a transaction
REACH FOR IT WHEN
Something must be undone after use: a lock released, a file closed, a transaction committed or rolled back, a patch reverted.
SKIP IT WHEN
Nothing needs cleaning up afterwards; a plain function call is enough.
HOW TO SPOT IT
with statements, __enter__ and __exit__, @contextmanager on a generator, a single yield inside try/finally.
IN PYTHON
Built in: the with statement. contextlib adds @contextmanager, ExitStack, suppress(), closing() and chdir().
SEEN IN
  • CPython 3.15 · Lib/contextlib.py@contextmanager wraps a generator function in a class with __enter__() and __exit__().
  • SQLAlchemy 2.1 · sqlalchemy/orm/session.pywith session.begin() commits when the block ends and rolls back when it raises.
  • pytest 9.2 · _pytest/raises.pywith pytest.raises() fails when nothing raises, and its __exit__() returns True to swallow the expected error.
  • CPython 3.15 · Lib/unittest/mock.pypatch() replaces an attribute in __enter__() and puts the original back in __exit__().
STEP 01 / 05

CLEANUP WRITTEN BY HAND IS SKIPPED BY THE FIRST EXCEPTION

Fig 3.1Follow the red arrows: one exception skips the release, and every later call waits.

Code that takes a resource and gives it back on a later line works until something between them raises. The exception leaves the function at once, the release line never runs, and the lock stays taken. The next caller waits forever, which looks like a hang rather than an error.

try/finally fixes one function. The trouble is that every function that takes the lock has to remember it, and the first one that forgets brings the bug back.

A LOCK LEFT HELD, THEN RELEASED BY WITH
import threading

lock = threading.Lock()

def charge(card: str) -> None:
    lock.acquire()
    if card == "expired":
        raise ValueError(card)  # the release below never runs
    lock.release()

try:
    charge("expired")
except ValueError:
    pass
lock.locked()  # → True

lock.release()
with lock:  # __exit__ releases it, error or not
    pass
lock.locked()  # → False
STEP 02 / 05

WITH CALLS __ENTER__ BEFORE AND __EXIT__ AFTER, WHATEVER HAPPENS

Fig 3.2Two accent arrows, one manager: the with statement calls it on the way in and the way out.

The with statement calls the manager’s __enter__() before the block and binds its return value to the name after as. When the block ends, it calls __exit__() with three arguments: the exception’s type, value and traceback, or three Nones if there was none.

That pair of methods is the context manager protocol. If __exit__() returns a true value, the exception is swallowed; any other return lets it propagate. Most managers return False, or nothing, and only clean up.

STEP 03 / 05

@CONTEXTMANAGER SPLITS A GENERATOR AT ITS YIELD

Fig 3.3The boxes sit where the shape’s did; the accent manager turns your generator into the protocol.

Writing __enter__ and __exit__ for every resource is tedious, so contextlib does it for you. @contextmanager wraps your generator function. Each call builds a _GeneratorContextManager, whose __enter__() runs the generator to its yield and returns what it yields.

Its __exit__() resumes the generator. With no error it calls next(), so the code after the yield runs, and expects the generator to finish. With an error it calls gen.throw(), which raises the exception at the yield, inside your try, so your finally runs.

CONTEXTLIB: ENTER RUNS TO YIELD, EXIT RESUMES IT
# Lib/contextlib.py · CPython 3.15.2 (trimmed)
class _GeneratorContextManager(
    _GeneratorContextManagerBase, AbstractContextManager, ContextDecorator,
):
    def __enter__(self):
        ...
        try:
            return next(self.gen)  # ← runs your function up to its yield
        except StopIteration:
            raise RuntimeError("generator didn't yield") from None

    def __exit__(self, typ, value, traceback):
        if typ is None:
            try:
                next(self.gen)  # ← no error: runs the code after yield
            except StopIteration:
                return False
            ...
        else:
            ...
            try:
                self.gen.throw(value)  # ← an error: raises it at the yield
            except StopIteration as exc:
                return exc is not value  # ← True only if the generator swallowed it
            ...
STEP 04 / 05

AN ERROR GOES BACK INTO THE GENERATOR AT THE YIELD

Fig 3.4Calls 3 and 4 carry the error back in; the accent note is where your cleanup runs.

When the block raises, the with statement doesn’t unwind past the manager. It calls __exit__() first, with the exception. contextlib throws it into the generator at the yield, so to your function it looks as if the yield line itself raised.

Your finally closes the connection, the exception leaves the generator, and __exit__() checks that it is the same exception object. It returns False, and the with statement re-raises the KeyError to your caller. Only a generator that catches the error and doesn’t raise it again can swallow it.

THE DECORATOR: A NEW MANAGER PER CALL
# Lib/contextlib.py · CPython 3.15.2 (trimmed)
def contextmanager(func):
    """@contextmanager decorator.
    ...
    """
    @wraps(func)
    def helper(*args, **kwds):
        return _GeneratorContextManager(func, args, kwds)  # ← a new manager per with
    return helper
STEP 05 / 05

WRITE ONE WITH @CONTEXTMANAGER, AND USE EXITSTACK FOR MANY

Fig 3.5Both panels work; the highlighted row is the tool most people don’t know they have.

For your own code, a generator with @contextmanager is usually enough: set up, yield the resource inside try, clean up in finally. Write a class when the manager must be reused, keep state between uses, or be a public type with methods of its own.

ExitStack handles a number of managers known only at run time. It enters each one with enter_context() and exits them in reverse order when its own block ends, as the log in the sample shows.

A GENERATOR MANAGER AND AN EXITSTACK
from collections.abc import Iterator
from contextlib import ExitStack, contextmanager

log: list[str] = []

@contextmanager
def opened(name: str) -> Iterator[str]:
    log.append("open " + name)
    try:
        yield name.upper()
    finally:
        log.append("close " + name)  # runs on success and on error

with ExitStack() as stack:  # any number of managers, closed in reverse
    handles = [stack.enter_context(opened(n)) for n in ("a", "b")]
handles  # → ['A', 'B']
log  # → ['open a', 'open b', 'close b', 'close a']

try:
    with opened("c"):
        raise KeyError("c")
except KeyError:
    log.append("handled")
log[-2:]  # → ['close c', 'handled']

COMMON QUESTIONS

Is open() a context manager?
The file object it returns is. Its __exit__() closes the file, which flushes buffered writes, so everything written inside the with block has reached the operating system when it ends.
Can a context manager also be a decorator?
Yes. Managers built with @contextmanager inherit ContextDecorator, so you can put one above a function, and the whole body runs inside the with block.
What about async with?
Same protocol, awaited: __aenter__() and __aexit__(). @asynccontextmanager builds one from an async generator.

WHAT YOU NOW KNOW

  • with calls __enter__() before the block and __exit__() after it, error or not.
  • contextlib runs your generator to its yield on entry, and throws any error back in at the yield on exit.
  • Put the yield inside try/finally, and reach for ExitStack when the number of managers varies.
DEEP DIVE: also in SQLAlchemy and pytest, the rest of contextlib, typing it, testing it, looks like

Also in SQLAlchemy: a transaction as a block

session.begin() returns a transaction object that is also a context manager. Its exit commits when the block ends normally and rolls back when it raises, and the outer with closes the session. Two nested with lines replace a try, a commit, an except with a rollback, and a finally with a close.

SQLALCHEMY: COMMIT OR ROLL BACK BY BLOCK
from sqlalchemy.orm import Session

with Session(engine) as session:  # closes the session at the end
    with session.begin():  # commits on success, rolls back on an exception
        session.add(Order(total_cents=4200))

Also in pytest: a manager that swallows on purpose

pytest.raises() inverts the usual rule. Its __exit__() fails the test when the block raises nothing, checks that the exception matches, records it on the object __enter__() returned, and returns True so the expected exception goes no further.

The rest of contextlib

suppress(KeyError) swallows named exceptions, closing(x) calls x.close() at the end, nullcontext() stands in when a manager is optional, chdir(path) changes the working directory for one block, and redirect_stdout() sends print output elsewhere. AsyncExitStack is ExitStack for async managers.

Typing it

Annotate a @contextmanager function as returning Iterator[T], where T is what it yields. A class manager returns Self, or the resource, from __enter__() and bool or None from __exit__(); declare bool only when it can swallow, so type checkers know code after the block is reachable.

Testing it

unittest.mock.patch() is itself a context manager, which is why with patch("module.name") undoes the patch even when an assertion fails inside the block. Test your own managers the same way: run a block that raises, and assert the cleanup happened.

LOOKS LIKE

Function decorators (part 2)
A decorator wraps every call of one function; a context manager wraps one block, wherever you write it.
An @ line above a def, against a with line above a block.
Template Method
A template method fixes steps around a method a subclass writes; a manager fixes steps around a block the caller writes.
A base class with a hook method, against __enter__() and __exit__().

Strategy: let the caller choose the algorithm

Strategy puts an algorithm behind a small interface and lets the caller choose which one to pass in, so the code that uses it never changes when a new one appears. In Python the interface is often just a call: sorted() takes a key function, and requests takes an auth object. requests ships Basic and Digest authentication and supports any scheme a user writes, yet its sending code holds no list of schemes. How does requests sign a request with a scheme it has never heard of?

THE PATTERN

you’ll write it often

Put each variant of an algorithm behind the same small interface, and let the caller pass in the one to use.

ROLES
  • contextthe code that needs the algorithm and calls it without knowing which one it has
  • strategythe interface every variant shares, often a single method or a call
  • concrete strategyone variant: Basic auth, Digest auth, your own token scheme
REACH FOR IT WHEN
Several ways to do one step exist, and the caller, a setting or the data decides which.
SKIP IT WHEN
There is one algorithm and no sign of a second: call it directly.
HOW TO SPOT IT
Parameters named key=, auth=, default=, cls= or *_class; a setting that lists class paths; a dict of functions keyed by name.
IN PYTHON
Usually a function: pass a callable. A class is worth it when the strategy keeps state or needs several methods.
SEEN IN
  • requests 2.34 · requests/auth.pyauth= takes any callable that changes the prepared request; Basic and Digest are two built-in ones.
  • Django 6.1 · django/contrib/auth/hashers.pymake_password() hashes with the first class in PASSWORD_HASHERS, so a setting swaps the algorithm.
  • CPython 3.15 · Lib/json/__init__.pyjson.dumps() takes default= and cls= to choose how objects JSON doesn’t know are encoded.
STEP 01 / 05

AN IF CHAIN IN THE SENDER GROWS WITH EVERY SCHEME

Fig 4.1Compare the bottom rows: one change edits the sender, the other only adds code.

Without strategies, the code that sends a request has to know every authentication scheme: an if for Basic, an elif for Digest, another for every token format a user might need. Each new scheme means editing the sender and testing every branch again.

A library can’t even ship that list complete. Your company’s request signing, an OAuth token or a cloud provider’s signature would each need a change to requests itself.

STEP 02 / 05

THE CALLER PASSES THE ALGORITHM IN

Fig 4.2The accent arrow is the only contact: the context calls one method and asks nothing else.

Strategy has three roles. The context is the code that needs the algorithm. The strategy is the interface every variant shares, often a single method. Each concrete strategy is one variant, and the client decides which one the context receives.

The context never branches on which strategy it has. It calls the one method and uses the result, so adding a variant adds a class or a function and touches nothing else.

STEP 03 / 05

REQUESTS CALLS WHATEVER YOU PASS AS AUTH

Fig 4.3The boxes sit where the shape’s did; AuthBase’s single method is the whole interface.

In requests the strategy interface is one method, __call__(r), which takes the prepared request, changes it and returns it. AuthBase declares it and raises NotImplementedError; HTTPBasicAuth implements it by setting the Authorization header from a username and password.

Because the interface is a call, a strategy doesn’t have to subclass AuthBase at all. Any callable that takes a request and returns it works; the base class mostly makes the intent clear.

REQUESTS: THE AUTH STRATEGIES
# src/requests/auth.py · requests 2.34.2 (trimmed)
class AuthBase:  # ← the strategy: one method, __call__
    """Base class that all auth implementations derive from"""

    def __call__(self, r: PreparedRequest) -> PreparedRequest:
        raise NotImplementedError("Auth hooks must be callable.")


class HTTPBasicAuth(AuthBase):  # ← one concrete strategy
    """Attaches HTTP Basic Authentication to the given Request object."""

    def __init__(self, username: bytes | str, password: bytes | str) -> None:
        self.username = username
        self.password = password
    ...
    def __call__(self, r: PreparedRequest) -> PreparedRequest:
        r.headers["Authorization"] = _basic_auth_str(self.username, self.password)
        return r
STEP 04 / 05

A TUPLE BECOMES HTTPBASICAUTH, ANYTHING ELSE IS CALLED AS IT IS

Fig 4.4Call 3 is the strategy at work; everything around it is the same for every scheme.

prepare_auth() has one convenience: a two-item tuple is taken as a username and password and wrapped in HTTPBasicAuth. Anything else is called as it is. That single if is the only place requests looks at what kind of auth it was given.

After the call, requests copies the strategy’s changes back onto itself and recomputes Content-Length, because a strategy may change the body too. A strategy of your own is a class with __call__, like the second sample, or a plain function.

REQUESTS: THE CONTEXT CALLS IT
# src/requests/models.py · requests 2.34.2 (trimmed)
class PreparedRequest:
    ...
    def prepare_auth(self, auth, url=""):  # ← the context
        """Prepares the given HTTP auth data."""
        ...
        if auth:
            if isinstance(auth, tuple) and len(auth) == 2:
                # special-case basic HTTP auth
                auth_handler = HTTPBasicAuth(*auth)
            else:
                auth_handler = cast("Callable[..., PreparedRequest]", auth)  # ← any callable

            # Allow auth to make its changes.
            r = auth_handler(self)

            # Update self to reflect the auth changes.
            self.__dict__.update(r.__dict__)

            # Recompute Content-Length
            self.prepare_content_length(self.body)
A BEARER TOKEN STRATEGY
import requests
from requests.auth import AuthBase


class BearerAuth(AuthBase):
    def __init__(self, token: str) -> None:
        self.token = token

    def __call__(self, r: requests.PreparedRequest) -> requests.PreparedRequest:
        r.headers["Authorization"] = "Bearer " + self.token
        return r


requests.get("https://api.example.com/me", auth=BearerAuth("a-token"))
STEP 05 / 05

A FUNCTION IS A STRATEGY

Fig 4.5The accent row is the rule of thumb: start with a function.

In Python the smallest strategy is a function. sorted() takes one as key=, and a dict of functions keyed by name lets a setting or a request pick the algorithm. The sample prices an order three ways, in cents, and fails loudly on a plan it doesn’t know.

Move to a class when the strategy holds configuration or state, such as a token, or needs more than one method, the way Django’s password hashers need both encode() and verify().

ONE FUNCTION PER PRICING PLAN
from collections.abc import Callable

orders = [("ada", 4200), ("grace", 750), ("linus", 1900)]  # totals in cents
sorted(orders, key=lambda order: order[1])[0]  # → ('grace', 750)

Pricing = Callable[[int], int]
PRICING: dict[str, Pricing] = {
    "standard": lambda cents: cents,
    "member": lambda cents: cents * 9 // 10,
    "free_shipping": lambda cents: cents if cents >= 2500 else cents + 499,
}

def checkout(cents: int, plan: str) -> int:
    return PRICING[plan](cents)  # the caller picks the algorithm by name

checkout(4200, "member")  # → 3780
checkout(1900, "free_shipping")  # → 2399
checkout(1900, "vip")  # → KeyError

COMMON QUESTIONS

How is a strategy different from a callback?
In Python it often isn’t. A key function is a one-method strategy. The name says the callable decides how the work is done, where a callback is told that something happened.
Should the context check the strategy’s type?
Check that it can be called, not what class it is. requests accepts any callable, which is why a plain function works as auth.
Where should the choice of strategy live?
At the edges: a setting, a constructor argument or a request parameter. Django reads PASSWORD_HASHERS, and every call to make_password() follows it.

WHAT YOU NOW KNOW

  • A strategy is one variant of an algorithm behind a shared interface, and the context calls it without asking which.
  • requests calls any auth callable with the prepared request; a 2-tuple is the one shortcut, turned into HTTPBasicAuth.
  • In your code, start with a function and move to a class when the strategy needs state or a second method.
DEEP DIVE: also in Django, typing it, testing it, its cost, looks like

Also in Django: password hashers

The PASSWORD_HASHERS setting is a list of class paths. Django’s get_hashers() imports and instantiates each one once, and make_password() hashes with the first. At login, check_password() picks the hasher named in the stored hash, so old hashes still verify after you change the default, and Django can upgrade them on the next login.

DJANGO: THE HASHER FROM THE SETTING
# django/contrib/auth/hashers.py · Django 6.1.3 (trimmed)
def make_password(password, salt=None, hasher="default"):
    ...
    hasher = get_hasher(hasher)  # ← the strategy, chosen by the setting
    salt = salt or hasher.salt()
    return hasher.encode(password, salt)


@functools.lru_cache
def get_hashers():
    hashers = []
    for hasher_path in settings.PASSWORD_HASHERS:  # ← class paths, first is the default
        hasher_cls = import_string(hasher_path)
        hasher = hasher_cls()
        ...
        hashers.append(hasher)
    return hashers

Typing it

For a one-call strategy, Callable[[PreparedRequest], PreparedRequest] says enough. When a strategy has several methods or keyword arguments, declare a typing.Protocol: any class with matching methods type-checks, with no base class to inherit.

Testing it

Strategies make the context easy to test: pass a fake that records its calls or returns a fixed answer. The concrete strategies are tested on their own, with no context around them.

Its cost

The runtime cost is one call. The real cost is in reading: the algorithm isn’t where the context calls it, so a reader has to find out which strategy was passed. Name strategies after what they do, and keep the selection in one obvious place.

LOOKS LIKE

State
A strategy is chosen by the caller; a state object is swapped by the object itself as events arrive.
Who assigns it: a parameter from outside, or self.state = … inside a method.
Template Method
Strategy swaps the whole algorithm by composition; Template Method varies one step by inheritance.
An object passed in, against a subclass overriding a hook method.
Bridge (part 2)
A bridge splits two dimensions that vary together; a strategy varies one step.
Two hierarchies held by reference, against one interface with several implementations.

Template Method: fixed steps, one of them yours

A template method is a base class method that runs an algorithm’s steps in a fixed order and calls methods that subclasses fill in for the steps that vary. You have used one if you have written a logging handler, a Django management command or a unittest test case. Python’s logging package ships more than a dozen handlers, and their emit() methods leave filtering and the write lock to someone else. How does every handler get filtering and thread safety while writing one method?

THE PATTERN

you’ll write it sometimes

Fix the steps of an algorithm in a base class method, and let subclasses write only the steps that vary.

ROLES
  • template methodthe base class method that runs every step in a fixed order
  • hook methoda step the base class calls and a subclass writes
  • subclassone variant, which overrides the hooks and nothing else
REACH FOR IT WHEN
Many variants share the same steps, and getting the order or the locking wrong would be a bug.
SKIP IT WHEN
Only one step varies and has no state: take a function instead (Strategy).
HOW TO SPOT IT
A base method raising NotImplementedError, docs saying “subclasses must implement”, methods named handle, emit, run, setUp.
IN PYTHON
A class structure, built on inheritance; abc.abstractmethod makes a missing hook fail early.
SEEN IN
  • CPython 3.15 · Lib/logging/__init__.pyHandler.handle() filters and locks, then calls emit(), the one method a handler writes.
  • Django 6.1 · django/core/management/base.pyBaseCommand.execute() runs system checks, then handle(), the method every management command writes.
  • CPython 3.15 · Lib/socketserver.pyBaseRequestHandler calls setup(), handle() and finish() for each request; you write handle().
  • CPython 3.15 · Lib/unittest/case.pyTestCase.run() calls setUp(), your test method and tearDown(), in that order.
STEP 01 / 04

EVERY HANDLER WOULD REPEAT THE FILTER AND THE LOCK

Fig 5.1The bottom rows show the difference: a forgotten lock on the left, none to forget on the right.

A logging handler sends records somewhere: a stream, a file, a socket, a queue. Before writing, every handler must run its filters, and while writing it must hold a lock, or two threads logging at once interleave their lines.

If every handler did those steps itself, each would carry the same dozen lines, and one that forgot the lock would garble output only under load, the hardest kind of bug to reproduce.

STEP 02 / 04

THE BASE CLASS RUNS THE STEPS, A SUBCLASS FILLS ONE IN

Fig 5.2Follow the accent arrows: the caller enters the base class, and the base class calls down.

The template method lives in the base class and runs every step in a fixed order. Some steps it does itself; at the points that vary it calls a hook method on self, which a subclass overrides.

The control is inverted: callers call the base class, and the base class calls the subclass, never the other way round. A subclass can’t skip a step or reorder them, because it never sees the steps, only its hook.

STEP 03 / 04

LOGGING CALLS HANDLE(), YOU WRITE EMIT()

Fig 5.3Call 1 enters the template, call 2 is its hook; your handler’s emit() would be called the same way.

Handler.handle() is the template method. It runs the filters, returns early if a filter rejected the record, takes the handler’s lock and calls self.emit(record). The base emit() raises NotImplementedError, so a handler that forgets to write one fails on its first record.

StreamHandler.emit() formats the record and writes it to its stream. FileHandler and SysLogHandler write their own way, and so does a handler from another library; none of them needs to take the lock or run the filters, because handle() already has.

LOGGING: HANDLE() RUNS THE STEPS
# Lib/logging/__init__.py · CPython 3.15.2 (trimmed)
class Handler(Filterer):
    ...
    def emit(self, record):  # ← the hook: every subclass must write it
        raise NotImplementedError('emit must be implemented '
                                  'by Handler subclasses')

    def handle(self, record):  # ← the template method: the steps, in order
        rv = self.filter(record)  # ← step 1: filters
        if isinstance(rv, LogRecord):
            record = rv
        if rv:
            with self.lock:  # ← step 2: the I/O lock
                self.emit(record)  # ← step 3: the part the subclass writes
        return rv
STEP 04 / 04

OVERRIDE ONE HOOK, AND LEAVE THE TEMPLATE ALONE

Fig 5.4The left panel is how to use a template; the right is how to write one.

The sample collects records in a list, which is handy in tests. It overrides emit() only. The filter added with addFilter() runs inside handle(), so the card number never reaches the list, without a line about filtering in the class.

When the base class is your own, mark required hooks with @abc.abstractmethod so a missing one fails when the class is instantiated, not when it is first used. Give optional hooks an empty default body, the way socketserver’s setup() and finish() do nothing.

A HANDLER THAT WRITES ONLY EMIT()
import logging


class ListHandler(logging.Handler):
    def __init__(self) -> None:
        super().__init__()
        self.lines: list[str] = []

    def emit(self, record: logging.LogRecord) -> None:  # the only step you write
        self.lines.append(self.format(record))


log = logging.getLogger("shop")
log.propagate = False
handler = ListHandler()
handler.setFormatter(logging.Formatter("%(levelname)s %(message)s"))
handler.addFilter(lambda record: "card" not in record.getMessage())  # handle() runs it
log.addHandler(handler)
log.warning("cart is empty")
log.warning("card 4242 declined")
handler.lines  # → ['WARNING cart is empty']

COMMON QUESTIONS

Why not call the steps from the subclass?
Then every subclass repeats them and can get the order wrong. With a template method, the order lives in one place and is the same for all of them.
What’s the difference between a hook and an abstract method?
An abstract method must be overridden; a hook may be. Handler.emit() raises NotImplementedError, while socketserver’s setup() does nothing by default.

WHAT YOU NOW KNOW

  • A template method runs the steps in a fixed order and calls hook methods that subclasses write.
  • logging’s Handler.handle() filters and locks, then calls emit(), the one method a handler writes.
  • Override the hook, never the template; mark required hooks abstract so a missing one fails early.
DEEP DIVE: also in Django, hooks with a default, typing it, its cost, looks like

Also in Django: management commands

Every python manage.py command is a subclass of BaseCommand. Its execute() method sets up colours and output streams, runs system checks and migration checks, then calls handle(), the one method a command writes, and prints what handle() returns. Arguments come from another hook, add_arguments(), which the base class calls while building the parser.

DJANGO: EXECUTE() CALLS YOUR HANDLE()
# django/core/management/base.py · Django 6.1.3 (trimmed)
class BaseCommand:
    ...
    def execute(self, *args, **options):  # ← the template method
        ...
        if self.requires_system_checks and not options["skip_checks"]:
            check_kwargs = self.get_check_kwargs(options)
            self.check(**check_kwargs)
        if self.requires_migrations_checks:
            self.check_migrations()
        output = self.handle(*args, **options)  # ← your command goes here
        ...
        return output

    def handle(self, *args, **options):  # ← the hook
        raise NotImplementedError(
            "subclasses of BaseCommand must provide a handle() method"
        )

Hooks with a default

socketserver’s BaseRequestHandler calls setup(), handle() and finish() from its constructor. setup() and finish() are empty, so a subclass overrides them only when it needs to; StreamRequestHandler fills them in to wrap the socket in file objects, and your handle() just reads and writes.

Typing it

Derive the base class from abc.ABC and mark required hooks @abstractmethod: instantiating a subclass that misses one raises TypeError at once, and type checkers flag it before that. typing.final on the template method tells checkers it must not be overridden.

Its cost

Inheritance couples every subclass to the base class’s internals. A change to the steps in the base class changes every subclass’s behaviour, which is the point, and also the risk. Keep the template method short, document each hook, and prefer composition when the hooks multiply.

LOOKS LIKE

Strategy
Template Method varies a step by subclassing; Strategy passes the varying step in as an object.
A method a subclass overrides, against a parameter such as key= or auth=.
Factory Method (part 1)
A factory method is a template method whose varying step creates an object.
The hook returns a new instance, as get_form_class() does in Django.
Context managers
Both fix what runs before and after; a context manager wraps a block, a template wraps a hook method.
with and __exit__(), against a base class calling self.something().

Observer: announce an event, let anyone listen

Observer lets an object announce that something happened while any number of other objects react, without the announcer knowing who they are. Flask announces the start of every request through a signal, and error trackers, metrics code and your tests can all listen. Sentry’s Flask integration hooks into every request this way, and Flask’s source never mentions Sentry. How does one send() call reach listeners that Flask has never imported?

THE PATTERN

you’ll write it sometimes

Let an object announce events while any number of listeners subscribe to them, so the announcer never imports or calls the listeners by name.

ROLES
  • subjectkeeps the list of listeners and notifies them; in Python, usually a signal
  • observera function or object that subscribed and reacts
  • event sourcethe code where the event happens, which calls send()
REACH FOR IT WHEN
Code in other packages, or code not written yet, must react to an event without the sender changing.
SKIP IT WHEN
There is one listener and there will only ever be one: call it directly.
HOW TO SPOT IT
.connect(receiver), @receiver, .send(sender), add_done_callback(), objects named *_signal or methods named on_*.
IN PYTHON
A list of callables is enough inside one app; blinker and Django signals add weak references and sender filtering.
SEEN IN
  • blinker 1.9 · blinker/base.pySignal.send() calls every receiver connected for this sender or for any sender, and returns their results.
  • Flask 3.1 · flask/signals.pyFlask names ten signals in one blinker namespace and sends request_started on every request.
  • sentry-python 2.75 · sentry_sdk/integrations/flask.pySentry connects its own receivers to request_started and got_request_exception at startup.
  • Django 6.1 · django/dispatch/dispatcher.pypost_save and the other model signals call every receiver registered with connect() or @receiver.
STEP 01 / 04

THE SENDER WOULD HAVE TO IMPORT EVERY LISTENER

Fig 6.1The red arrow is the problem: every new listener needs the sender to change.

Many parts of a program care that a request started: an error tracker opens a transaction, a metrics library starts a timer, a test records which views ran. If the web framework called each of them, it would have to import them all.

A framework can’t do that. Flask doesn’t know which extensions you installed, and an extension written next year can’t appear in Flask’s source today.

STEP 02 / 04

LISTENERS SUBSCRIBE, THE SUBJECT ONLY ANNOUNCES

Fig 6.2The source talks to the signal only; the accent arrows fan out to whoever subscribed.

The subject keeps a list of observers. An observer subscribes by calling connect() with a function; the event source calls send(), and the subject calls every function on its list. The source and the observers never reference each other, only the subject.

In Python the subject is usually a module-level object called a signal, imported by both sides. The observers are plain functions that take the sender and any keyword arguments the signal sends.

STEP 03 / 04

FLASK SENDS REQUEST_STARTED, BLINKER CALLS EVERY RECEIVER

Fig 6.3Call 1 is Flask’s only line about listeners; call 2 fans out to every receiver.

Flask declares its signals in one module, inside a blinker Namespace, and sends request_started at the top of full_dispatch_request(). That one send() line is all Flask knows about the listeners.

blinker’s send() asks receivers_for() which receivers are connected to this sender or to any sender, calls each one with the sender and the keyword arguments, and returns a list of receiver and result pairs. Sentry’s integration connected its own function at startup; Flask never imports Sentry.

FLASK: NAME THE SIGNAL, THEN SEND IT
# src/flask/signals.py · Flask 3.1.3 (trimmed)
from blinker import Namespace

# This namespace is only for signals provided by Flask itself.
_signals = Namespace()
...
request_started = _signals.signal("request-started")  # ← the subject


# src/flask/app.py · Flask 3.1.3 (trimmed)
class Flask(App):
    ...
    def full_dispatch_request(self) -> Response:
        self._got_first_request = True

        try:
            request_started.send(self, _async_wrapper=self.ensure_sync)  # ← announce
            rv = self.preprocess_request()
            if rv is None:
                rv = self.dispatch_request()
        except Exception as e:
            rv = self.handle_user_exception(e)
        return self.finalize_request(rv)
BLINKER: SEND() CALLS EVERY RECEIVER
# src/blinker/base.py · blinker 1.9.0 (trimmed)
class Signal:
    ...
    def send(self, sender=None, /, *, _async_wrapper=None, **kwargs):
        if self.is_muted:
            return []

        results = []

        for receiver in self.receivers_for(sender):  # ← this sender and ANY
            if iscoroutinefunction(receiver):
                ...
                result = _async_wrapper(receiver)(sender, **kwargs)
            else:
                result = receiver(sender, **kwargs)  # ← notify one observer

            results.append((receiver, result))

        return results
STEP 04 / 04

A LIST OF CALLBACKS IS OFTEN ENOUGH

Fig 6.4Start on the left; move right when receivers live in other packages.

Inside one application, a signal can be a list of functions with connect() and send(). The sample returns each receiver’s result, as blinker does, and connect() returns the function so it also works as a decorator.

Reach for blinker or Django signals when receivers live in other packages, when they should disconnect themselves once garbage collected, or when you want to listen to one sender only.

A SIGNAL AS A LIST OF CALLBACKS
from collections.abc import Callable
from typing import Any


class Signal:
    def __init__(self) -> None:
        self.receivers: list[Callable[..., Any]] = []

    def connect(self, receiver: Callable[..., Any]) -> Callable[..., Any]:
        self.receivers.append(receiver)
        return receiver  # so connect also works as a decorator

    def send(self, sender: object, **kwargs: Any) -> list[Any]:
        return [receiver(sender, **kwargs) for receiver in self.receivers]


order_paid = Signal()

@order_paid.connect
def email_receipt(sender: object, order_id: int) -> str:
    return "emailed " + str(order_id)

@order_paid.connect
def add_points(sender: object, order_id: int) -> int:
    return order_id * 10

order_paid.send("checkout", order_id=7)  # → ['emailed 7', 70]

COMMON QUESTIONS

In what order are receivers called?
blinker documents the order as undefined. Don’t write receivers that depend on running before or after another one.
Should I use a signal or override a method?
Override when you own the class and want to change what it does. Use a signal to react from outside, as an extension does, without changing the sender.
Are Django signals the same idea?
Yes. post_save.connect(receiver, sender=Order) subscribes to saves of one model. Django’s Signal also has send_robust(), which catches receivers’ exceptions and returns them as results.

WHAT YOU NOW KNOW

  • A subject keeps a list of observers and calls each one when it sends; the sender never names them.
  • Flask sends request_started once per request, and blinker calls every receiver connected, Sentry’s included.
  • Inside one app a list of callbacks is enough; use blinker or Django signals when listeners live elsewhere.
DEEP DIVE: also in Sentry, weak references, testing it, its cost, looks like

Also in Sentry: listening to a framework from outside

sentry-python’s Flask integration runs setup_once() when you initialise the SDK. It connects three receivers to Flask’s signals: one to name the transaction when a request starts, one to capture exceptions, and one to add trace data when a template renders. Flask’s code is unchanged; uninstalling Sentry removes the receivers with it.

SENTRY: SUBSCRIBE TO FLASK’S SIGNALS
# sentry_sdk/integrations/flask.py · sentry-python 2.75.0 (trimmed)
class FlaskIntegration(Integration):
    @staticmethod
    def setup_once() -> None:
        ...
        before_render_template.connect(_add_sentry_trace)
        request_started.connect(_request_started)  # ← subscribe
        got_request_exception.connect(_capture_exception)
        ...


def _request_started(app: "Flask", **kwargs: "Any") -> None:  # ← an observer
    client = sentry_sdk.get_client()
    integration = client.get_integration(FlaskIntegration)
    if integration is None:
        return
    ...

Weak references

By default blinker and Django keep receivers through weak references, so connecting a bound method doesn’t keep its object alive forever. The cost is the surprise in the watch-out above: a receiver nothing else refers to is collected and silently stops receiving. Module-level functions are safe, because the module keeps them alive.

Testing it

blinker’s connected_to() connects a receiver for the length of a with block, which suits a test that records what was sent. Signal.muted() does the opposite, and stops a signal from calling anyone while a test runs.

Its cost

Every send() loops over the receivers, which is cheap. The real cost is tracing: reading Flask’s code doesn’t tell you what runs when a request starts, and a slow receiver slows every request. Log receiver timings when a signal sits on a hot path.

LOOKS LIKE

Plugin hooks
A hook is declared with a signature and its results are collected; a signal just announces.
hookspec and hookimpl markers, against connect() and send().
Mediator
A mediator holds the rules between parts; a subject only passes the news on.
Logic that decides what each part does next, against a loop that calls everyone.
Chain of Responsibility
A chain stops at the first handler that deals with the request; a signal calls every receiver.
A loop that returns early, against one that collects all results.

Plugin hooks: named points any package can extend

A plugin hook is a named point where a program calls every installed extension that implements it, and collects their answers. pytest is built this way: its own features and your conftest.py are plugins of the same kind. A coverage plugin, a parallel runner and your project can all add a line to the header pytest prints, and pytest’s source names none of them. How does one call in pytest reach functions in packages it has never imported by name?

THE PATTERN

you’ll write it sometimes

Name the points where a program can be extended, and call every installed plugin’s function at each point, collecting their answers.

ROLES
  • hostthe program that declares the hooks and calls them by name
  • plugin managerregisters plugins and calls every implementation of a hook
  • plugina module or object with functions named after the hooks it implements
REACH FOR IT WHEN
Packages you don’t control must add behaviour at defined points: options, reports, collection, output.
SKIP IT WHEN
All the extensions live in your own codebase: an ordinary function call or a Strategy is simpler.
HOW TO SPOT IT
HookspecMarker, HookimplMarker, functions named pytest_* or tox_*, pm.hook.name(**kwargs), an [project.entry-points.*] table.
IN PYTHON
A library: pluggy. Plugins are found through entry points in installed packages’ metadata.
SEEN IN
  • pluggy 1.7 · pluggy/_execution.py_multicall() calls every implementation of a hook, newest first, and collects the results that aren’t None.
  • pytest 9.2 · _pytest/hookspec.pypytest declares 52 hooks; its own features are plugins that implement them, like yours.
  • pytest 9.2 · _pytest/terminal.pyThe terminal reporter calls pytest_report_header and prints every line plugins return.
  • tox 4.67 · tox/plugin/__init__.pytox finds plugins through the tox entry point and calls hooks such as tox_add_option().
STEP 01 / 04

A TOOL CAN’T IMPORT PLUGINS IT HAS NEVER HEARD OF

Fig 7.1The crosses are the problem: pytest’s source can’t name packages that came after it.

A test runner is extended by people it will never meet. A coverage plugin wants a report at the end of the run, a parallel runner wants to change how tests are scheduled, and your project wants a line in the header saying which database the tests use.

pytest can’t import them by name, and a single callback slot isn’t enough, because several plugins want the same point and each has its own answer. The host needs named points, any number of implementations per point, and a way to find them.

STEP 02 / 04

THE HOST NAMES THE HOOKS, PLUGINS IMPLEMENT THEM

Fig 7.2The host calls one name; the accent arrows reach every plugin that registered a function for it.

The host declares each hook as a specification: a name and the arguments it will pass. A plugin is any module or object with a function of that name. The plugin manager registers plugins, and for each hook keeps the list of functions that implement it.

Calling a hook calls all of them. Arguments go by keyword, so an implementation can accept only the ones it needs, and the results come back as a list. For hooks marked firstresult, the first non-None answer wins and the rest are skipped.

STEP 03 / 04

PYTEST CALLS EVERY PYTEST_REPORT_HEADER IT FOUND

Fig 7.3Call 1 names the hook; call 2 reaches your conftest.py and pytest’s own plugins alike.

When a run starts, pytest’s terminal reporter calls config.hook.pytest_report_header(config=…, start_path=…). pluggy’s _multicall() calls every registered implementation, the most recently registered first, skips the ones that return None, and hands back the list. The reporter prints each line.

Your conftest.py is one of those plugins, and so are parts of pytest itself: the cache plugin adds a cachedir line and the terminal plugin adds rootdir. Core features and your project’s code go through the same door.

PYTEST CALLS THE HOOK BY NAME
# src/_pytest/terminal.py · pytest 9.2.0 (trimmed)
class TerminalReporter:
    ...
    def pytest_sessionstart(self, session: Session) -> None:
        ...
        if not self.no_header:
            ...
            lines = self.config.hook.pytest_report_header(  # ← one call, every plugin
                config=self.config, start_path=self.startpath
            )
            self._write_report_lines_from_hooks(lines)


# src/pluggy/_caller.py · pluggy 1.7.0 (trimmed)
class HookCaller:
    def __call__(self, **kwargs: object) -> Any:
        ...
        firstresult = self.spec.opts.get("firstresult", False) if self.spec else False
        # Copy because plugins may register other plugins during iteration (#438).
        return self._hookexec(
            self.name, self._hookimpls.copy(), call_kwargs, firstresult
        )
PLUGGY: CALL EVERY IMPLEMENTATION
# src/pluggy/_execution.py · pluggy 1.7.0 (trimmed)
def _multicall(hook_name, hook_impls, caller_kwargs, firstresult):
    results: list[object] = []
    ...
    try:  # run impl and wrapper setup functions in a loop
        for hook_impl in reversed(hook_impls):  # ← the newest plugin runs first
            try:
                args = [caller_kwargs[argname] for argname in hook_impl.argnames]
                ...
            except KeyError as e:
                ...
            if hook_impl.hookwrapper:
                ...
            elif hook_impl.wrapper:
                ...
            else:
                if kwargs is None:
                    res = hook_impl.function(*args)  # ← call one plugin
                else:
                    res = hook_impl.function(*args, **kwargs)
                if res is not None:
                    results.append(res)
                    if firstresult:  # halt further impl calls
                        break
    except BaseException as exc:
        exception = exc
    ...
A PLUGIN OF YOUR OWN
# conftest.py: pytest loads it and registers its hook functions as a plugin
def pytest_report_header(config):
    return "shop: tests run against the staging database"
STEP 04 / 04

DECLARE A SPEC, MARK AN IMPLEMENTATION, LET ENTRY POINTS FIND THEM

Fig 7.4The left panel is the idea; the accent panel is what to install when plugins come from other packages.

The idea fits in a dozen lines of Python: a dict from hook name to functions, called newest first, with an option to stop at the first answer. The first sample builds it and calls a hook both ways.

For plugins that live in other packages, use pluggy. It checks each implementation’s arguments against the spec when the plugin registers, orders calls with tryfirst and trylast, and loads plugins from an entry point group, so installing a package is all a user does to enable it.

A HOOK CALLER IN PLAIN PYTHON
from collections import defaultdict
from collections.abc import Callable
from typing import Any

impls: defaultdict[str, list[Callable[..., Any]]] = defaultdict(list)

def hookimpl(name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def register(fn: Callable[..., Any]) -> Callable[..., Any]:
        impls[name].append(fn)
        return fn
    return register

def call(name: str, *, firstresult: bool = False, **kwargs: Any) -> Any:
    results = [r for fn in reversed(impls[name]) if (r := fn(**kwargs)) is not None]
    return (results[0] if results else None) if firstresult else results

@hookimpl("report_header")
def project_line(project: str) -> str:
    return "project: " + project

@hookimpl("report_header")
def db_line(project: str) -> str:
    return "db: staging"

call("report_header", project="shop")  # → ['db: staging', 'project: shop']
call("report_header", firstresult=True, project="shop")  # → 'db: staging'
THE SAME WITH PLUGGY
import pluggy

hookspec = pluggy.HookspecMarker("shop")
hookimpl = pluggy.HookimplMarker("shop")


class ShopSpec:
    @hookspec
    def report_header(self, project: str) -> str:
        """Return a header line, or None."""


class DatabasePlugin:
    @hookimpl
    def report_header(self, project: str) -> str:
        return "db: staging"


pm = pluggy.PluginManager("shop")
pm.add_hookspecs(ShopSpec)
pm.register(DatabasePlugin())
pm.load_setuptools_entrypoints("shop")  # plugins from installed packages
lines = pm.hook.report_header(project="shop")  # one result per plugin

COMMON QUESTIONS

How does pytest find an installed plugin?
Through the pytest11 entry point in the package’s metadata. pluggy reads entry points for the group and imports each module it lists.
In what order do implementations run?
Newest registration first, unless an implementation is marked tryfirst or trylast. Wrappers run around all of them.

WHAT YOU NOW KNOW

  • A hook is a declared name with many implementations; calling it calls all of them and collects the answers.
  • pytest calls hook.pytest_report_header(), and pluggy reaches your conftest.py and pytest’s own plugins the same way.
  • Use pluggy and an entry point group when plugins live in other packages.
DEEP DIVE: also in tox, wrappers, historic hooks, its cost, looks like

Also in tox: the same library, another tool

tox builds its plugin system on pluggy too. A package that declares a tox entry point is loaded at startup, and its functions marked @impl are called at hooks such as tox_add_option, which lets a plugin add command-line flags. A toxfile.py next to your configuration works like pytest’s conftest.py.

Wrappers

An implementation marked wrapper=True is a generator. pluggy runs it up to its yield before the ordinary implementations. It then sends their result in at the yield, where the wrapper can change it or handle an exception. pytest’s capture plugin uses wrappers to collect output around every other plugin’s work.

Historic hooks

Some hooks must reach plugins registered after the call happened, such as configuration that late plugins still need. pluggy’s call_historic() remembers the call and replays it for every plugin registered later.

Its cost

Every hook call loops over its implementations and matches arguments by name, which pytest does thousands of times per run without trouble. The cost that matters is reading: behaviour arrives from packages you may not know are installed. pytest --trace-config lists the active plugins.

LOOKS LIKE

Observer
A signal announces and ignores answers; a hook has a declared signature and collects results.
connect() and send(), against hookspec, hookimpl and a list of return values.
Registry (part 1)
A registry looks one entry up by name; a hook calls every entry registered for the name.
registry[name] returns one class; pm.hook.name() returns a list.
Chain of Responsibility
A firstresult hook is a chain: implementations are tried in order until one answers.
The firstresult=True flag on the spec.

Command: an action you can store, run or reverse

Command turns an action into an object: something you can build now and run later, print, keep in a list or reverse. Alembic, the migration tool for SQLAlchemy, describes every schema change this way. The same add_column() line can change a live database, print the SQL for a reviewer or, read backwards by autogenerate, become the downgrade that removes the column. How does one line in a migration script do all three?

THE PATTERN

you’ll write it sometimes

Turn a request into an object that holds everything needed to carry it out, so it can be queued, logged, printed or undone.

ROLES
  • commandthe action as an object, with what it needs to run and to reverse itself
  • invokerruns commands without knowing what each one does
  • receiverthe object that does the real work; in Alembic, the database dialect’s DDL code
REACH FOR IT WHEN
Actions must be queued, retried, logged, previewed or undone, or built in one place and run in another.
SKIP IT WHEN
You only ever call the action once, right away: call the function.
HOW TO SPOT IT
Classes named *Op, *Operation, *Command or *Task; pairs such as forwards/backwards or do/undo; a list called history.
IN PYTHON
Often just a callable: functools.partial is a command with no undo. A class when it needs undo or inspection.
SEEN IN
  • Alembic 1.20 · alembic/operations/ops.pyop.add_column() builds an AddColumnOp; autogenerate reverses a list of them to write downgrade().
  • Django 6.1 · django/db/migrations/operations/fields.pyAddField’s database_forwards() and database_backwards() apply and undo one schema change.
  • CPython 3.15 · Lib/concurrent/futures/thread.pysubmit() wraps your function and arguments in a _WorkItem that a worker thread runs later.
STEP 01 / 04

A CHANGE RUN AT ONCE CAN’T BE PRINTED OR UNDONE

Fig 8.1The bottom rows: no reviewable script on the left, a generated downgrade on the right.

A migration could open a connection and run ALTER TABLE directly. That works once, on the database in front of you. You can’t print the SQL for a DBA to review first, you can’t compare the change with your models, and the downgrade has to be written and kept correct by hand.

All three need the change to exist as more than a call already made: a value describing what to do, which different code can run, print or reverse.

STEP 02 / 04

AN ACTION BECOMES AN OBJECT YOU CAN STORE, RUN OR REVERSE

Fig 8.2Follow the accent arrows: the invoker reads a command and acts on a receiver it never chose.

A command object holds a request and everything needed to carry it out: the table, the column, the options. The client builds it, the invoker runs it, and the receiver is the object that does the real work.

Because the command is data, it can wait in a queue, be written to a log, be shown to a person, or be run by a different invoker than the one that built it. If it also knows how to reverse itself, an undo stack is just a list of commands.

STEP 03 / 04

OP.ADD_COLUMN() BUILDS AN ADDCOLUMNOP, THEN INVOKES IT

Fig 8.3Calls 1 and 2 happen in your script; call 3 is the only step that touches the database.

In a migration script, op.add_column() is a class method of AddColumnOp. It builds the operation object with the table, the column and the options, and passes it to Operations.invoke(). invoke() looks up the function registered for that kind of operation, which calls add_column() on the dialect’s implementation.

Normally that implementation runs the DDL on a connection. With alembic upgrade head --sql, the same command reaches an implementation that writes the SQL out instead. The receiver changes; the command doesn’t.

ALEMBIC: THE CHANGE AS AN OBJECT
# alembic/operations/ops.py · Alembic 1.20.1 (trimmed)
class AddColumnOp(AlterTableOp):  # ← the command: a schema change as data
    """Represent an add column operation."""

    def __init__(self, table_name, column, *, schema=None, if_not_exists=None,
                 inline_references=None, inline_primary_key=None, **kw):
        super().__init__(table_name, schema=schema)
        self.column = column
        ...
    def reverse(self) -> DropColumnOp:  # ← the command that undoes it
        op = DropColumnOp.from_column_and_tablename(
            self.schema, self.table_name, self.column
        )
        op.if_exists = self.if_not_exists
        return op

    def to_diff_tuple(self):
        return ("add_column", self.schema, self.table_name, self.column)
ALEMBIC: BUILD IT, THEN INVOKE IT
# alembic/operations/ops.py · Alembic 1.20.1 (trimmed)
class AddColumnOp(AlterTableOp):
    ...
    @classmethod
    def add_column(cls, operations, table_name, column, *, schema=None,
                   if_not_exists=None, inline_references=None, inline_primary_key=None):
        ...
        op = cls(table_name, column, schema=schema, if_not_exists=if_not_exists,
                 inline_references=inline_references,
                 inline_primary_key=inline_primary_key)
        return operations.invoke(op)  # ← hand the command to the invoker


# alembic/operations/base.py · Alembic 1.20.1 (trimmed)
class AbstractOperations(util.ModuleClsProxy):
    def invoke(self, operation: MigrateOperation) -> Any:
        fn = self._to_impl.dispatch(  # ← the code registered for this kind of op
            operation, self.migration_context.impl.__dialect__
        )
        return fn(self, operation)
STEP 04 / 04

A COMMAND REMEMBERS WHAT ITS UNDO NEEDS

Fig 8.4The accent row is the top of the stack: the next undo runs its undo().

An undo stack is a list of command objects. Each one saves what its undo needs while it runs, here the old price, so undoing never has to guess. Popping the last command and calling its undo() reverses the newest change first.

When nothing needs undoing, a command can be a plain callable. functools.partial(send_email, to=user) is an action with its arguments, ready to queue, and an executor’s submit() wraps your function and arguments in a work item the same way.

COMMANDS WITH UNDO
from dataclasses import dataclass


@dataclass
class SetPrice:
    sku: str
    cents: int
    was: int = 0

    def do(self, prices: dict[str, int]) -> None:
        self.was = prices[self.sku]  # remember what undo needs
        prices[self.sku] = self.cents

    def undo(self, prices: dict[str, int]) -> None:
        prices[self.sku] = self.was


prices = {"tea": 1200}
history: list[SetPrice] = []
for command in (SetPrice("tea", 990), SetPrice("tea", 850)):
    command.do(prices)
    history.append(command)
prices  # → {'tea': 850}
history.pop().undo(prices)
prices  # → {'tea': 990}
history  # → [SetPrice(sku='tea', cents=990, was=1200)]

COMMON QUESTIONS

Is functools.partial a command?
Yes, one without undo: it freezes a function and its arguments into a single callable you can store and call later. That is all an executor’s queue needs.
How is Alembic’s reverse() different from undo()?
reverse() returns a new command instead of acting. Autogenerate collects the reversed operations and renders them as downgrade() code, which runs only if someone downgrades.

WHAT YOU NOW KNOW

  • A command is an action as an object, so it can be queued, logged, printed or reversed.
  • op.add_column() builds an AddColumnOp and invokes it; with --sql the same command is printed instead of run.
  • An undo stack is a list of commands that each saved what their undo needs.
DEEP DIVE: also in Alembic, Django and concurrent.futures, its cost, looks like

Also in Alembic: downgrade() written by reversing commands

When you run alembic revision --autogenerate, Alembic compares your models with the database and builds a list of operation objects for upgrade(). It then calls reverse() on each, in reverse order, to build downgrade(), and renders both lists as Python in the new script.

ALEMBIC: UNDO, LAST CHANGE FIRST
# alembic/operations/ops.py · Alembic 1.20.1 (trimmed)
class UpgradeOps(OpContainer):
    ...
    def reverse_into(self, downgrade_ops: DowngradeOps) -> DowngradeOps:
        downgrade_ops.ops[:] = list(
            reversed([op.reverse() for op in self.ops])  # ← undo, last change first
        )
        return downgrade_ops

Also in Django: forwards and backwards

Every Django migration is a list of operation objects. AddField’s database_forwards() adds the column and database_backwards() removes it, and each operation also updates an in-memory model of the schema, which is how Django knows what the database should look like without reading it.

Also in concurrent.futures: a queue of commands

ThreadPoolExecutor.submit() wraps your function and its arguments in a _WorkItem with a Future, and puts it on a queue. A worker thread takes it off later and calls run(), which sets the result or the exception on the Future you were given.

Its cost

A class per action is a lot of code where a function call would do. Pay it where commands are stored, inspected or reversed, as migrations are, and use callables everywhere else.

LOOKS LIKE

Strategy
A strategy is how to do a job; a command is a job to do, with its arguments.
A command carries data such as a table and a column; a strategy is passed the data.
Memento
A memento saves state to restore it; a command saves an action to replay or reverse.
getstate() and setstate(), against do() and undo() or forwards and backwards.

Chain of Responsibility: pass it on until someone answers

Chain of Responsibility passes a request along a line of handlers, each of which either deals with it or hands it to the next. Web middleware is this pattern: every Starlette and FastAPI app is a chain of handlers with your router at the end. A request with a forged Host header gets a 400 from TrustedHostMiddleware and never reaches your code. How does a handler in the middle of the chain answer a request before the router sees it?

THE PATTERN

you’ll write it often

Pass a request along a chain of handlers, each of which may answer it or hand it to the next, so the sender never picks the handler.

ROLES
  • handlerchecks the request, then answers it or calls the next handler
  • chainthe handlers in order; each one holds a reference to the next
  • clientsends the request to the first handler and gets back whichever answer comes
REACH FOR IT WHEN
Several independent checks or features may each answer a request, and their order matters.
SKIP IT WHEN
Every request needs every step, all the way through: that is a pipeline or a plain sequence of calls.
HOW TO SPOT IT
A self.app or get_response stored in the constructor, call_next, a MIDDLEWARE setting, a loop that returns the first result that isn’t None.
IN PYTHON
A class structure in frameworks, where each middleware holds the next app; a list of functions in your own code.
SEEN IN
  • Starlette 1.10 · starlette/middleware/trustedhost.pyTrustedHostMiddleware answers a request with a bad Host header itself, and passes the rest on.
  • Django 6.1 · django/core/handlers/base.pyload_middleware() wraps the view in each MIDDLEWARE class, last first; any of them may answer itself.
  • CPython 3.15 · Lib/urllib/request.pyOpenerDirector._call_chain() tries each handler until one returns something other than None.
  • CPython 3.15 · Lib/logging/__init__.pyA record goes to its logger’s handlers, then its parents’, until a logger’s propagate is False.
STEP 01 / 05

ONE HANDLER WOULD CHECK EVERYTHING

Fig 9.1The red row is the risk: one check forgotten in one endpoint.

Some work belongs to every request: rejecting a forged Host header, answering a browser’s CORS preflight, turning an uncaught exception into a 500 page instead of a dropped connection. If each endpoint did that work, every endpoint would carry the same checks.

Repeated checks drift apart, and the endpoint that forgets one is the hole. Some checks must also run before routing, when no endpoint has been chosen yet.

STEP 02 / 05

EACH HANDLER ANSWERS OR PASSES ON

Fig 9.2The accent handler shows the choice every handler has: pass on down, or answer back up.

Each handler holds a reference to the next one. When a request arrives, it either deals with it and returns an answer, or calls the next handler and returns whatever comes back. The client talks only to the first handler and never knows which one answered.

Order is the design. A handler early in the chain sees every request, so cheap checks that reject requests belong near the front, and the handler at the end is the one that always answers.

STEP 03 / 05

STARLETTE WRAPS YOUR ROUTER IN ITS MIDDLEWARE, LAST FIRST

Fig 9.3Every box has the same method; that shared signature is what lets them chain.

Every handler is an ASGI app: an async callable taking scope, receive and send. build_middleware_stack() starts with the router and wraps it in each middleware class, last one first, so each instance holds the next app in self.app. ServerErrorMiddleware ends up outermost and ExceptionMiddleware just above the router.

Your middleware goes in between, in the order you list it. Because every layer has the same signature, the server can’t tell a chain of five from a bare router.

STARLETTE: EACH LAYER HOLDS THE NEXT
# starlette/applications.py · Starlette 1.10.0 (trimmed)
class Starlette:
    ...
    def build_middleware_stack(self) -> ASGIApp:
        ...
        middleware = [Middleware(ServerErrorMiddleware, handler=error_handler, debug=debug)]
        if self.max_body_size is not None:
            middleware.append(Middleware(RequestBodyLimitMiddleware, max_body_size=self.max_body_size))
        middleware += self.user_middleware  # ← yours, in the order you listed them
        middleware.append(Middleware(ExceptionMiddleware, handlers=exception_handlers, debug=debug))

        app = self.router  # ← the last handler
        for cls, args, kwargs in reversed(middleware):
            app = cls(app, *args, **kwargs)  # ← each handler holds the next one
        return app
ADDING A HANDLER TO THE CHAIN
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.middleware.trustedhost import TrustedHostMiddleware
from starlette.responses import PlainTextResponse
from starlette.routing import Route


async def home(request):
    return PlainTextResponse("hello")


app = Starlette(
    routes=[Route("/", home)],
    middleware=[
        Middleware(TrustedHostMiddleware, allowed_hosts=["shop.example", "*.shop.example"]),
    ],
)
STEP 04 / 05

A BAD HOST HEADER NEVER REACHES THE ROUTER

Fig 9.4Calls 1 and 2 are the refused request; 3 to 6 are an ordinary one going all the way down.

TrustedHostMiddleware reads the Host header and compares it with each allowed pattern. On a match it awaits self.app(scope, receive, send), passing the request on unchanged. On no match it builds a PlainTextResponse with status 400, sends it itself, and nothing below it runs.

CORSMiddleware ends preflight requests the same way. Middleware also sees the way back up, because control returns through each layer’s await, which is how ServerErrorMiddleware catches a crash anywhere below it.

STARLETTE: PASS IT ON, OR ANSWER HERE
# starlette/middleware/trustedhost.py · Starlette 1.10.0 (trimmed)
class TrustedHostMiddleware:
    def __init__(self, app, allowed_hosts=None, www_redirect=True):
        ...
        self.app = app  # ← the next handler

    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        ...
        is_valid_host = False
        found_www_redirect = False
        for pattern in self.allowed_hosts:
            if host == pattern or (pattern.startswith("*") and host.endswith(pattern[1:])):
                is_valid_host = True
                break
            ...
        if is_valid_host:
            await self.app(scope, receive, send)  # ← pass it on
        else:
            response: Response
            if found_www_redirect and self.www_redirect:
                ...
            else:
                response = PlainTextResponse("Invalid host header", status_code=400)
            await response(scope, receive, send)  # ← or answer it here
STEP 05 / 05

A CHAIN CAN BE A LIST OF FUNCTIONS

Fig 9.5The accent panel is enough for your own code; the right one is how web frameworks do it.

In your own code a chain can be a list of functions, each returning an answer or None. A loop stops at the first answer. urllib.request’s OpenerDirector works exactly this way, and so does the sample, which blocks a host, serves a cached file or routes.

Use the onion form, where each handler wraps and calls the next, when a handler must also act after the rest have run: timing a request, adding a header to every response, or catching what failed further down.

A CHAIN AS A LIST OF FUNCTIONS
from collections.abc import Callable

Request = dict[str, str]

def blocked_host(request: Request) -> str | None:
    return "400 bad host" if request["host"] != "shop.example" else None

def cached(request: Request) -> str | None:
    return "200 from cache" if request["path"] == "/logo.png" else None

def route(request: Request) -> str | None:
    return "200 " + request["path"]

CHAIN: list[Callable[[Request], str | None]] = [blocked_host, cached, route]

def handle(request: Request) -> str:
    for handler in CHAIN:
        if (response := handler(request)) is not None:
            return response  # the first handler that answers ends the chain
    return "404"

handle({"host": "evil.example", "path": "/"})  # → '400 bad host'
handle({"host": "shop.example", "path": "/logo.png"})  # → '200 from cache'
handle({"host": "shop.example", "path": "/cart"})  # → '200 /cart'

COMMON QUESTIONS

Is middleware a decorator or a chain?
Both shapes at once. Each layer wraps the next like a decorator, and any layer may answer without calling it, which is the chain’s defining move.
How does Django’s middleware compare?
Each Django middleware receives get_response, the next handler, when it is built, and calls it for each request. Returning a response without calling it ends the chain, as in Starlette.
Is logging a chain?
Yes, of a looser kind. A record goes to its logger’s handlers, then to each parent logger’s, until one has propagate set to False.

WHAT YOU NOW KNOW

  • Each handler answers the request or passes it to the next one it holds; the client never knows which answered.
  • Starlette wraps the router in middleware, last first, and TrustedHostMiddleware answers a bad Host with a 400 itself.
  • In your own code, a list of functions that return None to pass on is a complete chain.
DEEP DIVE: also in urllib and Django, its cost, looks like

Also in urllib: the plainest chain

urllib.request’s OpenerDirector keeps handlers by protocol and stage. _call_chain() tries each in turn: a handler returns a response to end the chain, None to let the next one try, or raises to stop everything. Redirects and authentication are handlers in the same list.

URLLIB: THE FIRST ANSWER WINS
# Lib/urllib/request.py · CPython 3.15.2
class OpenerDirector:
    ...
    def _call_chain(self, chain, kind, meth_name, *args):
        # Handlers raise an exception if no one else should try to handle
        # the request, or return None if they can't but another handler
        # could.  Otherwise, they return the response.
        handlers = chain.get(kind, ())
        for handler in handlers:
            func = getattr(handler, meth_name)
            result = func(*args)
            if result is not None:
                return result

Also in Django: get_response

Django’s load_middleware() walks the MIDDLEWARE setting from the end, wrapping the view handler in each class and passing the wrapped handler to the next one’s constructor as get_response. A middleware such as the CSRF check returns a 403 response itself when it rejects the request.

Its cost

Every layer adds a call per request, and deep stacks make tracebacks long. The harder cost is order: a chain behaves differently when two layers swap places, and nothing in the code warns you. Keep the list in one place, and comment why each layer sits where it does.

LOOKS LIKE

Decorator (part 2)
A decorator always calls the object it wraps; a chain handler may stop and answer.
Look for a code path that returns without calling self.app().
Generator pipelines
A pipeline sends every item through every stage; a chain stops at the first handler that answers.
yield in each stage, against return in a handler.
Plugin hooks
A firstresult hook is a chain whose handlers come from installed packages.
firstresult=True on a hookspec.

State: behaviour that changes with the mode

State moves behaviour that depends on a mode into one object per mode, and swaps the object when the mode changes, so methods stop branching on the mode. HTTP/1.1 is full of modes: a connection waits for a request, reads a body framed one of three ways, waits for the response, maybe closes. h11, the HTTP/1.1 library inside uvicorn and httpcore, handles them with a table and a reader per state. How does h11 know how to read the next bytes, and what stops a client from sending a body before its headers?

THE PATTERN

you’ll write it sometimes

Give each mode of an object its own behaviour, and change the behaviour by changing the current state, so methods never branch on the mode.

ROLES
  • contextthe object whose behaviour depends on its state; it delegates to the current one
  • statethe behaviour for one mode; in h11, a reader for the bytes expected next
  • transitionsthe rules saying which event moves which state to which
REACH FOR IT WHEN
An object answers the same call differently by mode, and illegal moves between modes must be refused.
SKIP IT WHEN
Two modes and one method: an if is clearer than a class per mode.
HOW TO SPOT IT
A self.state or status field, dicts keyed by state, classes or readers per mode, an Enum next to a table of allowed moves.
IN PYTHON
Usually a table: an Enum for the states and a dict of allowed moves, with objects or functions where behaviour differs.
SEEN IN
  • h11 0.16 · h11/_state.pyConnectionState looks up the next state by role, state and event, and raises on anything else.
  • h11 0.16 · h11/_readers.pyREADERS maps each state to the function or reader class that parses bytes in that state.
  • transitions 0.9 · transitions/core.pyStates are objects with on_enter and on_exit callbacks, and a Machine moves a model between them.
  • CPython 3.15 · Lib/asyncio/futures.pyA Future keeps its state in one field, PENDING, CANCELLED or FINISHED, and each method checks it.
STEP 01 / 04

IF CHAINS ON A MODE SPREAD THROUGH EVERY METHOD

Fig 10.1The red row is the cost: one new state means editing every method.

A connection behaves differently depending on where it is in an exchange. Before the request line, incoming bytes are headers to parse; after a Content-Length header, they are a body of known size; with chunked encoding, they are chunks that each carry a length.

Written as if chains, every method checks the mode: the one that reads, the one that writes, the one that decides whether the connection can be reused. Each new mode touches all of them, and nothing stops a caller from doing something the current mode forbids.

STEP 02 / 04

THE CONTEXT HANDS THE WORK TO ITS CURRENT STATE

Fig 10.2The accent arrow is the delegation; the arrow over the top is where the state changes.

The context keeps a reference to its current state and passes the work to it. Each concrete state does that work the way its mode requires. When an event happens, the context looks up the next state in the rules and swaps the reference.

The rules are the other half of a state machine. A table of which event moves which state to which puts every legal move in one place, and anything missing from the table is refused.

STEP 03 / 04

H11 READS WITH THE CURRENT STATE’S READER

Fig 10.3Call 1 parses bytes the current state’s way; call 2 moves the state, which picks the next reader.

h11’s states are sentinel classes such as IDLE, SEND_BODY and DONE, one per side of the connection. ConnectionState applies an event by looking up the role, the state and the event type in EVENT_TRIGGERED_TRANSITIONS. A failed lookup raises LocalProtocolError, so a client can’t send Data before its Request.

After every change of state, Connection picks the reader for the new state from READERS. In SEND_BODY it builds a ContentLengthReader or a ChunkedReader, depending on the headers, and next_event() just calls whatever reader it holds.

H11: EVERY LEGAL MOVE IN ONE TABLE
# h11/_state.py · h11 0.16.0 (trimmed)
EVENT_TRIGGERED_TRANSITIONS: EventTransitionType = {
    CLIENT: {
        IDLE: {Request: SEND_BODY, ConnectionClosed: CLOSED},
        SEND_BODY: {Data: SEND_BODY, EndOfMessage: DONE},
        DONE: {ConnectionClosed: CLOSED},
        # … MUST_CLOSE, CLOSED, and the SERVER side
    },
}


class ConnectionState:
    def _fire_event_triggered_transitions(self, role, event_type):
        state = self.states[role]
        try:
            new_state = EVENT_TRIGGERED_TRANSITIONS[role][state][event_type]  # ← look it up
        except KeyError:
            ...
            raise LocalProtocolError(...)  # ← not in the table: an illegal move
        self.states[role] = new_state
H11: A READER FOR EACH STATE
# h11/_readers.py · h11 0.16.0 (trimmed)
READERS: ReadersType = {
    (CLIENT, IDLE): maybe_read_from_IDLE_client,
    (SERVER, IDLE): maybe_read_from_SEND_RESPONSE_server,
    (CLIENT, DONE): expect_nothing,
    # … and the other states that expect nothing
    SEND_BODY: {  # ← a reader object, chosen by how the body is framed
        "chunked": ChunkedReader,
        "content-length": ContentLengthReader,
        "http/1.0": Http10Reader,
    },
}


# h11/_connection.py · h11 0.16.0 (trimmed)
class Connection:
    def _get_io_object(self, role, event, io_dict):
        state = self._cstate.states[role]
        if state is SEND_BODY:
            framing_type, args = _body_framing(...)
            return io_dict[SEND_BODY][framing_type](*args)
        else:
            return io_dict.get((role, state))  # ← the reader for this state
STEP 04 / 04

A TABLE OF STATES IS OFTEN ENOUGH

Fig 10.4The red row isn’t in the dict; that absence is the rule.

Most state machines in application code need no class per state: an Enum for the states and a dict from state and event to the next state. The sample refuses to cancel a shipped order in one place, with no if per state.

Add state objects, or functions in a dict, when behaviour differs by mode and not only the next state, as h11’s readers do. A library such as transitions helps when you need callbacks on entering and leaving states.

A TRANSITION TABLE FOR ORDERS
from enum import Enum


class Order(Enum):
    NEW = "new"
    PAID = "paid"
    SHIPPED = "shipped"
    CANCELLED = "cancelled"


TRANSITIONS: dict[tuple[Order, str], Order] = {
    (Order.NEW, "pay"): Order.PAID,
    (Order.NEW, "cancel"): Order.CANCELLED,
    (Order.PAID, "ship"): Order.SHIPPED,
    (Order.PAID, "cancel"): Order.CANCELLED,
}

def fire(state: Order, event: str) -> Order:
    if (state, event) not in TRANSITIONS:
        raise ValueError("cannot " + event + " an order that is " + state.value)
    return TRANSITIONS[state, event]

fire(Order.NEW, "pay")  # → <Order.PAID: 'paid'>
fire(Order.SHIPPED, "cancel")  # → ValueError

COMMON QUESTIONS

How is State different from Strategy?
The structure is the same. A strategy is picked by the caller and rarely changes; a state changes itself as events arrive, by the object’s own rules.
Why are h11’s states classes rather than an Enum?
They are sentinels: unique objects compared with is, which print as their own name. In your own code an Enum member does the same job.

WHAT YOU NOW KNOW

  • A context delegates to its current state and swaps it when an event moves it to a new state.
  • h11 keeps every legal move in one table, and reads each state’s bytes with the reader that state selects.
  • In your code, an Enum and a dict of allowed moves are usually enough; illegal moves are missing keys.
DEEP DIVE: also in transitions and asyncio, typing it, testing it, looks like

Also in transitions: states with callbacks

The transitions library gives each state an object with on_enter and on_exit callbacks, and a Machine adds a method per trigger to your model: order.ship() moves the order if the current state allows it and runs the callbacks. It suits workflows where entering a state must also do something, such as send an email.

Also in asyncio: the if form, done right

An asyncio Future has three states and keeps them in one field. Each method checks it, set_result() raising InvalidStateError on a finished Future. With three states and a handful of methods, the if form is the simpler choice, and CPython makes it.

Typing it

An Enum names the states, and a match statement over it can end with assert_never() from typing, so a type checker reports a state you forgot to handle. A dict keyed by (State, str) documents the legal moves as data that tests can loop over.

Testing it

Test the table, not each method: loop over every state and every event, and assert each pair either moves to the expected state or is refused. A new row in the table then gets a test without anyone writing one.

LOOKS LIKE

Strategy
Same shape; a strategy is chosen from outside, a state is swapped from inside as events arrive.
Is there a transition table, or code that assigns self.state? Then it is State.
Command
Events sent to a state machine are often commands; the machine decides whether each is allowed now.
A command object passed to a method that checks the current state first.

Visitor: one operation over a whole tree

Visitor moves an operation out of the classes it works on and into a class of its own, with one method per node type, so new operations don’t touch the nodes. Template engines, linters and code formatters that work on a tree use it. Jinja2 parses a template into a tree of dozens of node types, then compiles it to Python with one class, CodeGenerator. How does CodeGenerator pick the right code for an If node or an Output node?

THE PATTERN

you’ll write it sometimes

Keep each operation over a tree in a class of its own, with one method per node type, chosen by the type of each node.

ROLES
  • visitorone operation over the tree, with a visit_ method per node type
  • elementa node type in the tree; it holds fields, not the operations
  • clientstarts the walk with visitor.visit(root)
REACH FOR IT WHEN
The node types are stable, and new operations over them keep arriving: compile, check, print, optimise.
SKIP IT WHEN
Node types change often and operations rarely: methods on the nodes are simpler.
HOW TO SPOT IT
Classes named *Visitor or *Transformer, methods named visit_ plus a class name, generic_visit(), @singledispatch.
IN PYTHON
Dispatch by name: getattr(self, "visit_" + class name). singledispatch and match do the same for plain types.
SEEN IN
  • Jinja2 3.1 · jinja2/visitor.pyNodeVisitor finds visit_ plus the node’s class name, and walks the children when there is no such method.
  • Jinja2 3.1 · jinja2/compiler.pyCodeGenerator compiles a template tree to Python source, one visit_ method per node type.
  • CPython 3.15 · Lib/ast.pyast.NodeVisitor and NodeTransformer walk Python’s own syntax tree the same way.
  • jmespath 1.1 · jmespath/visitor.pyjmespath’s Visitor caches the visit_ method it found for each node type.
STEP 01 / 04

A METHOD PER OPERATION ON EVERY NODE CLASS

Fig 11.1Compare the bottom rows: a new operation touches every node class, or none.

A template engine works on an abstract syntax tree: an If node holds a test and the bodies to render, an Output node holds things to print, and Jinja2 has dozens of such classes. It needs several operations over that tree: compile it to Python, track which names each block reads and writes, fold constant expressions.

As methods on the node classes, each operation would be spread over dozens of classes, and adding one would mean touching all of them. The code that compiles an If would sit next to the code that optimises it, far from the code that compiles everything else.

STEP 02 / 04

THE VISITOR PICKS A METHOD BY THE NODE’S TYPE

Fig 11.2The accent box holds the whole operation; the node boxes hold none of it.

A visitor is one operation over the tree, written as one class. It has a method per node type, and a visit() method that looks at a node’s type and calls the matching one. Each method handles its node and calls visit() on the children it cares about.

The textbook version needs every node class to call back into the visitor. Python skips that step: visit() builds the method name from the node’s class name with getattr(), so the nodes need no code for it at all.

STEP 03 / 04

JINJA2 COMPILES A TEMPLATE WITH VISIT_ METHODS

Fig 11.3Call 1 starts the walk; call 2 is one of many, each landing on a visit_ method.

get_visitor() is one line of getattr(): it looks for a method named visit_ followed by the node’s class name. visit() calls that method if it exists and falls back to generic_visit(), which visits every child.

CodeGenerator subclasses NodeVisitor and writes Python source as it goes. Its visit_If() writes the if keyword, visits the test node to write the condition, then visits the body. Other visitors walk the same tree: FrameSymbolVisitor finds the names a block uses, and the Optimizer folds constants.

JINJA2: A METHOD NAMED AFTER THE NODE
# src/jinja2/visitor.py · Jinja2 3.1.6 (trimmed)
class NodeVisitor:
    def get_visitor(self, node: Node) -> "t.Optional[VisitCallable]":
        return getattr(self, f"visit_{type(node).__name__}", None)  # ← visit_If, visit_Output

    def visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any:
        """Visit a node."""
        f = self.get_visitor(node)

        if f is not None:
            return f(node, *args, **kwargs)

        return self.generic_visit(node, *args, **kwargs)

    def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any:
        """Called if no explicit visitor function exists for a node."""
        for child_node in node.iter_child_nodes():  # ← no method: walk the children
            self.visit(child_node, *args, **kwargs)
JINJA2: COMPILING AN IF NODE
# src/jinja2/compiler.py · Jinja2 3.1.6 (trimmed)
class CodeGenerator(NodeVisitor):  # ← one visitor: Python source from the tree
    ...
    def visit_If(self, node: nodes.If, frame: Frame) -> None:
        if_frame = frame.soft()
        self.writeline("if ", node)
        self.visit(node.test, if_frame)  # ← the condition is another node
        self.write(":")
        self.indent()
        self.blockvisit(node.body, if_frame)
        self.outdent()
        for elif_ in node.elif_:
            ...
        if node.else_:
            self.writeline("else:")
            self.indent()
            self.blockvisit(node.else_, if_frame)
            self.outdent()
STEP 04 / 04

AST.NODEVISITOR FOR TREES, SINGLEDISPATCH FOR VALUES

Fig 11.4The left panel is for walking a tree; the right one handles one value of many possible types.

For Python source, the standard library gives you the base class: subclass ast.NodeVisitor, write visit_ methods for the node types you need, and call generic_visit() to keep walking. The first sample lists every function a line of code calls, nested calls included.

When there is no tree, only values of different types, use single dispatch. functools.singledispatch picks the implementation registered for the most specific type of the first argument, which is why True gives true, even though bool is a subclass of int.

A VISITOR OVER PYTHON’S OWN TREE
import ast


class CallNames(ast.NodeVisitor):
    def __init__(self) -> None:
        self.names: list[str] = []

    def visit_Call(self, node: ast.Call) -> None:  # chosen by the class name, Call
        if isinstance(node.func, ast.Name):
            self.names.append(node.func.id)
        self.generic_visit(node)  # keep walking into the arguments


visitor = CallNames()
visitor.visit(ast.parse("print(len(items), max(1, abs(x)))"))
visitor.names  # → ['print', 'len', 'max', 'abs']
ONE FUNCTION, ONE IMPLEMENTATION PER TYPE
from functools import singledispatch


@singledispatch
def to_json(value: object) -> str:
    raise TypeError("cannot encode " + type(value).__name__)

@to_json.register
def _(value: bool) -> str:
    return "true" if value else "false"

@to_json.register
def _(value: int) -> str:
    return str(value)

to_json(True), to_json(3)  # → ('true', '3')
to_json(1.5)  # → TypeError

COMMON QUESTIONS

Why not use isinstance() checks in one function?
That works for a few types. The chain grows with every node type and is repeated in every operation; a visitor keeps one method per type and lets the name do the lookup.
What does a NodeTransformer add?
Its visit_ methods return a node, which replaces the one visited, or None, which removes it. Jinja2’s Optimizer is one; many code-rewriting tools are built on ast’s.
Can a match statement replace a visitor?
For a small operation on one node, yes. A visitor still wins when it must walk a whole tree and keep state as it goes.

WHAT YOU NOW KNOW

  • A visitor is one operation over a tree, with a method per node type, chosen by the node’s class name.
  • Jinja2 compiles, tracks names and optimizes with three visitors over the same template tree.
  • Subclass ast.NodeVisitor to walk code, and use functools.singledispatch to handle values by type.
DEEP DIVE: also in CPython and jmespath, typing it, its cost, looks like

Also in CPython: ast.NodeTransformer

ast.NodeTransformer is a NodeVisitor whose visit_ methods return replacements. Return a new node and it takes the old one’s place; return None and the node is dropped. After changing a tree, ast.fix_missing_locations() fills in the line numbers that compile() needs.

Also in jmespath: a visitor that evaluates

jmespath, the query language behind the AWS CLI’s --query option, parses an expression into a tree of dicts and evaluates it with TreeInterpreter, a visitor whose visit_ methods return values. Its visit() caches the method for each node type, so the getattr() lookup happens once per type. Chapter 14 follows it in full.

Typing it

Name-based dispatch is invisible to type checkers: a misspelt visit_Cal is just an unused method. Type each visit_ method’s node parameter precisely, and add a test that walks a sample tree and asserts every method ran.

Its cost

One getattr() per node, which jmespath caches. The design cost is the opposite trade to methods on nodes: adding a node type means adding a method to every visitor, so the pattern fits trees whose node types rarely change.

LOOKS LIKE

Iterator
An iterator hands out nodes and does nothing with them; a visitor runs an operation on each.
next() returning items, against visit_ methods with bodies.
Interpreter
An interpreter evaluates a language’s tree; it is often written as a visitor.
visit_ methods that return values, such as jmespath’s TreeInterpreter.
Composite (part 2)
A composite is the tree; a visitor is an operation you run over it.
Children lists in the nodes, against a separate class walking them.

Memento: a snapshot only its owner can read

A memento is a snapshot of an object’s state that the object itself makes and later restores, while whoever keeps the snapshot never looks inside. Python’s random module offers one: getstate() returns the generator’s whole state, and setstate() puts it back, so a simulation can rewind and replay exactly the same numbers. How do you rewind a random number generator without knowing how it works?

THE PATTERN

you’ll mostly read it

Let an object hand out a snapshot of its own state and take it back later, without the holder depending on what is inside.

ROLES
  • originatorthe object; it makes snapshots of itself and restores from them
  • mementothe snapshot: data only the originator understands
  • caretakerkeeps snapshots and hands them back, but never reads them
REACH FOR IT WHEN
You need undo, a checkpoint, a replay, or to store an object’s state somewhere and rebuild it.
SKIP IT WHEN
The object is a plain dataclass with public fields: copy.copy() or dataclasses.replace() is enough.
HOW TO SPOT IT
getstate()/setstate() pairs, __getstate__/__setstate__, __reduce__, methods named checkpoint or snapshot.
IN PYTHON
Built into pickling: __getstate__ and __setstate__, with a default __getstate__ on every object since 3.11.
SEEN IN
  • CPython 3.15 · Lib/random.pyRandom.getstate() returns a version, the generator’s state and a cached value; setstate() restores them.
  • Django 6.1 · django/db/models/base.pyModel.__getstate__() chooses what a pickled instance holds; __setstate__() warns if it came from another Django version.
  • requests 2.34 · requests/sessions.pySession.__getstate__() saves only the attributes named in its __attrs__ list.
STEP 01 / 03

TO REWIND A GENERATOR, YOU WOULD NEED ITS INSIDES

Fig 12.1The red row is the trap: code that depends on another object’s internals.

A simulation, a game or a flaky test sometimes needs to go back: rerun the last hundred steps with exactly the same random numbers. Those numbers come from the generator’s internal state, and Python’s generator, the Mersenne Twister, keeps 624 words of it plus a position.

Copying those fields by hand ties your code to the algorithm. It breaks when CPython changes the generator, and it makes the caller decide which fields matter, which is the generator’s business.

STEP 02 / 03

RANDOM.GETSTATE() HANDS YOU AN OPAQUE SNAPSHOT

Fig 12.2The dashed arrow is the rule: the caretaker holds the snapshot and never opens it.

getstate() returns a tuple of three things: a format version, the generator’s internal state from its C code, and a cached value that gauss() uses. Your code keeps the tuple and later passes it to setstate(), which checks the version and restores everything.

The version number protects the snapshot. setstate() still accepts version 2 tuples from older Pythons, converting them, and raises ValueError on a version it doesn’t know. __reduce__() hands the same snapshot to pickle, so a pickled generator resumes where it stopped.

RANDOM: MAKE A SNAPSHOT, RESTORE ONE
# Lib/random.py · CPython 3.15.2 (trimmed)
class Random(_random.Random):
    VERSION = 3     # used by getstate/setstate
    ...
    def getstate(self):  # ← make a memento
        """Return internal state; can be passed to setstate() later."""
        return self.VERSION, super().getstate(), self.gauss_next

    def setstate(self, state):  # ← restore from one
        """Restore internal state from object returned by getstate()."""
        version = state[0]
        if version == 3:
            version, internalstate, self.gauss_next = state
            super().setstate(internalstate)
        ...

    def __reduce__(self):  # ← pickle stores the same memento
        return self.__class__, (), self.getstate()
STEP 03 / 03

GETSTATE, SETSTATE, AND PICKLE’S OWN HOOKS

Fig 12.3The left panel is the pattern called by name; the right is the same pattern, called by pickle.

The first sample saves a generator’s state, rolls five dice, restores the state and rolls the same five again. The snapshot’s first item is the version, 3, and its middle item holds 625 integers.

pickle uses the same idea under other names. It stores whatever __getstate__() returns and hands it to __setstate__() on load, so the second sample leaves a callback out of the snapshot and rebuilds it. Django’s Model and requests’ Session both define the pair.

SAVE, ROLL, REWIND, ROLL AGAIN
import random

rng = random.Random(42)
snapshot = rng.getstate()  # keep it; never look inside
first = [rng.randint(1, 6) for _ in range(5)]
rng.setstate(snapshot)
again = [rng.randint(1, 6) for _ in range(5)]
first == again  # → True
snapshot[0], len(snapshot[1])  # → (3, 625)
PICKLE STORES WHAT __GETSTATE__ RETURNS
import pickle
from collections.abc import Callable


class Cart:
    def __init__(self) -> None:
        self.items: list[str] = []
        self.on_change: Callable[[], None] = lambda: None  # pickle can’t store this

    def __getstate__(self) -> dict[str, list[str]]:
        return {"items": self.items}  # the memento: data only

    def __setstate__(self, state: dict[str, list[str]]) -> None:
        self.items = state["items"]
        self.on_change = lambda: None  # rebuilt, not stored


cart = Cart()
cart.items.append("tea")
pickle.loads(pickle.dumps(cart)).items  # → ['tea']

COMMON QUESTIONS

How is a memento different from a deep copy?
A deep copy is a whole new object. A memento is only the state, in a form the originator chooses, which may leave out locks, sockets and caches.
Does every object have a default __getstate__?
Yes, since Python 3.11. It returns the instance’s attributes, so you override it only to leave something out or to add a version.

WHAT YOU NOW KNOW

  • A memento is a snapshot an object makes of itself, held by someone who never reads it.
  • random.getstate() returns a version, 625 integers of generator state and a cached value; setstate() puts them back.
  • pickle’s __getstate__ and __setstate__ are the same pattern; use them to leave out what can’t be stored.
DEEP DIVE: also in Django, its cost, looks like

Also in Django: a memento with a version check

A Django model instance pickles its attributes and the Django version that saved it. On load, __setstate__() compares that version with the running one and warns when they differ, because a cached instance from before an upgrade may not match the new model’s fields.

DJANGO: A PICKLED MODEL KNOWS ITS VERSION
# django/db/models/base.py · Django 6.1.3 (trimmed)
class Model(AltersData, metaclass=ModelBase):
    ...
    def __getstate__(self):
        """Hook to allow choosing the attributes to pickle."""
        state = self.__dict__.copy()
        ...
        return state

    def __setstate__(self, state):
        pickled_version = state.get(DJANGO_VERSION_PICKLE_KEY)
        if pickled_version:
            if pickled_version != django.__version__:
                warnings.warn(  # ← a memento from another version
                    "Pickled model instance's Django version %s does not "
                    "match the current version %s."
                    % (pickled_version, django.__version__),
                    RuntimeWarning,
                    stacklevel=2,
                )
        ...
        self.__dict__.update(state)

Its cost

Snapshots cost memory, and an undo history of full snapshots grows fast. When states are large and changes small, store commands with their undo instead, and keep a full snapshot only every so often.

LOOKS LIKE

Command
A command records an action to redo or reverse; a memento records state to restore.
do() and undo(), against getstate() and setstate().
Prototype (part 1)
A prototype is a whole object you copy to make another; a memento is state you put back into the same one.
copy.copy() returning an object, against setstate() returning nothing.

Mediator: one object owns the rules between parts

A mediator is one object that owns the rules between a group of parts, so the parts talk to it and never to each other. A Django form is the everyday example: each field checks its own value, and the form checks the rules that span fields, such as a password matching its confirmation. No field holds a reference to another. Where does a rule that involves two fields live, if neither field may know about the other?

THE PATTERN

you’ll mostly read it

Put the rules between a group of parts in one object, so the parts talk to it and never to each other.

ROLES
  • mediatorowns every rule that involves more than one part
  • colleaguea part that knows only itself and the mediator
  • clienttalks to the mediator, never to the parts one by one
REACH FOR IT WHEN
Rules span several parts, and wiring the parts to each other would make each depend on the rest.
SKIP IT WHEN
Two parts and one rule: let one call the other.
HOW TO SPOT IT
A clean() or validate() that compares several fields, a controller every widget reports to, add_error(field, …).
IN PYTHON
A class structure, usually the form, controller or service object that already owns the parts.
SEEN IN
  • Django 6.1 · django/forms/forms.pyfull_clean() cleans each field alone, then calls clean() for the rules between fields.
  • Django 6.1 · django/forms/forms.pyadd_error() lets the form’s rules attach a message to any field, so fields never report on each other.
  • DRF 3.18 · rest_framework/serializers.pySerializer.run_validation() validates each field, then calls validate() for rules between fields.
STEP 01 / 03

FIELDS THAT CHECK EACH OTHER KNOW TOO MUCH

Fig 13.1Count the links: each new rule ties two more fields together.

Some rules involve more than one field: the confirmation must match the password, the check-out date must follow the check-in, a postcode’s format depends on the country. If fields checked these rules themselves, each would need references to the others.

Then no field can be reused alone, and every new rule ties two more fields together. A form with a dozen fields and a few such rules becomes a web, where changing one field means reading all its neighbours.

STEP 02 / 03

A DJANGO FORM CHECKS FIELDS ONE BY ONE, THEN TOGETHER

Fig 13.2Every arrow starts at the form; that is the whole pattern.

full_clean() runs in two passes. _clean_fields() asks each field to clean its own value, storing the result in cleaned_data and filing any ValidationError against that field. Then _clean_form() calls clean(), the method you override for cross-field validation.

In clean() the form compares values and calls add_error() to attach a message to the field the user should fix. Fields never see each other. The fit is partial: a form coordinates once per submission, where a classic mediator also relays changes between parts as they happen.

DJANGO: EACH FIELD, THEN THE RULES BETWEEN
# django/forms/forms.py · Django 6.1.3 (trimmed)
class BaseForm(RenderableFormMixin):
    ...
    def full_clean(self):
        ...
        self._clean_fields()  # ← each field checks only itself
        self._clean_form()  # ← then the rules between fields
        self._post_clean()

    def _clean_fields(self):
        for name, bf in self._bound_items():
            field = bf.field
            try:
                self.cleaned_data[name] = field._clean_bound_field(bf)
                ...
            except ValidationError as e:
                self.add_error(name, e)  # ← the form files the error

    def _clean_form(self):
        try:
            cleaned_data = self.clean()  # ← your cross-field rules
        except ValidationError as e:
            self.add_error(None, e)
        ...
A RULE BETWEEN TWO FIELDS
from django import forms


class SignupForm(forms.Form):
    email = forms.EmailField()
    password = forms.CharField(widget=forms.PasswordInput)
    confirm = forms.CharField(widget=forms.PasswordInput)

    def clean(self):
        cleaned = super().clean()
        if cleaned.get("password") != cleaned.get("confirm"):
            self.add_error("confirm", "The passwords don’t match.")  # routed to one field
        return cleaned
STEP 03 / 03

ONE OBJECT OWNS THE RULES BETWEEN THE PARTS

Fig 13.3The bottom rows: rules scattered on the left, gathered in one place on the right.

The sample builds the same shape without Django. Each DateField reports only whether it has a value; the BookingForm checks the rule between them, and says nothing about the dates’ order until both fields pass on their own.

Mediators are rarer in libraries than in applications, because they hold one application’s rules. You meet them as forms, as the controller behind a screen of widgets, and as the service object that coordinates several repositories.

A BOOKING FORM AS THE MEDIATOR
from dataclasses import dataclass, field
from datetime import date


@dataclass
class DateField:
    name: str
    value: date | None = None

    def errors(self) -> list[str]:  # checks only itself
        return [] if self.value else [self.name + " is required"]


@dataclass
class BookingForm:  # the mediator: owns every rule between fields
    check_in: DateField = field(default_factory=lambda: DateField("check_in"))
    check_out: DateField = field(default_factory=lambda: DateField("check_out"))

    def errors(self) -> list[str]:
        found = self.check_in.errors() + self.check_out.errors()
        if not found and self.check_out.value <= self.check_in.value:  # type: ignore[operator]
            found.append("check_out must be after check_in")
        return found


form = BookingForm()
form.errors()  # → ['check_in is required', 'check_out is required']
form.check_in.value, form.check_out.value = date(2026, 12, 3), date(2026, 12, 1)
form.errors()  # → ['check_out must be after check_in']

COMMON QUESTIONS

Isn’t this just Observer?
An observer only hears about events. A mediator decides what happens next, and its rules are the point.
How does it relate to a facade?
A facade simplifies how outsiders call a subsystem; a mediator organises how the parts inside work together.

WHAT YOU NOW KNOW

  • A mediator owns the rules between parts, so the parts talk only to it.
  • A Django form cleans each field alone, then runs clean() for rules between fields and files errors with add_error().
  • Keep rules between parts in the form, controller or service that already owns them.
DEEP DIVE: also in Django REST framework, its cost, looks like

Also in Django REST framework: validate()

A DRF serializer has the same two passes. to_internal_value() runs each field’s own validation, and then run_validation() calls validate(), the method you override for rules that involve several fields. Errors raised there are reported against the whole object unless you name a field.

DRF: EACH FIELD, THEN VALIDATE()
# rest_framework/serializers.py · Django REST framework 3.18.3 (trimmed)
class Serializer(BaseSerializer, metaclass=SerializerMetaclass):
    ...
    def run_validation(self, data=empty):
        ...
        value = self.to_internal_value(data)  # ← each field validates itself
        try:
            self.run_validators(value)
            value = self.validate(value)  # ← then your rules between fields
            assert value is not None, '.validate() should return the validated data'
        except (ValidationError, DjangoValidationError) as exc:
            raise ValidationError(detail=as_serializer_error(exc))

        return value
    ...
    def validate(self, attrs):
        return attrs

Its cost

Every rule between parts goes through one class, which makes the mediator the place every change lands. Keep its methods short, one rule each, and test each rule with the smallest set of parts that triggers it.

LOOKS LIKE

Observer
A subject announces and doesn’t care who listens; a mediator decides what each part does.
A send() loop, against a method full of rules about named parts.
Facade (part 2)
A facade faces outward and simplifies calls; a mediator faces inward and coordinates the parts.
Who calls it: outside code, or the parts themselves.

Interpreter: a grammar, a tree and an evaluator

Interpreter gives a small language a grammar, parses each sentence into a tree, and evaluates the tree node by node. You use one whenever you write a regular expression, a template or a query string. jmespath, the JSON query language behind the AWS CLI’s --query option and boto3’s paginators, is a small, readable example in pure Python. How does a string such as orders[?status == 'paid'].id become the list of paid order ids?

THE PATTERN

you’ll mostly read it

Define a small language by its grammar, parse each sentence into a tree, and evaluate the tree with one rule per node type.

ROLES
  • grammarthe rules for which strings are sentences and how they break into parts
  • parserturns a sentence into a tree of nodes
  • interpreterevaluates the tree, one method per node type
REACH FOR IT WHEN
Users, config files or other programs need to express queries or rules too varied for a fixed set of options.
SKIP IT WHEN
A dict of options, a list of filters or plain Python covers what users need.
HOW TO SPOT IT
A tokenizer, a parser class, node types, visit_ methods that return values, a compile() followed by search() or match().
IN PYTHON
re, string.Template and fnmatch are interpreters; ast.parse() lends you Python’s parser for a language of your own.
SEEN IN
  • jmespath 1.1 · jmespath/visitor.pyTreeInterpreter evaluates a parsed expression with one visit_ method per node type.
  • botocore 1.44 · botocore/paginate.pyA boto3 paginator’s search() compiles a JMESPath expression and runs it over every page.
  • CPython 3.15 · Lib/re/_parser.pyre.compile() parses a pattern into a tree, then compiles it to opcodes that a small engine in C runs.
  • CPython 3.15 · Lib/string/__init__.pystring.Template finds $name placeholders with a regular expression and substitutes their values.
STEP 01 / 03

A QUERY LANGUAGE BUILT FROM STRING SLICING BREAKS ON NESTING

Fig 14.1The red row is where slicing ends: the first expression inside an expression.

The AWS CLI prints large JSON documents, and users want only part of them: the ids of running instances, the names in a list. A language for that needs field access, indexing, filters with comparisons, and every combination of them.

Splitting the string on dots and special-casing brackets handles the first examples and fails on the first filter that contains a path. Every feature becomes another if, and the order in which they are checked starts to matter.

STEP 02 / 03

JMESPATH PARSES TO A TREE, THEN A VISITOR EVALUATES IT

Fig 14.2Each box names the visit_ method that evaluates it; the accent root drives the other five.

jmespath’s parser follows the language’s grammar and turns the expression into a tree of plain dicts, each with a type, children and sometimes a value. The filter becomes a filter_projection node with three children: what to filter, what to take from each match, and the condition, itself a comparator node.

Evaluation is a visitor. ParsedResult.search() hands the tree and your data to a TreeInterpreter, whose visit_filter_projection() evaluates the list, tests each element against the condition, and evaluates the id of each element that passes. On the sample data that is the ids of the two paid orders.

JMESPATH: EVALUATE THE TREE WITH A VISITOR
# jmespath/parser.py · jmespath 1.1.0 (trimmed)
class ParsedResult(object):
    def search(self, value, options=None):
        interpreter = visitor.TreeInterpreter(options)
        result = interpreter.visit(self.parsed, value)  # ← evaluate the tree
        return result


# jmespath/visitor.py · jmespath 1.1.0 (trimmed)
class TreeInterpreter(Visitor):
    ...
    def visit_field(self, node, value):
        try:
            return value.get(node['value'])  # ← a name looks itself up
        except AttributeError:
            return None
    ...
    def visit_filter_projection(self, node, value):
        base = self.visit(node['children'][0], value)  # ← the list to filter
        if not isinstance(base, list):
            return None
        comparator_node = node['children'][2]
        collected = []
        for element in base:
            if self._is_true(self.visit(comparator_node, element)):  # ← the condition
                current = self.visit(node['children'][1], element)
                if current is not None:
                    collected.append(current)
        return collected
PARSE ONCE, SEARCH OFTEN
import jmespath

data = {"orders": [
    {"id": 1, "status": "paid"},
    {"id": 2, "status": "new"},
    {"id": 3, "status": "paid"},
]}
expression = jmespath.compile("orders[?status == 'paid'].id")  # parse once
paid_ids = expression.search(data)  # evaluate as often as you like
# the AWS CLI runs the same language: aws ec2 describe-instances --query ...
STEP 03 / 03

A SMALL LANGUAGE CAN BORROW PYTHON’S PARSER

Fig 14.3Start on the left; the right is for languages whose syntax isn’t Python’s.

When your language looks like Python expressions, let ast.parse() do the parsing and write only the evaluator. The sample allows numbers, names and four operators, one match case per node type, and refuses everything else, including a call that would import a module.

That refusal is the point. eval() runs any Python, and an interpreter you write runs only the language you defined. When the syntax isn’t Python’s, write a tokenizer and a parser, or use a parsing library, and keep the evaluator a visitor.

AN EVALUATOR FOR A TINY LANGUAGE
import ast
import operator
from collections.abc import Callable

OPS: dict[type[ast.operator], Callable[[float, float], float]] = {
    ast.Add: operator.add, ast.Sub: operator.sub,
    ast.Mult: operator.mul, ast.Div: operator.truediv,
}

def evaluate(node: ast.expr, names: dict[str, float]) -> float:
    match node:  # one case per node type the language allows
        case ast.Constant(value=int() | float() as value):
            return value
        case ast.Name(id=name):
            return names[name]
        case ast.BinOp(left, op, right) if type(op) in OPS:
            return OPS[type(op)](evaluate(left, names), evaluate(right, names))
    raise ValueError("not allowed: " + type(node).__name__)

def run(source: str, **names: float) -> float:
    return evaluate(ast.parse(source, mode="eval").body, names)

run("price * qty - discount", price=9.5, qty=4, discount=3)  # → 35.0
run("__import__('os')")  # → ValueError

COMMON QUESTIONS

Is a regular expression an interpreter?
Yes. re.compile() parses the pattern into a tree and compiles it to opcodes for a small engine written in C, which then runs against your strings.
How does Interpreter differ from Visitor?
Interpreter is about the language: a grammar, a parser and an evaluator. The evaluator is usually a visitor, as jmespath’s is.

WHAT YOU NOW KNOW

  • An interpreter has a grammar, a parser that builds a tree, and an evaluator with a rule per node type.
  • jmespath parses a filter expression into a filter_projection tree, and TreeInterpreter evaluates it against your data.
  • For a small language of your own, borrow ast.parse() and evaluate only the node types you allow.
DEEP DIVE: also in boto3 and re, its cost, looks like

Also in boto3 and the AWS CLI

botocore’s PageIterator.search() compiles a JMESPath expression once and runs it over every page of results, yielding the matches. The AWS CLI’s --query option feeds your expression to the same library, so a query you test in Python works on the command line unchanged.

Also in re: an interpreter in two stages

re.compile() runs re._parser to build a tree of the pattern, then re._compiler to turn the tree into opcodes, and hands them to _sre, an engine in C that interprets them against your text. The re module caches compiled patterns, which is why calling re.match() with the same pattern in a loop stays fast.

Its cost

Walking a tree for every evaluation is slower than running compiled code. Interpreters that run hot compile their tree once, to Python source as Jinja2 does, or to opcodes as re does, and the visitor runs only at compile time.

LOOKS LIKE

Visitor
A visitor is any operation over a tree; an interpreter’s evaluator is the one that computes a value.
visit_ methods that return results, beside a parser and a grammar.
Composite (part 2)
The parsed tree is a composite; the interpreter is what gives it meaning.
Nodes with children, and a separate evaluate step.

The patterns in one table

Every pattern from the fourteen chapters: the problem it solves, the move it makes, where a real project uses it, and what Python gives you for it. Each name links to its chapter.

  1. problem
    loop over items without knowing how they’re stored
    move
    a separate object returns one item per next()
    seen in
    Django, Jinja2
    use when
    your object holds items others loop over
    Python
    built in; write __iter__ as a generator
  2. problem
    process a stream bigger than memory
    move
    generators pull from generators, one item at a time
    seen in
    requests, Django
    use when
    input is large, endless or slow
    Python
    functions with yield, and itertools
  3. problem
    cleanup must run even when the code raises
    move
    with calls __enter__() before and __exit__() after
    seen in
    contextlib, pytest
    use when
    something must be released or undone
    Python
    built in; @contextmanager and ExitStack
  4. problem
    swap an algorithm without changing the caller
    move
    pass the algorithm in behind a shared interface
    seen in
    requests, Django
    use when
    several ways to do one step exist
    Python
    usually a function: key=, auth=
  5. problem
    fixed steps, a few of which vary
    move
    a base method runs the steps and calls hooks
    seen in
    logging, Django
    use when
    variants must keep the order and the locking
    Python
    inheritance; abstractmethod for required hooks
  6. problem
    react to an event without the sender knowing you
    move
    listeners connect to a signal the sender sends
    seen in
    blinker, Flask
    use when
    code in other packages must react
    Python
    a list of callables, or blinker
  7. problem
    installed packages must extend a program
    move
    named hooks; every implementation is called
    seen in
    pluggy, pytest
    use when
    extensions come from packages you don’t control
    Python
    pluggy and entry points
  8. problem
    an action to queue, print or undo
    move
    the action becomes an object with its arguments
    seen in
    Alembic, Django
    use when
    actions are stored, previewed or reversed
    Python
    functools.partial; a class for undo
  9. problem
    many checks, any of which may answer
    move
    each handler answers or passes to the next
    seen in
    Starlette, urllib
    use when
    independent checks share every request
    Python
    middleware, or a list of functions
  10. problem
    behaviour depends on a mode
    move
    delegate to the current state; a table moves it
    seen in
    h11
    use when
    illegal moves between modes must be refused
    Python
    an Enum and a dict of allowed moves
  11. problem
    new operations over a fixed tree
    move
    a visit_ method per node type, found by name
    seen in
    Jinja2, ast
    use when
    operations change more often than node types
    Python
    ast.NodeVisitor; singledispatch for values
  12. problem
    save and restore state you mustn’t read
    move
    the object makes and restores its own snapshot
    seen in
    random, Django
    use when
    undo, checkpoints, replays
    Python
    __getstate__ and __setstate__
  13. problem
    rules that span several parts
    move
    one object owns the rules; parts talk only to it
    seen in
    Django, DRF
    use when
    parts would otherwise reference each other
    Python
    the form, controller or service you have
  14. problem
    a small language users write in
    move
    parse to a tree, evaluate each node type
    seen in
    jmespath, re
    use when
    options can’t express what users need
    Python
    ast.parse() plus your own evaluator

Telling them apart

Several of these patterns share a shape and differ in intent. These are the pairs people mix up most, including some from the other two parts.

TELLING THEM APART

Strategy and State
Same shape; the caller picks a strategy, the object swaps its own state.
A parameter from outside, against self.state = … inside a method.
Observer and Plugin hooks
A signal announces; a hook has a declared signature and collects results.
connect() and send(), against hookspec and hookimpl.
Chain and Decorator
A decorator always calls what it wraps; a chain handler may answer and stop.
A code path that returns without calling the next handler.
Template Method and Factory Method
A factory method is a template method whose varying step creates an object.
A hook that returns a new instance.
Command and Strategy
A strategy is how to do a job; a command is a job to do, with its arguments.
A command carries data; a strategy is handed the data.
Visitor and Interpreter
An interpreter’s evaluator is a visitor that computes a value from a language’s tree.
A grammar and a parser next to the visit_ methods.
Memento and Prototype
A prototype is copied to make a new object; a memento is put back into the same one.
copy.copy() returning an object, against setstate() returning nothing.
Mediator and Facade
A facade simplifies calls from outside; a mediator coordinates the parts inside.
Who calls it: outside code, or the parts themselves.

THREE THINGS TO KEEP

  • Behavioral patterns decide which object does each part of a job, and which ones only hear about it.
  • In Python a function is often the whole pattern. Reach for a class when it needs state.
  • Every pattern adds a step between the caller and the work. Add it where the flexibility pays for the reading.

Every for loop, with block and middleware stack you write is one of these patterns, named or not.