python-patterns

Python Patterns

Write Python that is type-safe, testable, and a joy to maintain.

Core Principles

1. Explicit Over Implicit

Use type hints. Avoid *args and **kwargs when named parameters work. Favor clear interfaces over dynamic flexibility.

2. Composition Over Inheritance

Python's multiple inheritance is powerful but dangerous. Prefer composition and protocols over deep class hierarchies.

3. Async Done Right

Async is a tool for I/O-bound workloads, not a universal default. Use synchronous code for CPU-bound tasks, async for network calls and file I/O.

4. Test-First for Critical Paths

Your business logic should be testable without mocks. Use dependency injection. Keep I/O at the boundaries.

---

Python Maturity Model

Level	Typing	Async	Testing	Structure
1: Script	No type hints	sync only	Manual testing	Single file
2: Module	Basic types (str, int)	Basic asyncio	pytest, some coverage	Package with __init__.py
3: Package	Full type hints with mypy	Async with proper patterns	pytest + fixtures + mocking	src-layout, entry points
4: Service	Generics, Protocols, TypedDict	Structured concurrency	Property-based, integration tests	Domain-driven structure
5: Library	Precise types, variance annotations	Trio / anyio	Fuzzing, benchmark tests	Public API surface explicit

Target: Level 3+ for production services.

---

Actionable Guidance

Type Hints

Basic Patterns

from typing import Optional, Union, Sequence, TypeVar, Protocol, Any
from datetime import datetime

# Function signatures
def process_user(
    user_id: int,
    name: str,
    email: Optional[str] = None,
    tags: list[str] | None = None,  # Python 3.10+ union syntax
) -> dict[str, Any]:
    ...

# TypedDict for structured dicts
class UserData(TypedDict, total=False):
    id: int
    name: str
    email: str
    created_at: datetime

# Protocols (structural subtyping)
class Drawable(Protocol):
    def draw(self, context: Any) -> None: ...

def render(item: Drawable) -> None:
    item.draw(...)  # Any object with draw() method works