Rust-first development

The default PEP-517 build uses maturin and installs the Rust extension as kwimage_ext._rust. The public Python modules remain compatibility shims, so downstream kwimage imports do not need to change while kernels are ported.

For an editable Rust build:

./dev/build_rust.sh
python -m pytest tests/test_rust_backend.py tests/test_rust_shims.py

The historical Cython/C sources are retained temporarily as a parity reference. To rebuild both implementations and require direct semantic parity:

./dev/check_backend_parity.sh

dev/build_legacy.sh is available when only the reference extensions are needed. It builds CPU reference modules under explicit *_legacy names; those binaries are not part of the normal wheel.

Backend selection is capability-aware: a Rust module is selected only when it implements every symbol required by a particular shim. Set KWIMAGE_EXT_FORCE_RUST=1 to prove that a test is not accidentally falling through to a legacy extension. KWIMAGE_EXT_FORCE_LEGACY=1 is intended for maintainer diagnostics only.

The Rust module also exposes narrow coco-assignment capabilities through kwimage_ext.algo.assignment. coco_greedy_match batches IoU thresholds; coco_greedy_match_grid additionally batches independent area/ignore slices so downstream evaluators can cross the Python/Rust boundary once per image. Both accept an already-built CSR sparse candidate graph plus stable prediction order / truth flags. Geometry and metric policy remain outside these kernels; downstream kwcoco retains Python reference implementations and fallbacks. Direct kernel parity and timing can be checked with:

KWIMAGE_EXT_FORCE_RUST=1 python -m pytest -q tests/test_rust_assignment.py
python dev/bench_assignment.py --n-pred=400 --n-true=400 --candidates=40

Release wheels use PyO3 abi3-py310. Build one CPython 3.10 baseline wheel per platform and test that same artifact on every supported Python version. The artifact-level check is:

python dev/check_wheel_artifact.py wheelhouse/kwimage_ext*.whl

Release evidence audit

For release candidates, validate the built wheel, not an editable checkout. The artifact validator first checks the archive structure, then installs the wheel into a temporary target directory and requires every imported kwimage_ext module (including algo.assignment and _rust) to resolve from that isolated target. This prevents source-tree imports or stale editable .pth files from hiding an incomplete release artifact:

python dev/validate_wheel_artifact.py wheelhouse/kwimage_ext*.whl

For a local release candidate, the deterministic preflight is:

./dev/build_release_candidate.sh _release_candidate

That command always builds a fresh non-editable wheel, validates the isolated install/capability surface, runs the release-packaging guards, records SHA256 hashes and wheel contents, and emits an uploadable evidence bundle. dev/validate_rust_port.sh performs the same non-editable wheel audit in addition to the editable development tests. End-to-end COCO metric speed / memory comparisons remain owned by kwcoco because only the full evaluator can make a meaningful comparison against pycocotools.COCOeval.