spython.main package

Submodules

spython.main.apps module

spython.main.apps.apps(self, image=None, full_path=False, root='')[source]

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 https://sci-f.github.io. Note that this seems to be deprecated in Singularity 3.x.

Parameters:
  • full_path (if True, return relative to scif base folder)
  • image_path (full path to the image)

spython.main.build module

spython.main.build.build(self, recipe=None, image=None, isolated=False, sandbox=False, writable=False, build_folder=None, robot_name=False, ext='sif', sudo=True, stream=False, force=False, options=None, quiet=False, return_result=False, sudo_options=None, singularity_options=None)[source]

build a singularity image, optionally for an isolated build (requires sudo). If you specify to stream, expect the image name and an iterator to be returned.

image, builder = Client.build(…)

Parameters:
  • 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 arbitrary 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)
  • sudo_options (options to pass to sudo (e.g. –preserve-env=SINGULARITY_CACHEDIR,SINGULARITY_TMPDIR))
  • options (for all other options, specify them in this list.)
  • singularity_options (a list of options to provide to the singularity client)
  • quiet (quiet verbose printing from the client.)
  • return_result (if True, return complete error code / message dictionary)

spython.main.execute module

spython.main.execute.execute(self, image=None, command=None, app=None, writable=False, contain=False, bind=None, stream=False, nv=False, return_result=False, options=None, singularity_options=None, sudo=False, sudo_options=None, quiet=True, environ=None)[source]

execute: send a command to a container

Parameters:
  • 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
  • options (an optional list of options to provide to execute.)
  • singularity_options (a list of options to provide to the singularity client)
  • bind (list or single string of bind paths.) – This option allows you to map directories on your host system to directories within your container using bind mounts
  • nv (if True, load Nvidia Drivers in runtime (default False))
  • return_result (if True, return entire json object with return code) – and message result not (default)
  • quiet (Do not print verbose output.)
  • environ (extra environment to add.)
spython.main.execute.shell(self, image, app=None, writable=False, contain=False, bind=None, nv=False, options=None, singularity_options=None, sudo=False, quiet=True)[source]

shell into a container. A user is advised to use singularity to do this directly, however this function is useful for supporting tools.

Parameters:
  • image (full path to singularity image)
  • app (if not None, execute a shell 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
  • options (an optional list of options to provide to shell.)
  • singularity_options (a list of options to provide to the singularity client)
  • bind (list or single string of bind paths.) – This option allows you to map directories on your host system to directories within your container using bind mounts
  • nv (if True, load Nvidia Drivers in runtime (default False))

spython.main.help module

spython.main.help.helpcmd(self, command=None)[source]

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)

spython.main.inspect module

spython.main.inspect.inspect(self, image=None, json=True, app=None, quiet=True, singularity_options=None)[source]

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

Parameters:
  • image (path of image to inspect)
  • json (print json instead of raw text (default True))
  • quiet (Don’t print result to the screen (default True))
  • app (if defined, return help in context of an app)
  • singularity_options (a list of options to provide to the singularity client)
spython.main.inspect.parse_labels(result)[source]

fix up the labels, meaning parse to json if needed, and return original updated object

Parameters:result (the json object to parse from inspect)

spython.main.instances module

spython.main.instances.list_instances(self, name=None, return_json=False, quiet=False, sudo=False, sudo_options=None, singularity_options=None)[source]

list instances. For Singularity, this is provided as a command sub group.

singularity instance list

Return codes provided are different from standard linux: see https://github.com/singularityware/singularity/issues/1706 Since we expect json output, we don’t support older versions of Singularity.

Parameters:
  • return_json (return a json list of instances instead of objects (False))
  • name (if defined, return the list for just one instance (used to ged pid))
  • singularity_options (a list of options to provide to the singularity client)
  • Return Code – Reason
  • 0 – Instances Found
  • 1 – No Instances, libexecdir value not found, functions file not found
  • 255 – Couldn’t get UID
spython.main.instances.stopall(self, sudo=False, quiet=True, singularity_options=None)[source]

stop ALL instances. This command is only added to the command group as it doesn’t make sense to call from a single instance

Parameters:sudo (if the command should be done with sudo (exposes different set of) – instances)

spython.main.pull module

spython.main.pull.pull(self, image=None, name=None, pull_folder='', ext='sif', force=False, capture=False, stream=False, quiet=False, singularity_options=None)[source]

pull will pull a singularity hub or Docker image

Parameters:
  • image (the complete image uri. If not provided, the client loaded is used)
  • singularity_options (a list of options to provide to the singularity client)
  • 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.)

spython.main.run module

spython.main.run.run(self, image=None, args=None, app=None, sudo=False, writable=False, contain=False, bind=None, stream=False, nv=False, options=None, singularity_options=None, return_result=False, quiet=False)[source]

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

Parameters:
  • image (full path to singularity image)
  • args (args to include with the run)
  • app (if not None, execute a command in context of an app)
  • writable (This option makes the file system accessible as read/write)
  • options (an optional list of options to provide to run.)
  • singularity_options (a list of options to provide to the singularity client)
  • contain (This option disables the automatic sharing of writable) – filesystems on your host
  • bind (list or single string of bind paths.) – This option allows you to map directories on your host system to directories within your container using bind mounts
  • stream (if True, return <generator> for the user to run)
  • nv (if True, load Nvidia Drivers in runtime (default False))
  • return_result (if True, return entire json object with return code) – and message result (default is False)
  • quiet (print the command to the user)

Module contents

spython.main.get_client(quiet=False, debug=False)[source]

get the client and perform imports not on init, in case there are any initialization or import errors.

Parameters:
  • quiet (if True, suppress most output about the client)
  • debug (turn on debugging mode)