POTE/docs/05_dev_setup.md

Dev setup (conventions; code scaffolding comes next)

This doc sets the conventions we’ll implement in the first “code PRs”.

Python + layout

• Use Python 3.x
• Source layout: src/ + tests/
• Prefer type hints and docstrings

Configuration

• Store secrets in .env (not committed).
• Commit a .env.example documenting required variables.

Expected variables (initial):

• POTE_DB_URL (e.g., sqlite:///./pote.db or Postgres URL)
• QUIVER_API_KEY (optional, if using QuiverQuant)
• FMP_API_KEY (optional, if using Financial Modeling Prep)

Database

• Default dev: SQLite for fast local iteration.
• Support Postgres for “real” runs and larger datasets.
• Migrations: Alembic (once models are in place).

Testing

• pytest for unit/integration tests
• Prefer:
  • HTTP clients tested with mocked responses
  • DB tests using SQLite in a temp file or in-memory where possible

Logging

• Use standard logging with consistent, parseable messages.
• ETL jobs should log counts: fetched/inserted/updated/skipped.

PR sizing guideline

Each PR should:

• implement one coherent piece (schema, one client, one ETL, one metric module)
• include tests
• include minimal docs updates (if it changes behavior)