Patterns

Key features

• Factory: one function or method that returns a concrete instance based on input, hiding the class name from the caller
• Abstract Factory: an interface with one creation method per product; each concrete factory implementation produces a matching family
• Both patterns exist so calling code depends on an interface (Notifier, Button) rather than a concrete class name
• Factory picks ONE product from a type; Abstract Factory picks a whole SET of related products that must stay consistent with each other
• Adding a new variant means adding one new factory/class, not editing every place the old ones were instantiated

Command

def notifier_factory(channel: str):
    if channel == "email":
        return EmailNotifier()
    if channel == "sms":
        return SmsNotifier()
    raise ValueError(f"unknown channel: {channel}")

notifier = notifier_factory("email")
notifier.send("your order shipped")

Key features

• Every strategy implements the same interface (here, one calculate method), so the context class can call any of them identically
• The context (Cart) holds a strategy object and delegates to it — it never branches on a type flag itself
• Swapping cart.shipping_strategy = ExpressShipping() changes behavior at runtime with zero changes to Cart
• Adding a new algorithm means adding one new class, not editing an existing if/elif chain
• A plain function passed as a callable can substitute for a one-method Strategy class in Python — the pattern does not require a class at all

Command

class ShippingStrategy(ABC):
    @abstractmethod
    def calculate(self, weight_kg): ...

class Cart:
    def __init__(self, shipping_strategy: ShippingStrategy):
        self.shipping_strategy = shipping_strategy

    def shipping_cost(self, weight_kg):
        return self.shipping_strategy.calculate(weight_kg)

Key features

• Adapter wraps an existing object and exposes the interface callers expect, translating each call internally
• Used when the incompatible class is third-party or legacy — code you cannot or should not modify directly
• The adapter implements the TARGET interface (what callers want) and holds a reference to the ADAPTEE (what actually does the work)
• Callers depend only on the target interface — swapping the legacy client for a modern one later means writing a new adapter, not touching every caller
• Different from Decorator: Adapter changes an interface to match what is expected; Decorator keeps the same interface and adds behavior

Command

class JsonDataSource(ABC):
    @abstractmethod
    def get_items(self): ...

class LegacyXmlAdapter(JsonDataSource):
    def __init__(self, legacy_parser):
        self.legacy_parser = legacy_parser

    def get_items(self):
        raw = self.legacy_parser.fetch_data()
        return [parse(raw)]

Key features

• A repository exposes collection-like methods — get_by_id, add, list, remove — never raw queries
• Business logic depends on the repository interface, never on a specific database driver or ORM query
• An in-memory repository implementing the same interface makes unit tests run with no real database
• A repository usually manages one aggregate/entity type — UserRepository, OrderRepository — not the whole schema
• Different from a generic Adapter: a repository's shape is always collection-like (get/add/remove), an Adapter's shape can be anything the target interface requires

Command

class UserRepository(ABC):
    @abstractmethod
    def get_by_id(self, user_id): ...
    @abstractmethod
    def add(self, user): ...

class InMemoryUserRepository(UserRepository):
    def __init__(self):
        self._users = {}

    def get_by_id(self, user_id):
        return self._users.get(user_id)

    def add(self, user):
        self._users[user["id"]] = user

Key features

• A service method is named after a use case — place_order, cancel_subscription — not a CRUD verb like update
• The service coordinates repositories and domain objects; it does not contain SQL, and does not duplicate rules the domain object already enforces
• Multiple entry points (a web view, a CLI command, a background job) call the same service method instead of re-implementing the use case
• A service layer sits between the presentation layer and the domain/repository layer in a layered architecture
• Not every CRUD operation needs a service — a thin layer that adds nothing beyond repository.add() is unnecessary indirection

Command

