Design Patterns

Proven solutions to recurring design problems. Use patterns when you recognize the problem — not to show cleverness.

Warning: Patterns add complexity. Only apply when the problem is actually recurring.

Creational — How Objects Are Created

Factory Method

Problem: Caller shouldn't know which concrete class to instantiate.

# Instead of: notification = EmailNotification(msg)
# Use: notification = NotificationFactory.create("email", msg)

class NotificationFactory:
    _registry = {"email": EmailNotification, "sms": SMSNotification}

    @classmethod
    def create(cls, type: str, message: str) -> Notification:
        if type not in cls._registry:
            raise ValueError(f"Unknown notification type: {type}")
        return cls._registry[type](message)

Builder

Problem: Object needs many optional parameters (telescoping constructor).

# Instead of: Query(table, cols, where, limit, offset, order, joins)
query = (QueryBuilder("users")
    .select("id", "name")
    .where("active = true")
    .limit(10)
    .build())

Singleton

Problem: Exactly one instance needed (config, connection pool).

class Config:
    _instance = None

    def __new__(cls):
        if not cls._instance:
            cls._instance = super().__new__(cls)
        return cls._instance

⚠️ The naive implementation above is NOT thread-safe. Use a lock in multi-threaded environments:

import threading
class Config:
    _instance = None
    _lock = threading.Lock()
    def __new__(cls):
        with cls._lock:
            if not cls._instance:
                cls._instance = super().__new__(cls)
        return cls._instance

⚠️ Avoid for anything testable — singletons make tests order-dependent.

Structural — How Objects Are Composed

Adapter

Problem: Make an incompatible interface work with existing code.

# Legacy system returns dict, new system expects object
class LegacyUserAdapter:
    def __init__(self, legacy_dict: dict):
        self._data = legacy_dict

    @property
    def id(self): return self._data["user_id"]
    @property
    def name(self): return self._data["full_name"]

Decorator

Problem: Add behavior without modifying the original class.

class LoggingRepository:
    def __init__(self, repo: UserRepository):
        self._repo = repo

    def find(self, id: int) -> User:
        logger.info(f"Finding user {id}")
        result = self._repo.find(id)
        logger.info(f"Found: {result}")
        return result

Repository

Problem: Decouple business logic from data access.

class UserRepository(ABC):
    @abstractmethod
    def find_by_id(self, id: int) -> User: ...
    @abstractmethod
    def save(self, user: User) -> None: ...

class SQLUserRepository(UserRepository):
    def find_by_id(self, id: int) -> User:
        row = self.db.query("SELECT * FROM users WHERE id = ?", id)
        return User.from_row(row)

Facade

Problem: Callers must coordinate a complex subsystem — simplify behind one interface.

class PaymentFacade:
    def charge(self, amount: float, card: Card) -> Receipt:
        self.fraud_detector.check(card)       # complex internals
        receipt = self.stripe.charge(amount, card)
        self.audit_logger.log(receipt)
        return receipt
# Caller only knows: facade.charge(amount, card)

Proxy

Problem: Control access to an object — add caching, auth, or lazy loading transparently.

class CachedUserRepository:
    def __init__(self, repo: UserRepository, cache: Cache):
        self._repo, self._cache = repo, cache

    def find_by_id(self, id: int) -> User:
        if user := self._cache.get(f"user:{id}"):
            return user
        user = self._repo.find_by_id(id)
        self._cache.set(f"user:{id}", user)
        return user

Behavioral — How Objects Communicate

Observer / Event

Problem: Notify multiple objects when state changes, without tight coupling.

class EventBus:
    def __init__(self):
        self._handlers: dict[str, list[Callable]] = {}

    def subscribe(self, event: str, handler: Callable): ...
    def publish(self, event: str, data: any): ...

# OrderService doesn't know about EmailService, InventoryService, etc.
event_bus.publish("order.placed", order)

Strategy

Problem: Swap algorithms at runtime.

class PaymentProcessor:
    def __init__(self, strategy: PaymentStrategy):
        self._strategy = strategy

    def charge(self, amount: float):
        self._strategy.process(amount)  # Stripe, PayPal, Crypto — all the same interface

Command

Problem: Encapsulate requests as objects (for undo/queue/logging).

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

class MoveCommand(Command):
    def execute(self): self.piece.move(self.destination)
    def undo(self): self.piece.move(self.origin)

Template Method

Problem: An algorithm's structure is fixed, but specific steps vary per subclass.

class ReportGenerator(ABC):
    def generate(self) -> str:       # fixed skeleton — not overridable
        data = self.fetch_data()
        return self.format(data)

    @abstractmethod
    def fetch_data(self) -> list: ...

    @abstractmethod
    def format(self, data: list) -> str: ...

class CSVReport(ReportGenerator):
    def fetch_data(self): return db.query("SELECT ...")
    def format(self, data): return ",".join(str(r) for r in data)

Pattern Selection Guide

When to Refactor TO a Pattern

Anti-Pattern Warning