rust-python-ffi

name	rust-python-ffi
description	Reference for the gbcms Rust/Python (PyO3) boundary — maturin build commands,

Rust/Python FFI Patterns

Building

maturin develop           # dev build (fast, unoptimized)
maturin develop --release # release build (use before integration tests)

legacy-parity feature (default on). The per-variant count_bam parity oracle is gated behind the default legacy-parity Cargo feature, so dev/test builds (above) include it and the binned↔legacy parity tests work. Shipped wheels build with --no-default-features (Dockerfile, release.yml) to omit it — production never calls count_bam. If you maturin build --no-default-features locally, gbcms._rs.count_bam will be absent and the parity tests will fail (expected).

PyO3 Bindings

• Rust structs with #[pyclass] expose fields via #[pyo3(get)] or #[pyo3(get, set)]
• Type stubs (_rs.pyi) must exactly match #[pyo3(get)] fields
• BaseCounts is frozen from Python — mutations use with_ad() copy-on-write
• src/gbcms/_rs.pyi is the single stub for gbcms._rs — update it when fields/signatures change

Platform-Portable Code

The coitrees crate uses different node types per SIMD backend:

• nosimd (CI Linux): IntervalNode<usize, _> → node.metadata is usize
• NEON (macOS ARM): Interval<&usize> → node.metadata is &usize

Pattern for portable metadata access:

use std::borrow::Borrow;
#[allow(noop_method_call)]
let idx: &usize = node.metadata.borrow();
let exon = &self.exons[*idx];

Environment Variables

GBCMS_LOG_LEVEL=DEBUG RUST_LOG=debug gbcms dna ...
OPENSSL_NO_VENDOR=1  # required for Linux CI builds