Development

Development#

In Oxbow, data I/O is handled in Rust and rich features are exposed via Python. There are currently minimal bindings to R. Oxbow makes extensive use of the noodles and bigtools crates to parse genomic file formats.

The overall project is organized as a multi-project “monorepo” split into separate Rust, Python, and R packages.

Oxbow (Rust + Python)#

Project management#

The core oxbow project is a pure Rust library. The code for the Python package in py-oxbow is a hybrid Rust-Python project. The latter requires the uv package/project manager for development and relies on PyO3’s maturin as a Python build system.

Ensure you have Rust installed on your system. You can install Rust using rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install uv by following the instructions here. The Python project’s dependencies are organized into PEP 735-style dependency groups in the pyproject.toml. The following will create a virtual environment in py-oxbow/.venv with all dependency groups:

cd py-oxbow
uv sync

Building the Rust crate only#

The oxbow Rust crate alone can be built using the standard Rust package manager, cargo. To build the library, navigate to the oxbow directory and run cargo build:

cd oxbow
cargo build  # --release (for non-debug build)

Building the Rust-Python project#

To (re)build and install a local development version of oxbow into your virtual environment:

cd py-oxbow
uvx maturin develop --uv

For a non-debug (and faster-running) build, add --release:

uvx maturin develop --uv --release

You can then test the build interactively:

uv run python

>>> import oxbow as ox
>>> ...

or running one of the example notebooks:

uv run jupyter lab ./notebooks/bench.ipynb

Linting and formatting#

We use the standard Rust toolchain for linting and formatting Rust code.

Clippy is a Rust linter:

cargo clippy

The following command formats all source files of the current crate using rustfmt:

cargo fmt

We use ruff for linting and formatting Python code.

To validate the code style:

uv run ruff check

To format:

uv run ruff format

Running Tests#

To run tests on Rust code, we use cargo:

cargo test

For Python, we use pytest. Tests currently need to be run from within the tests directory.

cd py-oxbow/tests
uv run pytest

R interface#

To build the R bindings from source, navigate to the r-oxbow directory and start an interactive R environment. Make sure you have the devtools and rextendr libraries installed.

Changes must be recompiled as described here.

library(devtools)
library(rextendr)
rextendr::document()
devtools::load_all(".")

The Rust extension code is found in r-oxbow/src/rust/src/lib.rs. You can use cargo commands for linting, formatting, and testing the Rust code. The automatically generated R wrappers are found in r-oxbow/R/extendr-wrappers.rs. Do not edit this file manually!

In order to provide default argument values, we layer on an additional wrapper on top of what rextendr generates in r-oxbow/R/api.rs. This is the user-facing API.

Contents