# Coding conventions cheat-sheet (extracted from Phase 1)

naming:
  module_files: snake_case (e.g., text_pipeline.py, ai_provider.py)
  functions: snake_case
  classes: PascalCase
  constants: UPPER_SNAKE_CASE
  module_singletons: module-level instances, named lower_snake (e.g., db = MotionDatabase())

imports:
  order:
    - stdlib
    - third-party
    - local application imports
  style:
    - group imports with a blank line between groups
    - prefer "from x import y" only when needed to avoid circular imports

types_and_dataclasses:
  - Use type hints broadly (functions, public APIs)
  - config should be a dataclass in config.py
  - Module-level singletons are allowed (but follow lifecycle rules in db_connection constraints)

tests:
  - pytest
  - tests/ directory, files named test_*.py
  - Use fixtures in tests/fixtures and conftest.py
  - Tests expect raises(...) for invalid input or ProviderError

error_handling:
  - Prefer explicit exceptions (ValueError, ProviderError)
  - Avoid overly-broad except: clauses (see anti-patterns)