ryxpress 0.0.2

Reproducible Analytical Pipelines with Nix

ryxpress — Reproducible Analytical Pipelines with Nix (Python)

If you’re looking for rixpress, the R package version look here.

ryxpress is a Python reimplementation/port of the R package rixpress. It provides helpers and a small framework to build and work with reproducible, multilanguage analytical pipelines that are built with Nix. The code for the Python package lives under src/ryxpress and exposes utilities to define, inspect and consume Nix-built artifacts from Python.

If you previously used the R version (rixpress), ryxpress aims to provide a similar user experience for Python projects while integrating with the same Nix-first workflow.

Video introduction (original R demo)

Quick overview

• Use Nix to describe reproducible runtime/build environments.
• Define pipeline derivations (build steps) in your project using R syntax, but inspect and load artifacts using Python.
• Build pipelines with Nix and use ryxpress helpers to read, load or copy outputs from the Nix store.

Installation

Prerequisites

• Nix installed on your machine. See the Nix project docs or Determinate Systems' installer.

Because ryxpress is a wrapper around the R version, both R and {rixpress} need to be available, and since there’s not much point in using ryxpress if you don’t have Nix installed, we provide a default.nix for easy installation and use.

Basic usage examples

Read or load an artifact by derivation name The Python helpers mirror the R helpers' intent: they try to resolve derivation outputs and—when sensible—load objects into Python. Note: these functions are best-effort and safe in the presence of non-Python outputs.

from ryxpress.rxp_read_load import rxp_read, rxp_load

# Try to read the output of a derivation "mtcars_mpg".
# rxp_read tries to load a pickle first, then tries rds2py for RDS files if available;
# if nothing can be loaded it returns a path (or list of paths) instead of raising.
res = rxp_read("mtcars_mpg")

if isinstance(res, str):
    print("Artifact path:", res)
else:
    print("Loaded Python object of type:", type(res))

# rxp_load behaves similarly but will attempt to inject the loaded object into
# the caller's globals (best-effort) when successful, otherwise returns the path(s).
obj_or_path = rxp_load("mtcars_mpg")

Note on formats:

• rxp_read/rxp_load will try pickle.load first (even if the filename has no .pkl/.pickle extension).
• If pickle fails and the file looks like an RDS (or even if it doesn't), rxp_read/rxp_load will attempt to use the optional rds2py package (if present) to parse the file.
• If neither loader succeeds, the function returns the path(s) (no warnings or exceptions are raised in normal "can't load" cases).

Inspect builds and outputs

• rxp_inspect inspects the project build logs and helps resolve derivation outputs.
• rxp_copy copies artifacts from /nix/store into your working directory for inspection.
• rxp_gc helps manage cache/cleanup of local artifacts.

Docs and API reference (developer docs)

This repository uses MkDocs + mkdocstrings to generate documentation and an autogenerated API reference from the package docstrings.

Contributing

Contributions are welcome. When contributing, please:

• Provide small, focused, and runnable examples.
• Prefer small datasets and short-running examples for tests/docs.
• Document any system-level dependencies for examples in a default.nix so the pipeline can be reproduced.

If you are unsure about a change, open an issue to discuss before submitting a PR. See CONTRIBUTING.md for guidelines (if present).

Scope

The Python port focuses on the same “micropipeline” use case: single-machine pipelines for small-to-medium projects where Nix provides reproducible builds. It aims to mirror the user experience of the R package where practical, but it is not a drop-in replacement for all R-specific workflows. See the docs for current feature coverage and examples.

Examples & demos

See the examples and demos in the companion repository: https://github.com/b-rodrigues/rixpress_demos

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See LICENSE for details.