Singularity Python API Main


spython.main.base.command module

spython.main.base.command.init_command(self, action, flags=None)[source]

return the initial Singularity command with any added flags.

  • action (the main action to perform (e.g., build))
  • flags (one or more additional flags (e.g, volumes)) – not implemented yet.
spython.main.base.command.run_command(self, cmd, sudo=False, quiet=False, capture=True)[source]

run_command is a wrapper for the global run_command, checking first for sudo and exiting on error if needed. The message is returned as a list of lines for the calling function to parse, and stdout uses the parent process so it appears for the user.

  • cmd (the command to run)
  • sudo (does the command require sudo?)
  • On success, returns result. Otherwise, exists on error

spython.main.base.logger module

spython.main.base.logger.init_level(self, quiet=False)[source]

set the logging level based on the environment

Parameters:quiet (boolean if True, set to quiet. Gets overriden by environment) – setting, and only exists to define default
spython.main.base.logger.println(self, output, quiet=False)[source]

print will print the output, given that quiet is not True. This function also serves to convert output in bytes to utf-8

  • output (the string to print)
  • quiet (a runtime variable to over-ride the default.)

spython.main.base.sutils module

spython.main.base.sutils.get_filename(self, image=None, ext='simg')[source]

return an image filename based on the image uri. If an image uri is not specified, we look for the loaded image.

  • image (the uri to base off of)
  • ext (the extension to use)

check if the loaded image object (self.simage) has an associated uri return if yes, None if not.

spython.main.base.sutils.load(self, image=None)[source]

load an image, either an actual path on the filesystem or a uri.

Parameters:image (the image path or uri to load (e.g., docker://ubuntu)
spython.main.base.sutils.setenv(self, variable, value)[source]

set an environment variable for Singularity

  • variable (the variable to set)
  • value (the value to set)

Module contents

class spython.main.base.Client[source]

Bases: object

RobotNamer = <spython.main.image.generate.RobotNamer object>
apps(image=None, full_path=False, root='')

return list of SCIF apps in image. The Singularity software serves a scientific filesystem integration that will install apps to /scif/apps and associated data to /scif/data. For more information about SCIF, see

  • full_path (if True, return relative to scif base folder)
  • image_path (full path to the image)
build(recipe=None, image=None, isolated=False, sandbox=False, writable=False, build_folder=None, robot_name=False, ext='simg', sudo=True)

build a singularity image, optionally for an isolated build (requires sudo).

  • recipe (the path to the recipe file (or source to build from). If not) – defined, we look for “Singularity” file in $PWD
  • image (the image to build (if None, will use arbitary name)
  • isolated (if True, run build with –isolated flag)
  • sandbox (if True, create a writable sandbox)
  • writable (if True, use writable ext3 (sandbox takes preference))
  • build_folder (where the container should be built.)
  • ext (the image extension to use.)
  • robot_name (boolean, default False. if you don’t give your image a) – name (with “image”) then a fun robot name will be generated instead. Highly recommended :)
  • sudo (give sudo to the command (or not) default is True for build)

ensure that singularity is installed, and exit if not.

debug = False
execute(image=None, command=None, app=None, writable=False, contain=False)

execute: send a command to a container

  • image (full path to singularity image)
  • command (command to send to container)
  • app (if not None, execute a command in context of an app)
  • writable (This option makes the file system accessible as read/write)
  • contain (This option disables the automatic sharing of writable) – filesystems on your host

help prints the general function help, or help for a specific command

Parameters:command (the command to get help for, if none, prints general help)
image = <spython.main.image.generate_image_commands.<locals>.ImageClient object>
inspect(image=None, json=True, app=None)

inspect will show labels, defile, runscript, and tests for an image

  • image_path (path of image to inspect)
  • json (print json instead of raw text (default True))
  • app (if defined, return help in context of an app)

load an image, either an actual path on the filesystem or a uri.

Parameters:image (the image path or uri to load (e.g., docker://ubuntu)
pull(image=None, name=None, pull_folder='', ext='simg')

pull will pull a singularity hub or Docker image

  • image (the complete image uri. If not provided, the client loaded is used)
  • pull_folder (if not defined, pulls to $PWD (‘’). If defined, pulls to) – user specified location instead.
  • Docker and Singularity Hub Naming
  • ———————————
  • name (a custom name to use, to override default)
  • ext (if no name specified, the default extension to use.)
quiet = False
run(image=None, args=None, app=None, sudo=False, writable=False, contain=False)

run will run the container, with or withour arguments (which should be provided in a list)

  • image (full path to singularity image)
  • args (args to include with the run)
setenv(variable, value)

set an environment variable for Singularity

  • variable (the variable to set)
  • value (the value to set)

return the version of singularity