Python Clean Code Standards

# Python Clean Code Standards

## Style
- Follow PEP 8 with 88-char line length (Black formatter default).
- Use type hints on all function signatures and class attributes.
- Use `from __future__ import annotations` for forward references.
- Prefer f-strings over .format() or % formatting.

## Data Structures
- Use `@dataclass` or Pydantic `BaseModel` for structured data. Not dicts.
- Use `NamedTuple` for immutable records.
- Use `Enum` for fixed sets of values. Never bare strings.
- Prefer list/dict/set comprehensions over map/filter with lambdas.

## Functions
- Functions do one thing. If the name needs "and", split it.
- Maximum 3 positional parameters. Use keyword-only (`*`) for the rest.
- Return early to avoid deep nesting. No else-after-return.
- Use `@functools.cache` for pure functions with repeated calls.

## Error Handling
- Catch specific exceptions, never bare `except:`.
- Use custom exception classes for domain errors.
- Context managers (`with`) for resource cleanup. Always.
- Log exceptions with `logger.exception()` to include traceback.

## Async
- Use `async/await` for I/O-bound work. Never for CPU-bound.
- Use `asyncio.gather()` for concurrent I/O tasks.
- Never mix sync and async database drivers.
- Use `asyncio.TaskGroup` (3.11+) for structured concurrency.

## Testing
- Use pytest, not unittest.
- Fixtures for setup/teardown. Parametrize for multiple inputs.
- Use `freezegun` for time-dependent tests.
- `pytest-asyncio` for async test functions.