# Python Standards

Extends common coding standards with Python-specific rules.

## Type Hints

- Type hints on all function signatures (PEP 484), return types always specified
- `from __future__ import annotations` for modern syntax
- `TypeAlias` for complex definitions, `TypeVar` or PEP 695 for generics

## Data Structures

- `dataclasses` (prefer `frozen=True`) for simple data containers
- Pydantic `BaseModel` for validated data (API boundaries, config, external input)
- Named tuples or dataclasses over plain tuples/dicts

## Environment and Dependencies

- Virtual environments mandatory (`venv`, `poetry`, or `uv`)
- Pin all versions in lock files; `pyproject.toml` as single config source
- Separate dev from production dependencies

## Formatting and Linting

- **Ruff** for linting and formatting (line length: 88)
- Import sorting: stdlib → third-party → local

## File System and I/O

- `pathlib.Path` over `os.path`
- Context managers for all resource management
- `async`/`await` for I/O-bound operations
- Never bare `open()` without `with`

## Documentation

- Google style docstrings (Args / Returns / Raises) on all public functions, classes, modules

## Error Handling

- Custom exception classes for domain errors
- Never bare `except:` — always specify the type
- `raise ... from e` to preserve chains
- Return typed results over raising for expected cases