cotainr.container module#

cotainr - a user space Apptainer/Singularity container builder.

This module implements the interaction with the container runtime.

Classes#

SingularitySandbox: A Singularity container sandbox context manager.

API reference#

class cotainr.container.SingularitySandbox(*, base_image)#

Bases: object

A Singularity container sandbox context manager.

This creates and manipulates a Singularity sandbox, i.e. a temporary directory representing the container. As a final step, the sandbox should be converted into a SIF container image file.

Parameters:

base_imagestr: Base image to use for the container which may be any valid Apptainer/Singularity <BUILD SPEC>.

Attributes:

base_imagestr: Base image to use for the container.
sandbox_diros.PathLike or None: The path to the temporary directory containing the sandbox if within a sandbox context, otherwise it is None.

Methods

`add_metadata`()	Add metadata to the container sandbox.
`add_to_env`(*, shell_script)	Add shell_script to the sourced environment in the container.
`build_image`(*, path)	Build a SIF image file from sandbox.
`run_command_in_container`(*, cmd)	Run a command in the container sandbox.

add_metadata()#

Add metadata to the container sandbox.

The following metadata is added to the container sandbox:

“cotainr.command”: The full command line used to build the container.
“cotainr.version”: The version of cotainr used to build the container.
“cotainr.url”: The cotainr project url.

The container metadata may be inspected by running singularity inspect on the built container image file.

Notes

The metadata entries are added to the .singularity.d/labels.json file.

add_to_env(*, shell_script)#

Add shell_script to the sourced environment in the container.

The content of shell_script is written as-is to the /environment file in the Singularity container which is sourced on execution of the container.

Parameters:

shell_scriptstr: The shell script to add to the sourced environment in the container.

build_image(*, path)#

Build a SIF image file from sandbox.

Takes the current content of the sandbox and builds a SIF container image from it. The container image is outputted to path.

Parameters:

pathos.PathLike: Path to the built container image.

run_command_in_container(*, cmd)#

Run a command in the container sandbox.

Wraps singularity exec of the cmd in the container sandbox` allowing for running commands inside the container sandbox context, e.g. for installing software in the container sandbox.

Parameters:

cmdstr: The command to run in the container sandbox.

Returns:

processsubprocess.CompletedProcess: Information about the process that ran in the container sandbox.

Notes

The command is run with –no-home for maximum compatibility (e.g. trying to mount the home folder on LUMI causes problems). Thus, when running a command in the container, you cannot reference files in your home directory. Instead you must copy all files into the container sandbox and then reference the files relative to the container root.