# ryxpress — Reproducible Analytical Pipelines with Nix (Python)

If you’re looking for rixpress, the R package version [look here](https://github.com/b-rodrigues/rixpress).

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)](https://www.youtube.com/watch?v=a1eNG9TFZ_o)

## 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.

```python
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.
