fitscube-rs¶

A Rust port of the fitscube Python package. Combines single-frequency/single-time FITS images into a FITS cube — building the spectral (or time) axis from the per-image headers, detecting even vs uneven spacing, preserving per-channel beams in a CASA BEAMS table — and extracts individual planes back out.

Note: This is an experiment in LLM-assisted coding with Claude. Do not trust this software as far as you can throw it.

Installation¶

Python library¶

pip install fitscube-rs

CLI binary¶

Requires Rust 1.85+.

cargo install fitscube-rs

Usage¶

Python API and quickstart: fitscube-rs.readthedocs.io/en/latest/quickstart.html
CLI reference: fitscube-rs.readthedocs.io/en/latest/cli.html
Rust API: docs.rs/fitscube-rs

Development¶

Install in editable mode:

uv pip install -e .

After changing the Python-facing Rust API in src/python.rs, rebuild with the stubgen feature (the default build omits _generate_stubs) and regenerate the type stubs:

uv run maturin develop --features stubgen
uv run --no-sync python -c "from fitscube_rs._fitscube_rs import _generate_stubs; _generate_stubs()"

This overwrites fitscube_rs/_fitscube_rs.pyi from the Rust annotations and docstrings. Commit the result alongside any API changes.

Running tests¶

Python tests need the compiled extension and the test extra (pytest, astropy), plus the upstream fitscube package, which the parity tests validate against. uv sync builds the maturin extension into .venv, so a plain uvx pytest won’t work — it runs in an isolated env with neither the module nor the deps:

uv sync --extra test       # builds the extension + installs test deps
uv pip install fitscube    # upstream package, for parity tests
uv run --no-sync pytest

Rust tests run with cargo test:

cargo test

Pre-commit hooks¶

Formatters and linters run via prek, a fast drop-in pre-commit reimplementation. The hooks (.pre-commit-config.yaml) are the same checks CI enforces: ruff lint + format, ty type checking, cargo fmt, and cargo clippy.

uv sync --extra dev   # installs prek + ty into the venv
uvx prek install      # install the git hook (runs on every commit)
uvx prek run --all-files   # run all hooks manually

License¶

fitscube-rs is released under the BSD 3-Clause License.

It is a port of the fitscube Python package by Alec Thomson (BSD 3-Clause), and validates its output against that package in the test suite. See NOTICE.md for full attributions.

Table of contents¶

Rust API¶

The Rust crate is documented separately on docs.rs/fitscube-rs — the Python API on this site is a thin binding over it.