Skip to content

AGENTS.md

Latest commit

 

History

History
60 lines (45 loc) · 2.66 KB

AGENTS.md

File metadata and controls

60 lines (45 loc) · 2.66 KB
Raw

AGENTS.md

Commands

  • Lint: uv run ruff check src/ tests/
  • Format: uv run ruff format src/ tests/
  • Test: uv run pytest tests/ -v
  • Type check: uv run ty
  • Docs: uv run mkdocs build --strict
  • All checks before commit: uv run ruff format src/ tests/ && uv run ruff check src/ tests/ && uv run pytest tests/ -v

Use uv for everything. Never use pip or venv directly.

Directory Structure

  • src/tollkeeper/ — library source (hatchling src layout)
    • core.py — Tollkeeper entry point, TollkeeperSession state machine, CheckReport, AuditFailedError
    • backends/ — Backend ABC (base.py), CsvBackend, IcebergBackend (stub)
    • checks/ — BaseCheck ABC, CheckResult, Polars DQ checks
    • signals/ — SignalStore ABC, SqliteSignalStore, DbApiSignalStore
  • tests/ — pytest suite, mirrors source modules (test_core.py, test_csv_backend.py, etc.)
  • docs/ — mkdocs-material source

Architecture

  • Fluent API: Tollkeeper(backend).table(t).write(fn).audit(checks).publish()
  • TollkeeperSession is a state machine. Transitions: created → written → audited → published/rolled-back. publish() and rollback() are terminal, idempotent, mutually exclusive. Respect _published and _rolled_back flags.
  • Backend ABC is the extension point for storage. Do not add storage logic to core.py.
  • BaseCheck ABC is the extension point for DQ. Each check implements run(version_ref) -> CheckResult.
  • SignalStore is optional. All signal store code in core.py is guarded by if self._signal_store.
  • No Airflow imports in this package. Airflow integration is a separate package (Phase 2).

Coding Standards

  • Python ≥3.11. Use X | None, list[T], from __future__ import annotations.
  • Type hints on all functions. TYPE_CHECKING guard for annotation-only imports.
  • Ruff line length: 120.
  • Comments only when the why is non-obvious.

Testing

  • Every bug fix and feature needs tests. TDD preferred.
  • Use in-memory fakes (e.g. FakeBackend), not mocks.
  • Test files: tests/test_<module>.py.
  • Coverage must stay ≥80% (currently ~96%).
  • Run the full suite before committing.

Branches and CI

  • Default branch: develop (not main).
  • PRs target develop. Feature branches: feature/<name>. Bug fixes: fix/<name>.
  • CI: ruff lint, ruff format, pytest (3.11/3.12/3.13), mkdocs build --strict.

Boundaries

  • Do not add dependencies for what a few lines can do.
  • Do not add abstractions without a second consumer.
  • Do not remove or weaken tests to make CI pass.
  • Do not commit to develop directly; always use a PR.
  • Do not add Generated by / Co-Authored-By: Claude trailers.