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 singularity options)
-
spython.main.base.command.run_command(self, cmd, sudo=False, capture=True, quiet=None, return_result=False, sudo_options=None, environ=None)[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).)
- sudo_options (string or list of strings that will be passed as options to sudo)
- 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
- GLOBAL OPTIONS:
-d|–debug Print debugging information -h|–help Display usage summary -s|–silent Only print errors -q|–quiet Suppress all normal output
--version Show application version -v|–verbose Increase verbosity +1 -x|–sh-debug Print shell wrapper debugging information
- GENERAL COMMANDS:
- help Show additional help for a command or container selftest Run some self tests for singularity install
- CONTAINER USAGE COMMANDS:
- exec Execute a command within container run Launch a runscript within container shell Run a Bourne shell within container test Launch a testscript within container
- CONTAINER MANAGEMENT COMMANDS:
- apps List available apps within a container bootstrap Deprecated use build instead build Build a new Singularity container check Perform container lint checks inspect Display container’s metadata mount Mount a Singularity container image pull Pull a Singularity/Docker container to $PWD siflist list data object descriptors of a SIF container image sign Sign a group of data objects in container verify Verify the crypto signature of group of data objects in container
- COMMAND GROUPS:
- capability User’s capabilities management command group image Container image command group instance Persistent instance command group
spython.main.base.generate module
spython.main.base.logger module
spython.main.base.sutils module
-
spython.main.base.sutils.get_filename(self, image, ext='sif', pwd=True)[source] return an image filename based on the image uri.
Parameters: - ext (the extension to use)
- pwd (derive a filename for the pwd)
-
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.
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. 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)
-
build(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) 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)
-
debug= False
-
execute(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) 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.)
-
export(image_path, pipe=False, output_file=None, command=None, sudo=False, singularity_options=None) export will export an image, sudo must be used. Since we have Singularity versions after 3, export is replaced with building into a sandbox.
Parameters: - image_path (full path to image)
- pipe (export to pipe and not file (default, False))
- singularity_options (a list of options to provide to the singularity client)
- output_file (if pipe=False, export tar to this file. If not specified,)
- will generate temporary directory.
-
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)
-
inspect(image=None, json=True, app=None, quiet=True, singularity_options=None) 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)
-
instance alias of
spython.instance.Instance
-
instance_stopall(sudo=False, quiet=True, singularity_options=None) 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, sudo=False, sudo_options=None, singularity_options=None) 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
-
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='sif', force=False, capture=False, stream=False, quiet=False, singularity_options=None) 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.)
-
quiet= False
-
run(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) 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)
-
setenv(variable, value) set an environment variable for Singularity
Parameters: - variable (the variable to set)
- value (the value to set)
-
shell(image, app=None, writable=False, contain=False, bind=None, nv=False, options=None, singularity_options=None, sudo=False, quiet=True) 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))
-