Skip to content

Developer Notes

Testing

This project uses pytest for its test suite. The dependencies are defined in pyproject.toml, and the test settings are in pytest.ini.

To install the project and its test dependencies in editable, run:

pip install -e ".[test]"

Then, the test suite can be ran with:

pytest

Test Coverage

Test coverage can be generated with the pre-configured coverage.py tool. Follow the installation instructions in Testing, and then just append --cov:

pytest --cov

Docstring conventions

Ownership of returned wrappers

Any method or function whose return type is a KernelOpaquePtr subclass must end its Returns: section with one of the following sentences, so that callers can reason about lifetimes without reading the implementation:

  • Owned handle. — the caller receives an independent handle. The underlying C memory is freed when the returned object is garbage collected.
  • View into <parent>. — the returned object borrows its C memory from <parent>. Use detach() (or copy.copy()) to promote it to an owned handle if it needs to outlive its parent. See Object Lifetimes for context.

Linting and Type Checking

Code style is enforced with ruff and types are checked with ty. Both are run in CI and can be run locally:

ruff check .
ruff format --check .
uv run --extra type ty check