Skip to content

Code style

SAE Books is a Python codebase. We use the standard tools.

Tooling

  • Formatter: ruff format (Black-equivalent, 100 cols)
  • Linter: ruff check
  • Types: mypy in strict mode for new modules; legacy modules opted-in incrementally
  • Tests: pytest with pytest-asyncio

Run lint and type checks before opening a PR:

make lint       # ruff check .
make typecheck  # mypy saebooks

Imports

from __future__ import annotations

at the top of every file. Then standard library, then third-party, then saebooks.*. ruff handles the sort.

Naming

  • snake_case for functions, variables, modules.
  • PascalCase for classes.
  • SCREAMING_SNAKE_CASE for module-level constants.
  • Async functions get a async_ prefix only when there is a same-named sync sibling and the disambiguation matters. Otherwise just def vs async def.

Docstrings

Module and public-API docstrings are required. They should explain why the code exists, not what each line does. Don't waste lines on restating the function signature.

Errors

  • Validate at boundaries (HTTP, external APIs). Trust internal calls.
  • Raise HTTPException from FastAPI handlers; raise typed exceptions from service layers and let the handler translate.
  • Don't catch and re-log; let exceptions propagate to the global handler unless you can do something useful with them.

Tests

See Testing.