python

Python Implementation Patterns

Use this skill for idiomatic, modern Python (3.11+) with a bias toward correctness, explicit typing, and maintainability. This skill covers core language patterns; sub-skills handle domain-specific concerns.

Delivery Workflow

Use the checklist below and track progress:

Python progress:
- [ ] Step 1: Discover project conventions, Python version, and dependency management
- [ ] Step 2: Model data shapes and error types explicitly
- [ ] Step 3: Implement with proper typing and async discipline
- [ ] Step 4: Handle errors, logging, and side effects explicitly
- [ ] Step 5: Verify with tests, type checking, and linting

Platform Assumptions

• Target Python 3.11+ by default.
• Use uv for dependency and environment management when available; fall back to poetry if the project already uses it.
• Do not add compatibility shims for Python 3.9 or earlier unless the project explicitly requires it.
• Prefer standard library solutions before reaching for third-party packages.

Typing and Data Modeling

• Annotate all function signatures — parameters and return types.
• Use Pydantic v2 for data validation and serialization at system boundaries (API input, config, external data).
• Use dataclasses for internal data carriers that do not need validation logic.
• Use TypedDict for typed dict shapes that are not instantiated as classes.
• Use Protocol for structural typing instead of ABC when duck typing is the right model.
• Avoid Any except at explicit untyped boundaries; document why when used.
• Use NewType or domain-specific aliases to prevent primitive obsession in critical paths.

# Prefer explicit types at boundaries
from pydantic import BaseModel

class DocumentChunk(BaseModel):
    chunk_id: str
    content: str
    embedding_model: str
    token_count: int

# Not this
def process(data: dict) -> dict: ...

Async and Concurrency

• Use asyncio for I/O-bound work; use concurrent.futures.ProcessPoolExecutor for CPU-bound work.
• Never call blocking I/O inside an async function — use asyncio.to_thread or a thread executor.
• Keep async context managers explicit for resources that require teardown.
• Prefer structured concurrency with asyncio.TaskGroup (Python 3.11+) over bare asyncio.gather when error propagation matters.
• Do not use asyncio.create_task fire-and-forget without a way to observe failure.