Contributing#

Any help is welcome – including constructive criticism. Feel free to clone the repository, run it, and open merge requests or issues.

Standards#

The project sticks to a few standards so the code stays consistent and merges painlessly.

Tooling:

  • Ruff – lint and format. Configured in pyproject.toml; migrations/ is excluded.

  • uv – dependency management. pyproject.toml is the source of truth; requirements and requirements_dev are generated from it.

  • Docker – everything runs in containers.

Code style:

  • Python >= 3.13.

  • Prefer the simplest solution that solves the problem.

  • Prefer dataclasses or Pydantic models over raw dict for structured data.

  • Prefer f-strings over % / .format().

  • Prefer pathlib over os.path.

  • Use docstrings on functions, classes and methods (autodoc renders them in these docs).

Updating dependencies#

Edit pyproject.toml, then refresh the lockfile and re-export the requirements files:

# 1. Resolve and update uv.lock from pyproject.toml.
$ uv lock

# 2. Export uv.lock into the plain requirements files the
#    Dockerfile consumes via `pip install -r`.
$ uv export --no-hashes --no-annotate --no-dev -o app/requirements
$ uv export --no-hashes --no-annotate -o app/requirements_dev

uv.lock is the single source of truth: uv sync (used by contributors) and the exported requirements files (used by the Docker image) both derive from it, so they cannot drift.

Commit pyproject.toml, uv.lock, app/requirements and app/requirements_dev together.

Rebuild the image:

$ docker compose -f compose.dev.yaml build

Updating documentation#

Documentation lives in docs/ and is built with Sphinx:

$ cd docs
$ uv run make clean html

Output ends up in docs/build/html/index.html. To validate cleanly (no warnings) before opening a merge request:

$ cd docs
$ sphinx-build -W -b html source build/html

Whenever a feature is added or changed, update the relevant page in docs/source/modules/ and – if architecture-level concepts shift – the relevant page under docs/source/architecture/.

Co-developed libraries#

Some functionality lives in sibling libraries that are co-developed with this project:

  • Rug – stock-market data scrapers.

  • Karpet – cryptocurrency data scrapers.

If you fix a scraper there, you’ll typically also need a release of the library and a dependency bump here.