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.