Reference document · quick lookup

Patterns Quick Reference

Patterns are names for recurring structures that solve recurring problems. Learn to recognise them emerging in code before you learn to apply them deliberately — which is why every entry here leads with the problem, not the shape. Terms follow the glossary; each pattern names the lesson that teaches it.

Find the pattern by the problem

Patterns are answers. Read this column first — if none of these is your problem, none of these is your pattern.

Structural patterns

Shapes that decide who talks to whom.

Discount = Callable[[Money], Money]        # the interface, at its cheapest

def final_price(total: Money, discount: Discount) -> Money:
    return total - discount(total)         # the context never names a variant

class PaymentGateway(Protocol):            # your interface, your words
    def charge(self, amount: Money, token: str) -> str: ...

class StripeAdapter:                       # implements yours, speaks theirs
    def charge(self, amount: Money, token: str) -> str:
        return self._client.payment_intents.create(...).id

class CheckoutFacade:
    def place_order(self, cart: Cart, token: str) -> Order:
        self._inventory.reserve(cart)                    # one coarse method…
        charge = self._payments.charge(cart.total, token)
        return self._shipping.create(cart, charge)       # …four subsystems hidden

class RetryingGateway:                     # same port in, same port out
    def __init__(self, inner: PaymentGateway, attempts: int = 3) -> None:
        self._inner, self._attempts = inner, attempts

    def charge(self, amount: Money, token: str) -> str:
        ...                                # retry here; the caller sees no change

# domain/ports.py — everything the core needs from the world
class Clock(Protocol):
    def now(self) -> datetime: ...

class OrderRepository(Protocol):
    def get(self, order_id: str) -> Order: ...

def build_app() -> App:                    # the only function that says "Stripe"
    clock: Clock = SystemClock()
    orders: OrderRepository = SqlAlchemyOrderRepository(make_session())
    return App(checkout=CheckoutService(orders, StripeAdapter(stripe), clock))

Domain patterns

Shapes that keep the rules true.

@dataclass(frozen=True)
class Money:
    amount: Decimal
    currency: str

    def __post_init__(self) -> None:
        if self.amount < 0:                # a broken Money cannot be built
            raise ValueError("amount cannot be negative")

class Order:                               # the root guards the cluster
    def add_line(self, product: ProductId, qty: int, price: Money) -> None:
        if self._status is not Status.PENDING:
            raise OrderLockedError()       # nobody reaches into _lines directly
        self._lines.append(OrderLine(product, qty, price))

class OrderRepository(Protocol):
    def get(self, order_id: str) -> Order: ...
    def add(self, order: Order) -> None: ...
    def get_unshipped(self) -> list[Order]: ...   # a question, not a filter

with uow:                                  # one transaction boundary
    order = uow.orders.get(order_id)
    order.confirm()
    uow.commit()                           # all of it, or none of it

def to_domain(payload: dict) -> Shipment:  # their words in, ours out
    return Shipment(
        tracking=TrackingCode(payload["trkNo"]),
        status=STATUS_MAP[payload["st"]],  # "st" never reaches the domain
    )

System patterns

Shapes for data and time.

class MessageBus:
    def publish(self, event: object) -> None:
        for handler in self._handlers.get(type(event), []):
            handler(event)

bus.register(OrderConfirmed, send_confirmation_email)   # wiring, not domain

def error_entries(lines: Iterable[str]) -> Iterator[LogEntry]:
    for line in lines:                     # iterable in, items out
        entry = parse(line)
        if entry.level == "ERROR":
            yield entry

total = summarize(error_entries(read_lines("app.log")))   # flat memory

async def refund_order(order: Order, gateway: AsyncGateway) -> Refund:
    result = await gateway.refund(order.total)      # I/O at the edge
    return apply_refund(order, result.refund_id)    # sync rule, no loop needed

Evolution patterns

Shapes for changing a system that is already running.

def route(request: Request) -> Response:
    if request.path in MIGRATED:           # the fig grows one route at a time
        return new_system.handle(request)
    return legacy.handle(request)

class StockService(Protocol):              # 1. insert the seam
    def reserve(self, sku: str, qty: int) -> None: ...

# 2. migrate all 40 callers to the seam    3. swap the implementation
# 4. delete the old one — every step small, reviewable, reversible

# 1. expand    add `delivery_address`; write BOTH; keep reading `address`
# 2. backfill  copy history in idempotent batches
# 3. switch    read `delivery_address`; still writing both
# 4. contract  stop writing `address`; only then drop it

def checkout(cart: Cart, flags: FeatureFlags) -> Order:
    if flags.is_enabled("new_pricing"):    # deployed, not yet released
        return new_pricing_checkout(cart)
    return legacy_checkout(cart)

def test_characterizes_current_behaviour() -> None:
    # not "what it should do" — what it does today, locked before the refactor
    assert legacy_total(SAMPLE_ORDER) == Decimal("118.60")

Sources: Gamma et al., Design Patterns; Freeman et al., Head First Design Patterns; Evans, Domain-Driven Design; Vernon, Implementing DDD; Percival & Gregory, Architecture Patterns with Python; Cockburn, hexagonal architecture; Fowler, Strangler Fig, Branch by Abstraction and Parallel Change; Feathers, Working Effectively with Legacy Code.