Python Design Patterns

Pythonic adaptations of GoF patterns, SOLID principles, and anti-patterns to avoid.

"Modern Python simply avoids the problems that the old design patterns were meant to solve." — Brandon Rhodes, PyCon 2025

Prerequisites: from __future__ import annotations, collections.abc for Callable/Iterator, structlog for logging.

Pattern Decision Table

Need	Pattern	Python Idiom
Multiple creation strategies	Factory	Function or `@classmethod`
Complex object, many options	Builder	`dataclass` + `replace()`
Interchangeable algorithms	Strategy	Pass `Callable`
Event notification	Observer	Callback list
Lazy sequences	Iterator	Generator (`yield`)
Tree structures	Composite	Recursive dataclass
Memory optimization	Flyweight	`__slots__`, `lru_cache`
Interface conversion	Adapter	Wrapper class
Cross-cutting concerns	Decorator	`@decorator`
State machines	State	Dict mapping or `match`
Shared configuration	Global Object	Module-level instance
Callbacks with state	Prebound Method	`obj.method`, `partial`
None is valid value	Sentinel	`_MISSING = object()`

SOLID Quick Reference

Principle	Violation Sign	Fix
Single Responsibility	"Manager" class	Split into focused classes
Open-Closed	`if/elif` on types	Dict of handlers + Protocol
Liskov Substitution	`NotImplementedError`	Composition over inheritance
Interface Segregation	Unused interface methods	Small `Protocol` classes
Dependency Inversion	`self.db = PostgresDB()`	Constructor injection

Anti-Patterns

Anti-Pattern	Why Bad	Pythonic Alternative
Singleton class	Modules ARE singletons	Module-level instance
Deep inheritance	Coupling, diamond problem	Composition + Protocol
Java getters/setters	Boilerplate	Direct attrs, `@property`
God Object	Untestable, SRP violation	Focused services
Method without self	Unnecessary class	Module-level function
Premature patterns	Over-engineering	YAGNI - add when needed

Key Patterns

Factory & Strategy

# Factory: function returning instance
def create_connection(db_type: str) -> Connection:
    return {"postgres": PostgresConn, "sqlite": SQLiteConn}[db_type]()

# Strategy: pass functions, not strategy objects
def calculate_total(items: list[Item], pricing: Callable[[float], float]) -> float:
    return sum(pricing(i.price) for i in items)

Observer & Decorator

# Observer: callback list
@dataclass
class EventEmitter:
    _listeners: dict[str, list[Callable]] = field(default_factory=dict)
    def on(self, event: str, fn: Callable) -> None:
        self._listeners.setdefault(event, []).append(fn)
    def emit(self, event: str, *args) -> None:
        for fn in self._listeners.get(event, []): fn(*args)

# Decorator: @wraps for cross-cutting concerns
def timing(func):
    @wraps(func)
    def wrapper(*a, **kw):
        start = perf_counter()
        result = func(*a, **kw)
        log.info("timing", elapsed=perf_counter() - start)
        return result
    return wrapper

Global Object & Sentinel

# Global Object: module-level instance (not singleton class)
_config: Config | None = None
def get_config() -> Config:
    global _config
    if _config is None: _config = Config.from_env()
    return _config

# Sentinel: distinguish None from "not provided"
_MISSING = object()
def get(key: str, default: object = _MISSING) -> object:
    if (v := cache.get(key)) is not None: return v
    if default is _MISSING: raise KeyError(key)
    return default

Reference Files

File	Content
`references/patterns.md`	All GoF patterns with examples
`references/solid-anti.md`	SOLID principles + anti-patterns
`references/python-idioms.md`	Global Object, Prebound Method, Sentinel

ADR-014 - Design decisions
ADR-013 - Immutability patterns

python-design-patterns