styxsingularity 0.7.1
Singularity/Apptainer integration for Styx compiled wrappers
Requires Python: >=3.10

# Singularity/Apptainer Runner for Styx compiled wrappers

[![Build](https://github.com/styx-api/styxsingularity/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/styx-api/styxsingularity/actions/workflows/test.yaml?query=branch%3Amain)
[![codecov](https://codecov.io/gh/styx-api/styxsingularity/branch/main/graph/badge.svg?token=22HWWFWPW5)](https://codecov.io/gh/styx-api/styxsingularity)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
![stability-stable](https://img.shields.io/badge/stability-stable-green.svg)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/styx-api/styxsingularity/blob/main/LICENSE)
[![pages](https://img.shields.io/badge/api-docs-blue)](https://styx-api.github.io/styxsingularity)

`styxsingularity` is a Python package that provides Singularity/Apptainer integration for Styx compiled wrappers. It allows you to run Styx functions within Singularity containers, offering improved isolation and reproducibility for your workflows.

## Installation

You can install `styxsingularity` using pip:

```Python
pip install styxsingularity
```

## Usage

```Python
from styxdefs import set_global_runner
from styxsingularity import SingularityRunner

# Initialize the SingularityRunner
runner = SingularityRunner()

# Set the global runner for Styx
set_global_runner(runner)

# Now you can use any Styx functions as usual, and they will run in Singularity containers
```

## Advanced Configuration

The `SingularityRunner` class accepts several parameters for advanced configuration:

- `image_overrides`: A dictionary to override container image tags
- `singularity_executable`: Path to the Singularity executable (default: `"singularity"`)
- `data_dir`: Directory for temporary data storage
- `environ`: Environment variables to set in the container

Example:

```python
runner = SingularityRunner(
    image_overrides={"python:3.9": "my-custom-python:3.9"},
    singularity_executable="/usr/local/bin/singularity",
    data_dir="/tmp/styx_data",
    environ={"PYTHONPATH": "/app/lib"}
)
```

## Error Handling

`styxsingularity` provides a custom error class, `StyxSingularityError`, which is raised when a Singularity execution fails. This error includes details about the return code, command arguments, and Singularity arguments for easier debugging.

## Contributing

Contributions to `styxsingularity` are welcome! Please refer to the [GitHub repository](https://github.com/styx-api/styxsingularity) for information on how to contribute, report issues, or submit pull requests.

## License

`styxsingularity` is released under the MIT License. See the LICENSE file for details.

## Documentation

For detailed API documentation, please visit our [API Docs](https://styx-api.github.io/styxsingularity).

## Support

If you encounter any issues or have questions, please open an issue on the [GitHub repository](https://github.com/styx-api/styxsingularity).

## Requirements

- Python 3.10+
- Singularity or Apptainer installed and running on your system

## Comparison with [`styxdocker`](https://github.com/styx-api/styxdocker)

While [`styxdocker`](https://github.com/styx-api/styxdocker) and [`styxsingularity`](https://github.com/styx-api/styxsingularity) serve similar purposes, they have some key differences:

- Container Technology: `styxdocker` uses Docker, while `styxsingularity` uses Singularity/Apptainer.
- Platform Support: `styxdocker` works on Windows, Linux, and macOS, whereas `styxsingularity` is not supported on Windows.
- User Permissions: `styxdocker` can run containers as the current user on POSIX systems, which can help with file permission issues.

Choose the package that best fits your infrastructure and requirements.