class OrderPlacementService:
    def __init__(self, product_repository):
        self.product_repository = product_repository

    def place_order(self, sku, quantity):
        available = self.product_repository.get_stock(sku)
        if quantity > available:
            raise InsufficientStockError(f"only {available} left of {sku}")
        self.product_repository.decrement_stock(sku, quantity)
        return {"sku": sku, "quantity": quantity, "status": "placed"}

Key features

• The receiving class depends on an interface (anything with a .log() method), not a concrete class it constructs itself
• Most common form in Python: constructor injection — pass the dependency as an __init__ argument
• Makes unit testing straightforward — pass a fake/mock implementation instead of the real dependency
• This entry is deliberately brief — the full treatment (dependency inversion, constructor vs. function injection, containers, FastAPI's Depends(), testing with injected dependencies) lives in the roadmap's own dedicated Dependency Injection section

Command

class ReportGenerator:
    def __init__(self, logger):   # injected, not created internally
        self.logger = logger

    def generate(self):
        self.logger.log("report generated")

ReportGenerator(ConsoleLogger()).generate()

Key features

• A subject keeps a list of observers and calls a shared method (here, update) on each one when state changes
• attach() registers an observer; notify() (usually called from inside the subject after a state change) loops over all attached observers
• The subject depends only on the observer interface (update), never on which concrete observer classes are attached
• Adding a new reaction to an event means adding a new observer class and attaching it — the subject never changes
• Python's standard library uses the same idea under different names — logging handlers, and any callback list, are Observer variants

Command

class Subject:
    def __init__(self):
        self._observers = []

    def attach(self, observer):
        self._observers.append(observer)

    def notify(self, event):
        for observer in self._observers:
            observer.update(event)

Key features

• A command object bundles a request into execute() (and often undo()), instead of the caller invoking the action directly
• The invoker (RemoteControl) stores and runs commands without knowing what each one actually does
• Storing executed commands in a list is what makes undo, redo, and replay possible — the action itself becomes data
• Different from a plain function callback: a command instance can carry both the forward action AND the reverse action together
• Common uses: undo/redo stacks, task queues, transactional operations, GUI button/menu actions

Command

class Command(ABC):
    @abstractmethod
    def execute(self): ...
    @abstractmethod
    def undo(self): ...

class TurnOnCommand(Command):
    def __init__(self, light):
        self.light = light

    def execute(self):
        return self.light.turn_on()

    def undo(self):
        return self.light.turn_off()

Key features

• Each builder method sets one piece of configuration and returns self, which is what makes the calls chainable
• Nothing is constructed until .build() is called — that is the one place required fields get validated
• Builder replaces a constructor with many optional parameters, where remembering positional order becomes error-prone
• The builder and the object it builds are usually two separate classes — HttpRequestBuilder builds an HttpRequest, it isn't one
• Different from Factory: Factory picks WHICH class to instantiate; Builder assembles a complex instance of one class piece by piece

Command

class HttpRequestBuilder:
    def __init__(self):
        self._request = HttpRequest()

    def method(self, method):
        self._request.method = method
        return self             # enables chaining

    def build(self):
        if self._request.url is None:
            raise ValueError("url is required")
        return self._request

Key features

• A decorator implements the SAME interface as the object it wraps, so wrapped and unwrapped objects are used identically by callers
• Each decorator holds a reference to the object it wraps and delegates to it, adding its own behavior before or after
• Decorators can be stacked — WithCaramel(WithMilk(Espresso())) — without a combinatorial explosion of classes for every combination
• Different from Python's @decorator syntax: this pattern wraps an OBJECT at runtime; @decorator wraps a FUNCTION at definition time — related idea, different mechanism
• Different from Adapter: Decorator keeps the interface the SAME and adds behavior; Adapter CHANGES the interface to match what callers expect

Command

class CoffeeAddOn(Coffee):
    def __init__(self, coffee: Coffee):
        self._coffee = coffee

class WithMilk(CoffeeAddOn):
    def cost(self):
        return self._coffee.cost() + 0.50

    def description(self):
        return self._coffee.description() + " + milk"