cotainr.util module#

cotainr - a user space Apptainer/Singularity container builder.

This module implements utility functions.

Functions#

stream_subprocess(*, args, **kwargs): Run a the command described by args while streaming stdout and stderr.
get_systems(): Get a dictionary of predefined systems, defined in systems.json

Attributes#

systems_file: The path to the systems.json file (if present).

API reference#

cotainr.util.get_systems()#

Get a dictionary of predefined systems, defined in the systems.json file.

Returns:

systemsDict: A dictionary of predefined systems

Raises:

NameError: If some required arguments are missing in the systems.json file.

cotainr.util.stream_subprocess(*, args, log_dispatcher=None, **kwargs)#

Run a the command described by args while streaming stdout and stderr.

The command described by args is run in a subprocess with that subprocess’ stdout and stderr streamed to the main process. Each line in the subprocess’ output is streamed separately to the main process. Extra kwargs are passed to Popen when opening the subprocess.

Parameters:

argslist or str: Program arguments. See the docstring for subprocess.Popen for details.
log_dispatcherLogDispatcher, optional: The log dispatcher which subprocess stdout/stderr messages are forwarded to (the default is None which implies that subprocess messages are forwarded directly to stdout/stderr).

Returns:

completed_processsubprocess.CompletedProcess: Information about the completed subprocess.

Raises:

subprocess.CalledProcessError: If the subprocess returned a non-zero status code.

Notes

The way we handle stdout and stderr messages in separate threads introduces a race condition in cases where subprocesses write to stdout and stderr at the same time. All messages are always guaranteed to be streamed to the console, but they might arrive in the wrong order. We accept this “feature” as is.