RosettaStune

RosettaStune is a lightweight unit registry for cross-schema linked data. It uses a Rust core for fast alias resolution and a Python layer for optional conversions to Pint, Astropy, and SymPy.

• Unit alias policy and contribution guide: docs/unit-alias-policy.md
• Agent and contributor workflow: AGENTS.md

• python/rosettastune/data/lexicon.jsonld is the language-agnostic source of truth.
• The Rust extension parses the JSON-LD lexicon and resolves identifiers locally.
• The Python wrapper converts resolved canonical units into whichever unit library is available.

• Pint for runtime array math and engineering calculations.
• Astropy for strict scientific unit handling.
• SymPy for symbolic expressions and algebra.

• Open this repository in the included dev container: .devcontainer/devcontainer.json
• The container installs Python, Rust, llvm-tools-preview, and cargo-llvm-cov during postCreateCommand.

make install-dev

If your Python executable is not the project venv default, override it:

make install-dev PYTHON=/path/to/python

The project includes a task-oriented Makefile: Makefile

make help
make fmt
make test
make ci

Common tasks:

• make snapshot-update refreshes Rust insta snapshots.
• make coverage-python generates coverage.xml, coverage.txt, and pytest-junit.xml via pytest defaults.
• make coverage-rust generates rust-coverage.lcov (requires cargo-llvm-cov).

• Build the extension with Maturin.
• Run Rust tests and snapshot checks with Cargo.
• Run Python tests with Pytest.

cargo fmt --check
cargo test
python -m pip install -e '.[dev]'
python -m pytest

• CI workflow: .github/workflows/ci.yml
• Coverage thresholds source of truth: Cargo.toml in [package.metadata.coverage]
• CI enforces both:
  • Python coverage minimum (python_min)
  • Rust line coverage minimum (rust_min) via cargo llvm-cov
• On published releases, CI uploads coverage artifacts to the release:
  • pytest-junit.xml
  • coverage.xml
  • coverage.txt
  • rust-coverage.lcov
  • rust-coverage.txt

1. Confirm local checks pass:

make ci

2. Confirm coverage thresholds in Cargo.toml under [package.metadata.coverage] are intentional.
3. Ensure version metadata is updated where needed (Cargo.toml, pyproject.toml).
4. Push changes to main and create/publish a GitHub release tag.
5. Wait for the release-assets job in .github/workflows/ci.yml to succeed.
6. Verify release assets include:
   • pytest-junit.xml
   • coverage.xml
   • coverage.txt
   • rust-coverage.lcov
   • rust-coverage.txt
7. If release coverage/upload fails, inspect workflow logs for:
   • missing cargo-llvm-cov
   • coverage threshold failures
   • pytest import/environment issues

• ModuleNotFoundError: No module named rosettastune while running tests:
  • Use the project venv interpreter and install editable deps first:

make install-dev
make test

- Or override `PYTHON` explicitly:

make test PYTHON=/path/to/python

• error: no such command: llvm-cov:

  • Ensure cargo-llvm-cov is installed and llvm-tools-preview is available.
  • The dev container and CI install both automatically.

• PyO3 import/init mismatch errors:

  • Ensure Maturin and PyO3 module names match:
    • pyproject.toml: module-name = "rosettastune._rosettastune"
    • src/lib.rs: #[pymodule] fn _rosettastune(...)

• Snapshot drift in Rust tests:

INSTA_UPDATE=always cargo test

1. Add canonical entry and aliases in python/rosettastune/data/lexicon.jsonld.
2. Add backend mappings in python/rosettastune/api.py for Pint, Astropy, and SymPy.
3. Update or regenerate snapshots with INSTA_UPDATE=always cargo test.
4. Add or adjust Python tests in tests/test_rosettastune.py.