Intervaltree in rust

This crate exposes an interval tree implementation written in Rust to Python via PyO3. The Python wrapper provides the ability to build a tree from tuples, insert additional intervals, search for overlaps, and delete intervals by their (left, right) key.

Requirements

• Rust toolchain (for compiling the extension module)
• Python 3.8+
• maturin for building/installing the package

Quick start

python -m venv .venv
source .venv/bin/activate
pip install maturin
maturin develop

You can install the package with (also with uv)

pip install intervaltree_rs

maturin develop builds the extension module in-place and installs it into the active virtual environment, making it importable as intervaltree_rs.

Usage

Once installed, you can use the interval tree directly from Python:

from intervaltree_rs import IntervalTree

# Build a tree from tuples: (left, right, payload)
intervals = [
    (5, 10, "a"),
    (12, 18, "b"),
    (1, 4, "c"),
]
tree = IntervalTree.from_tuples(intervals)

# Insert another interval
tree.insert((8, 11, "d"))

# Search for overlaps. Inclusive bounds are enabled by default.
hits = tree.search(9, 10)
for left, right, value in hits:
    print(left, right, value)

# Delete by the interval key
removed = tree.delete((12, 18))
print("Removed:", removed)

Search options

IntervalTree.search(ql, qr, inclusive=True) accepts an inclusive flag. Set it to False to perform exclusive range queries.

Building a distributable wheel

To build a wheel that you can distribute or upload to PyPI, run:

maturin build --release

The built wheels will be placed under target/wheels/.

Running tests

The Python bindings are covered by Rust unit tests. Run them with:

cargo test