Welcome to ska_shell’s documentation!

Functions

ska_shell.bash(cmdstr, logfile=None, importenv=False, env=None, logger=None, log_level=None, check=None)

Run the cmdstr string in a bash shell. See run_shell for options.

Returns:

bash output

ska_shell.bash_shell(cmdstr, logfile=None, importenv=False, getenv=False, env=None, logger=None, log_level=None, check=None)

Run the command string cmdstr in a bash shell. It can have multiple lines. If exit status is non-zero at any point then processing is terminated and a ShellError exception is raised.

Parameters:

• cmdstr – command string

• shell – shell for command – ‘bash’ (default) or ‘tcsh’

• logfile – append output to the suppplied file object

• importenv – import any environent changes back to python env

• getenv – get the environent changes after running cmdstr

• env – set environment using env dict prior to running commands

• logger – log output to the supplied logging.Logger

• log_level – log level for logger

Return type:

(outlines, deltaenv)

ska_shell.getenv(cmdstr, shell='bash', importenv=False, env=None)

Run the cmdstr string in shell. See run_shell for options.

Returns:

Dict of environment vars update produced by cmdstr

ska_shell.importenv(cmdstr, shell='bash', env=None)

Run cmdstr in a bash shell and import the environment updates into the current python environment (os.environ). See bash_shell for options.

Returns:

Dict of environment vars update produced by cmdstr

ska_shell.run_shell(cmdstr, shell='bash', logfile=None, importenv=False, getenv=False, env=None, logger=None, log_level=None, check=None)

Run the command string cmdstr in a shell (‘bash’ or ‘tcsh’). It can have multiple lines. Each line is separately sent to the shell. The exit status is checked if the shell comes back with a prompt. If exit status is non-zero at any point then processing is terminated and a ShellError exception is raise.

Parameters:

• cmdstr – command string

• shell – shell for command – ‘bash’ (default) or ‘tcsh’

• logfile – append output to the suppplied file object

• importenv – import any environent changes back to python env

• getenv – get the environent changes after running cmdstr

• env – set environment using env dict prior to running commands

• check – raise an exception if any command fails

Return type:

(outlines, deltaenv)

ska_shell.tcsh(cmdstr, logfile=None, importenv=False, env=None, logger=None, log_level=None, check=None)

Run the cmdstr string in a tcsh shell. See run_shell for options.

Returns:

tcsh output

ska_shell.tcsh_shell(cmdstr, logfile=None, importenv=False, getenv=False, env=None, logger=None, log_level=None, check=None)

Run the command string cmdstr in a tcsh shell. It can have multiple lines. If exit status is non-zero at any point then processing is terminated and a ShellError exception is raised.

Parameters:

• cmdstr – command string

• shell – shell for command – ‘bash’ (default) or ‘tcsh’

• logfile – append output to the suppplied file object

• importenv – import any environent changes back to python env

• getenv – get the environent changes after running cmdstr

• env – set environment using env dict prior to running commands

• logger – log output to the supplied logging.Logger

• log_level – log level for logger

Return type:

(outlines, deltaenv)

Classes

class ska_shell.Spawn(stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, timeout=None, catch=False, stderr=-2, shell=False)

Bases: object

Provide methods to run subprocesses in a controlled and simple way. Features:

• Uses the subprocess.Popen() class

• Send stdout and/or stderr output to a file

• Specify a job timeout

• Catch exceptions and log warnings

Example usage:

>>> from ska_shell import Spawn, bash, getenv, importenv
>>>
>>> spawn = Spawn()
>>> status = spawn.run(['echo', 'hello'])
hello
>>> status
0
>>>
>>> try:
...     spawn.run(['bad', 'command'])
... except Exception, error:
...     error
...
OSError(2, 'No such file or directory')
>>> spawn.run(['bad', 'command'], catch=True)
Warning - OSError: [Errno 2] No such file or directory
>>> print spawn.exitstatus
None
>>> print spawn.outlines
['Warning - OSError: [Errno 2] No such file or directory\n']
>>>
>>> spawn = Spawn(stdout=None, shell=True)
>>> spawn.run('echo hello')
0
>>> spawn.run('fail fail fail')
127
>>>
>>> spawn = Spawn(stdout=None, shell=True, stderr=None)
>>> spawn.run('fail fail fail')
127
>>> print spawn.outlines
[]

Additional object attributes:

• openfiles: List of file objects created during init corresponding

  to filenames supplied in outputs list

run(cmd, timeout=None, catch=None, shell=None)

Run the command cmd and abort if timeout is exceeded.

Attributes after run():

• outlines: list of output lines from process

• exitstatus: process exit status or None if an exception occurred

Parameters:

• cmd – list of strings or a string(see Popen docs)

• timeout – command timeout (default: self.timeout)

• catch – catch exceptions (default: self.catch)

• shell – run cmd in shell (default: self.shell)

Return type:

process exit value

Exceptions

class ska_shell.RunTimeoutError

Bases: RuntimeError

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class ska_shell.ShellError

Bases: Exception

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.