spython.main.base package

Submodules

spython.main.base.command module

spython.main.base.command.generate_bind_list(self, bindlist=None)[source]
generate bind string will take a single string or list of binds, and
return a list that can be added to an exec or run command. For example, the following map as follows:

[‘/host:/container’, ‘/both’] –> [“–bind”, “/host:/container”,”–bind”,”/both” ] [‘/both’] –> [“–bind”, “/both”] ‘/host:container’ –> [“–bind”, “/host:container”]

None –> []

An empty bind or otherwise value of None should return an empty list. The binds are also checked on the host.

bindlist: a string or list of bind mounts

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

return the initial Singularity command with any added flags.

Parameters:
  • 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, capture=True, quiet=None, return_result=False)[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.

Parameters:
  • cmd (the command to run)
  • sudo (does the command require sudo?)
  • quiet (if quiet set by function, overrides client setting.)
  • return_result (return the result, if not successful (default False).)
  • On success, returns result.
spython.main.base.command.send_command(self, cmd, sudo=False, stderr=None, stdout=None)[source]

send command is a non interactive version of run_command, meaning that we execute the command and return the return value, but don’t attempt to stream any content (text from the screen) back to the user. This is useful for commands interacting with OCI bundles.

Parameters:
  • cmd (the list of commands to send to the terminal)
  • sudo (use sudo (or not))

spython.main.base.flags module

spython.main.base.flags.parse_verbosity(self, args)[source]

parse_verbosity will take an argument object, and return the args passed (from a dictionary) to a list

Parameters:args (the argparse argument objects)

spython.main.base.generate module

class spython.main.base.generate.RobotNamer[source]

Bases: object

generate(delim='-', length=4, chars='0123456789')[source]
Generate a robot name. Inspiration from Haikunator, but much more
poorly implemented ;)
Parameters:
  • delim (Delimiter)
  • length (TokenLength)
  • chars (TokenChars)
spython.main.base.generate.main()[source]

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

Parameters:
  • 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.

Parameters:
  • image (the uri to base off of)
  • ext (the extension to use)
spython.main.base.sutils.get_uri(self)[source]

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

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

Module contents

class spython.main.base.Client[source]

Bases: object

RobotNamer = <spython.main.base.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 https://sci-f.github.io

Parameters:
  • 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, stream=False)

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 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)
debug = False
execute(image=None, command=None, app=None, writable=False, contain=False, bind=None, stream=False, nv=False)

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
  • 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))
help(command=None)

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.image.cmd.generate_image_commands.<locals>.ImageClient object>
inspect(image=None, json=True, app=None, quiet=True)

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)
instance

alias of Instance

instance_stopall(sudo=False, quiet=True)

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)
instances(name=None, return_json=False, quiet=False)

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

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))
  • Return Code – Reason
  • 0 – Instances Found
  • 1 – No Instances, libexecdir value not found, functions file not found
  • 255 – Couldn’t get UID
load(image=None)

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)
oci = [singularity-python-oci]
pull(image=None, name=None, pull_folder='', ext='simg', force=False, capture=False, name_by_commit=False, name_by_hash=False, stream=False)

pull will pull a singularity hub or Docker image

Parameters:
  • 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, bind=None, stream=False, nv=False)

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)
  • 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))
setenv(variable, value)

set an environment variable for Singularity

Parameters:
  • variable (the variable to set)
  • value (the value to set)
version()[source]

a wrapped to get_singularity_version, takes no arguments.