Python Patterns

Python Patterns

When to use this skill

Use this skill when writing or reviewing modern Python code and you want consistent patterns for typing, async, structure, packaging, and correctness (especially in services, scripts, CLIs, and data tooling).

Core patterns

Type hints everywhere (and no bare dict)

Rules:

• Prefer precise types: dict[str, Any], Mapping[str, Any], Sequence[T]
• Use Any only at boundaries, not internally
• Prefer Protocol or TypedDict for structural contracts

Examples:

from typing import Any

def parse_payload(payload: dict[str, Any]) -> tuple[str, int]:
    user_id = str(payload["user_id"])
    count = int(payload.get("count", 0))
    return user_id, count

Dataclasses vs TypedDict vs Pydantic

Use:

• dataclass: internal domain objects, immutable-ish value types
• TypedDict: dict-shaped external payloads (JSON) when you want structural typing
• pydantic (or similar): validation + parsing at boundaries (API inputs, configs)

Pattern:

• Validate at boundaries, keep core logic on typed objects.

Async patterns (avoid mixing sync/async)

Rules:

• If a call chain is async, keep it async.
• Do not call blocking IO inside async def (use thread pool or async libs).
• Prefer httpx.AsyncClient, async DB drivers, async queues.

Good:

import httpx

async def fetch_json(url: str) -> dict[str, object]:
    async with httpx.AsyncClient(timeout=10.0) as client:
        r = await client.get(url)
        r.raise_for_status()
        return r.json()

Avoid:

• requests inside async def
• time.sleep() inside async code (use await asyncio.sleep())

Project structure (src/ layout)

Prefer:

repo/
  pyproject.toml
  src/
    mypkg/
      __init__.py
      api.py
      services/
      cli/
  tests/

Benefits:

• prevents accidental imports from repo root
• clearer packaging boundaries

Virtual environments

Preferred:

• uv for fast env + installs (if team agrees)

Fallback:

• python -m venv .venv
• pip install -r requirements.txt