6.6 · Project
Toolchain¶
All Python commands run through uv with the lock enforced; Rust through Cargo. CI runs the same commands.
Setup¶
uv sync --locked # creates .venv, builds the Rust extension (maturin), installs dev groups
uv run --locked pre-commit install
Requires: uv ≥ 0.9, a stable Rust toolchain (rustup) with rustfmt and clippy.
The PyO3 extension build backend requires maturin ≥ 1.9.4; uv selects it from
the isolated build-system requirement.
Gates¶
| Gate | Command |
|---|---|
| Lock is current | uv lock --check |
| Lint (+ autofix) | uv run --locked ruff check --fix . |
| Format | uv run --locked ruff format . |
| Types + typing fixtures | uv run --locked mypy |
| Python cognitive complexity | uv run --locked complexipy . --failed |
| Rust cognitive complexity | Install rust-code-analysis-cli 0.0.25, then run rust-code-analysis-cli -m -p crates -O json --pr -o /tmp/hinoki-rust-complexity && python scripts/check_rust_complexity.py /tmp/hinoki-rust-complexity |
| Python tests + coverage | uv run --locked pytest --cov |
| Only the real-server tests | uv run --locked pytest -m runtime |
| Rust format / lints / tests | cargo fmt --all --check · cargo clippy --workspace --all-targets -- -D warnings · cargo test --workspace (see PyO3 setup below) |
| All hooks | uv run --locked pre-commit run --all-files |
Database tests¶
The binding tests embed Python. Select the interpreter explicitly and add its shared-library directory when running the workspace suite locally:
PYTHON="$(uv run --locked python -c 'import sys; print(sys.executable)')"
PYTHON_LIBDIR="$("$PYTHON" -c 'import sysconfig; print(sysconfig.get_config_var("LIBDIR"))')"
PYO3_PYTHON="$PYTHON" \
LD_LIBRARY_PATH="$PYTHON_LIBDIR${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
cargo test --workspace
CI sets these variables for the Rust job using its uv-managed Python 3.13.
PostgreSQL-dependent tests in tests/dbtest.py, tests/transactiontest.py and crates/orm/tests/postgres.rs need a disposable server and run only when HINOKI_TEST_DATABASE_URL is set; otherwise pytest reports them as skipped and Cargo prints SKIPPED. Migration conformance tests for MySQL and MariaDB use HINOKI_TEST_MYSQL_URL and HINOKI_TEST_MARIADB_URL; test each supported backend separately and read the skip summary. A run without the PostgreSQL URL does not verify PostgreSQL behavior. Locally:
docker run -d --name hinoki-test-pg -e POSTGRES_PASSWORD=hinoki -e POSTGRES_DB=hinoki \
-p 127.0.0.1:54399:5432 --tmpfs /var/lib/postgresql/data postgres:17-alpine
export HINOKI_TEST_DATABASE_URL=postgres://postgres:hinoki@127.0.0.1:54399/hinoki
uv run --locked pytest
PYTHON="$(uv run --locked python -c 'import sys; print(sys.executable)')"
PYTHON_LIBDIR="$("$PYTHON" -c 'import sysconfig; print(sysconfig.get_config_var("LIBDIR"))')"
PYO3_PYTHON="$PYTHON" \
LD_LIBRARY_PATH="$PYTHON_LIBDIR${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
cargo test --workspace
docker rm -f hinoki-test-pg
CI provides the same database as a service container. Never point the variable at a database with real data: tests create and drop tables.
The Python and Rust suites include ORM/model tests. PostgreSQL-dependent tests
run only with a disposable HINOKI_TEST_DATABASE_URL; migration conformance
tests for MySQL and MariaDB also use HINOKI_TEST_MYSQL_URL and
HINOKI_TEST_MARIADB_URL. CI provides disposable real-server services.
The native CRUD differential test build enables the private sql-trace Cargo
feature so it can compare SQL text, parameters and order for both request lanes;
ordinary wheels are built without that feature. Build it into the environment
with uv run --no-sync --with "maturin>=1.9.4,<2" maturin develop --manifest-path crates/bindings/Cargo.toml --features sql-trace.
Without it those tests skip; set HINOKI_REQUIRE_SQL_TRACE=1 (CI does) to make
a missing trace build fail them instead. The CI Rust job also runs
cargo clippy -p hinoki-bindings --all-targets --features sql-trace -- -D warnings.
Generated OpenAPI is validated with openapi-spec-validator inside the Python
tests. The retained benchmark report has reproducible
end-to-end measurements, but benchmark runs are separate from the default CI
test gate.
Decisions¶
- Python ≥ 3.12, dev interpreter 3.13 (
.python-version), CI 3.12, 3.13 and 3.14, abi3 wheels (smoke-tested in a clean 3.12 environment by thewheelCI job). - Ruff is the only linter/formatter (
ruff checkwith--fix, thenruff format), version pinned inpyproject.toml(lintgroup) and in.pre-commit-config.yaml; keep them equal when bumping. - mypy --strict is the separate type check. No overlapping tools (no black, isort, flake8, pylint).
- maturin is the build backend (
python-source = "python", extensionhinoki.core); uv rebuilds when Rust sources change (tool.uv.cache-keys). - Cognitive complexity is capped at 15 for every Python function and Rust function/closure. CI runs pinned
complexipyandrust-code-analysis-cli; test and development code are included. Refactor over-budget functions instead of suppressing analyzer findings. - Dependency groups:
lint,typecheck,test, aggregated bydev. Granian is both the optional runtime server extra and a test dependency for server integration coverage.
Two environments, two responsibilities¶
- uv owns the project:
.venv,uv.lock, the dependency groups and every tool declared in them (ruff,mypy,pytest,pre-commititself). Run them withuv run --locked .... - pre-commit builds its own isolated environments for the hooks it fetches (e.g.
ruff-pre-commit); these are not the project.venvand are not managed by uv. That is why the Ruff revision in.pre-commit-config.yamlmust equal theruff==pin inpyproject.toml(uv.lock). - Hooks never rewrite
sources/-style historical snapshots (excluded globally). CI never applies fixes: it fails if a hook would change a file.pre-commit installis a manual step in a Git checkout, never triggered by importing the framework.
CI workflow hygiene¶
- Third-party actions in
.github/workflows/are pinned to a full commit SHA with the released tag in a trailing comment. To update one, resolve the new tag to its commit (gh api repos/OWNER/REPO/git/ref/tags/TAG), replace the SHA and the comment together, and let the PR's CI run prove it. - Each
Python Xjob setsUV_PYTHONto its matrix version and asserts the interpreter before testing. Without ituv runfollows.python-versionand every job would test 3.13. Locally, run another version withuv run --locked --python 3.14 pytest(useUV_PROJECT_ENVIRONMENTto keep its environment apart). ci.ymlchecks out withpersist-credentials: false: no CI job pushes.deploy-docs.ymlkeeps the token because it pushes togh-pages.- The
auditjob checksCargo.lock(cargo audit,cargo deny check) anduv.lock(uv exportof every group and extra, thenpip-audit --require-hashes --disable-pip). Locally:uv export --locked --all-groups --all-extras --no-emit-project --format requirements-txt -o /tmp/requirements.txt && uvx pip-audit==2.10.1 --require-hashes --disable-pip -r /tmp/requirements.txt.
Native extension: editable install, rebuild, wheel¶
| Task | Command | Notes |
|---|---|---|
| Editable install (first time) | uv sync --locked |
maturin builds a debug extension into the project |
| Rebuild after changing Rust | uv sync --locked (or any uv run) |
tool.uv.cache-keys watches crates/**/*.rs and Cargo.toml; uv reinstalls when they change. Observed: touching router.rs made uv run rebuild |
| Force a rebuild | uv sync --locked --reinstall-package hinoki |
use if in doubt; syncing Python deps alone does not prove the extension is current |
| Release-profile editable build | uv run --locked maturin develop --release |
needs maturin on PATH (uvx maturin works) |
| Wheel | uv build --wheel |
abi3 (cp312-abi3) wheel in dist/; built and import-tested by the wheel CI job |
| Rust workspace tests | cargo test --workspace with the PyO3 environment above |
PyO3 unit tests link to the selected Python interpreter; PostgreSQL tests require HINOKI_TEST_DATABASE_URL |