spython

library0.3.14pypypi✓ verified 24d ago

spython is a Python library that provides a programmatic interface for interacting with the Singularity (now Apptainer) container engine. It allows Python applications to execute Singularity commands, manage images, and run containers without directly calling the command-line interface. The current version is 0.3.15, and it maintains a somewhat active release cadence with several updates per year.

devops

pip install spython

github ↗package ↗

INSTALL

IMPORT

SIG · SPYTHON

spython

devopspythonv0.3.14

Install

1.7s avg

Import

49ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.14 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.052s · 18.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.046s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from spython.main import Client

This quickstart demonstrates how to pull a Singularity image, run a command inside it, start and execute a command within an instance, and then stop the instance. It highlights the importance of checking the return_code for command success.

from spython.main import Client import os # Ensure Singularity/Apptainer is in your PATH # Example: Pull an image image_name = "alpine.sif" # Pull an image print(f"Pulling image: docker://alpine:latest to {image_name}") result_pull = Client.pull(image="docker://alpine:latest", pull_folder=os.getcwd(), pull_to=image_name) if result_pull.get('return_code') != 0: print(f"Error pulling image: {result_pull.get('stderr')}") else: print(f"Image pulled successfully: {result_pull.get('message')}") # Run a command inside the container print(f"Running 'ls -l /' in {image_name}") result_run = Client.run(image=image_name, command="ls -l /") if result_run.get('return_code') != 0: print(f"Error running command: {result_run.get('stderr')}") else: print("Command output (stdout):") print(result_run.get('stdout')) # Execute a command in the container with an instance instance_name = "my_alpine_instance" print(f"Starting instance '{instance_name}' from {image_name}") result_instance_start = Client.instance_start(image=image_name, instance=instance_name, command="sleep 60") if result_instance_start.get('return_code') != 0: print(f"Error starting instance: {result_instance_start.get('stderr')}") else: print(f"Instance '{instance_name}' started. Executing 'cat /etc/os-release'...") result_exec = Client.execute(image=image_name, instance=instance_name, command="cat /etc/os-release") if result_exec.get('return_code') != 0: print(f"Error executing in instance: {result_exec.get('stderr')}") else: print("Execution output (stdout):") print(result_exec.get('stdout')) print(f"Stopping instance '{instance_name}'") result_instance_stop = Client.instance_stop(instance=instance_name) if result_instance_stop.get('return_code') != 0: print(f"Error stopping instance: {result_instance_stop.get('stderr')}") else: print(f"Instance '{instance_name}' stopped successfully.") # Clean up (optional): remove the pulled .sif file if os.path.exists(image_name): print(f"Removing {image_name}") os.remove(image_name)

Debug

Known issues

gotchaspython acts as a wrapper for the Singularity (or Apptainer) command-line interface. For spython to function, the Singularity/Apptainer software must be installed on the system and its executable (e.g., `singularity` or `apptainer`) must be available in the system's PATH.

fix

Ensure Singularity/Apptainer is correctly installed and configured on your host system, and its binaries are discoverable via the PATH environment variable.

affects: All versions

gotchaAll spython commands (e.g., `Client.pull`, `Client.run`, `Client.execute`) return a dictionary object. This dictionary contains crucial keys like `return_code`, `message`, `stdout`, and `stderr`. It is vital to check `return_code` for command success and `stderr` for any error messages, as `stdout` might be empty even on failure.

fix

Always check `result.get('return_code')` for a non-zero value to detect failures, and inspect `result.get('stderr')` for diagnostic information.

affects: All versions

breakingAs of version `0.3.12`, `spython` explicitly changed behavior to prevent internal modification of instance names during operations. If your previous workflows implicitly relied on `spython` modifying or setting instance names, you will need to adjust.

fix

Manage instance names explicitly and avoid relying on `spython` to alter them. Ensure your instance start and stop commands use the exact instance names you intend.

affects: >=0.3.12

gotchaWhen working with local Singularity image files (.sif), particularly with commands like `Client.run` or `Client.execute`, ensure you provide the full, absolute path to the image. Relative paths can lead to `FileNotFoundError` if `spython`'s internal working directory differs from your script's execution context.

fix

Use `os.path.abspath()` or provide full paths to `.sif` files when invoking `spython` commands.

affects: All versions

breakingVersion `0.3.0` introduced changes to how `WORKDIR` is matched when converting Dockerfile-like recipes to Singularity recipes. This might affect the interpretation of `WORKDIR` directives within containers if you are programmatically building or converting recipes using `spython` from versions prior to `0.3.0`.

fix

Review and test any workflows that programmatically create or convert Singularity recipes, specifically checking `WORKDIR` behavior, if upgrading from `spython < 0.3.0`.

affects: >=0.3.0

Errors

Common errors & fixes

Singularity container executable not found. Please install Singularity or Apptainer.

The Singularity or Apptainer container engine is not installed on the system, or its executable is not in the system's PATH.

fix

Install Apptainer (or Singularity) on your system and ensure the `singularity` or `apptainer` executable is available in your shell's PATH, or set the `SINGULARITY_PATH` environment variable to its full path.

ModuleNotFoundError: No module named 'spython'

The `spython` Python package has not been installed in the current Python environment.

fix

Install the package using pip: `pip install spython`.

AttributeError: 'Singularity' object has no attribute 'pull'

The `spython.main.Singularity` class is not intended for direct instantiation and method calling for core commands like `pull` or `build`; these commands are exposed as static methods of `spython.main.Client`.

fix

Use the `Client` class to execute commands directly: `from spython.main import Client; Client.pull("library://alpine:latest")`.

ModuleNotFoundError: No module named 'singularity'

The `spython` library is incorrectly imported from a non-existent `singularity` module instead of the actual `spython` package.

fix

Use the correct package name for imports, such as `from spython.main import Client` or `from spython.main import Singularity`.

Upgrade

Version history

0.3.14latest on PyPI · released Sep 15, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/singularityhub/singularity-cli ↗

packagehttps://pypi.org/project/spython/ ↗