python-patterns

Python Patterns

Modern Python (3.10+) patterns for production code. Specific, opinionated, actionable.

When to Use

• Writing new Python modules or services
• Reviewing Python code for quality
• Modernizing Python 2-era or early Python 3 code
• Debugging subtle Python behavior

Type Hints

Always type hint public functions. It's documentation that tools can check.

# Good — clear what goes in and what comes out
def chunk_text(text: str, max_tokens: int = 512) -> list[str]:
    ...

# Good — complex types use type aliases
from typing import TypeAlias
JsonDict: TypeAlias = dict[str, "JsonValue"]
JsonValue: TypeAlias = str | int | float | bool | None | list["JsonValue"] | JsonDict

# Good — use | for unions (Python 3.10+), not Optional
def find_user(user_id: int) -> User | None:
    ...

# Good — use dataclass for structured data, not plain dicts
from dataclasses import dataclass, field

@dataclass
class EmbeddingResult:
    text: str
    vector: list[float]
    model: str
    token_count: int
    metadata: dict[str, str] = field(default_factory=dict)

Async Patterns

Use async for I/O-bound work. Don't use it for CPU-bound work.

import asyncio
import httpx

# Good — concurrent I/O with asyncio.gather
async def fetch_all(urls: list[str]) -> list[dict]:
    async with httpx.AsyncClient() as client:
        tasks = [client.get(url) for url in urls]
        responses = await asyncio.gather(*tasks, return_exceptions=True)
    return [r.json() for r in responses if not isinstance(r, Exception)]

# Good — async context manager for resource cleanup
class DatabasePool:
    async def __aenter__(self):
        self._conn = await connect()
        return self._conn

    async def __aexit__(self, *args):
        await self._conn.close()

# Good — async generator for streaming
async def stream_llm_response(prompt: str):
    async with client.stream("POST", "/completions", json={"prompt": prompt}) as r:
        async for chunk in r.aiter_lines():
            if chunk:
                yield chunk

# BAD — blocking I/O in async code
async def bad_example():
    import requests
    result = requests.get(url)  # blocks the event loop for everyone