Local development
This page is for people changing pydelity itself. To use pydelity, see Install pydelity.
Prerequisites
Section titled “Prerequisites”- git
- uv 0.8.1 or later
- just, a recent version, for
example with
uv tool install rust-justorbrew install just. The repo pins just 1.59.0 inpyproject.toml.
Everything else is pinned in the repo, so you don’t need to install it yourself.
prek (which runs the git hooks), Ruff, ty,
interrogate, pytest, twine and zizmor are pinned in pyproject.toml and
installed into .venv by just install. Run one directly with uv run, for
example uv run prek run --all-files. Prettier and markdownlint, and the
Node.js they run on, are pinned in .pre-commit-config.yaml. prek sets them up
the first time a git hook or just lint-markdown needs them.
Without just installed, uv run --locked just <recipe> runs the pinned just
instead. If you’d rather have prek on your PATH too, install it with
uv tool install prek or brew install prek (see
prek’s installation guide).
The docs site needs Node.js and pnpm as well. See The docs site.
The recipes use bash, so on Windows run them from Git Bash or WSL.
Get started
Section titled “Get started”git clone https://github.com/IDinsight/pydelity.gitcd pydelityjust installjust testCommands
Section titled “Commands”| Command | What it does |
|---|---|
just |
List every recipe |
just build |
Build the wheel and sdist into a fresh dist/, then check their metadata as PyPI would |
just clean |
Remove .venv, caches and build output (run just install afterwards) |
just docs |
Serve the docs site with live reload |
just docs-build |
Build the docs site, then check its internal links |
just docs-reference |
Regenerate the docs site’s reference pages from the code |
just install |
Create .venv from uv.lock (fails if the lock is out of date) and install the prek git hook |
just lint |
Regenerate the reference pages, then run every lint recipe below |
just lint-markdown |
Format every Markdown file with Prettier, then lint it with markdownlint |
just lint-python |
Fix and format the Python code with Ruff, type-check it with ty, and check docstring coverage with interrogate |
just lint-workflows |
Audit the GitHub Actions workflows, the hook config and the Dependabot config with zizmor |
just test |
Run the tests, then the docstring examples, in random order, and stop at the first failure |
just testruns the tests in parallel, one worker per CPU, then the examples in the docstrings undersrc/. It stops at the first failure. To run everything and collect every failure instead, useKEEP_GOING=1 just test. The failures and errors are also written to.cache/test-errors.- Tests run in a random order. pytest prints the seed at the top
(
Using --randomly-seed=...), anduv run pytest --randomly-seed=<seed>repeats that order. - No test calls a real model provider or spends money. Every test runs with
dummy API keys and with the providers’ addresses pointed at a closed local
port. Tests that need a provider use the stand-in server in
tests/fixtures/mock_providers.py. - The tests import the installed package, not
src/, so they test what users get.
CI runs the tests on Python 3.13 and 3.14. It also builds the wheel and, on
Linux, macOS and Windows, installs it in a fresh environment and runs a survey
against the stand-in server (scripts/smoke_installed_wheel.py).
Dependencies
Section titled “Dependencies”uv add and uv remove update pyproject.toml and uv.lock and sync .venv
in one step, and keep the lists in alphabetical order.
| Task | Command |
|---|---|
| Add a dev tool (test, lint, type check) | uv add --dev "<package>==<version>" |
| Add a runtime dependency | uv add <package> |
| Upgrade a dev tool | uv add --dev "<package>==<new version>" |
| Upgrade a runtime dependency | uv lock --upgrade-package <package>, then just install |
| Remove a dependency | uv remove <package> (with --dev for a dev tool) |
After editing pyproject.toml by hand |
uv lock, then just install |
Rebuild .venv from scratch |
just clean, then just install |
- Dev tools are pinned to an exact version (
==), so everyone and CI run the same one. Runtime dependencies get a minimum version (uv addwrites>=), so pydelity installs alongside other packages. - Afterwards, run
just lintandjust test, and commitpyproject.tomlanduv.locktogether. CI fails if the lock does not matchpyproject.toml. - After pulling someone else’s dependency change, run
just install. - Dependabot opens a monthly pull request that moves the pins to newer releases.
Git hooks
Section titled “Git hooks”With the git hook installed, prek runs the checks on the files in each commit.
To run every hook on every file, use uv run prek run --all-files.
Commit messages
Section titled “Commit messages”Commit messages on main follow
Conventional Commits, because
release-please works out each release from them. When a pull request is
squash-merged, its title becomes the commit message. See
Releases.