fsl.utils.run

This module provides some functions for running shell commands.

Note

The functions in this module are only known to work in Unix-like environments.

run	Call a command and return its output.
runfsl	Call a FSL command and return its output.
runfunc	Run the given python function as a shell command.
func_to_cmd	Save the given python function to an executable file.
dryrun	Context manager which causes all calls to run() to be logged but not executed.
hold	Waits until all specified cluster jobs have finished.
job_output	Returns the output of the given cluster-submitted job.

fsl.utils.run.DRY_RUN = False

If True, the run() function will only log commands, but will not execute them.

fsl.utils.run.DRY_RUN_COMMANDS = None

Contains the commands that got logged during a dry run.

Commands will be logged if DRY_RUN is true, which can be set using dryrun().

fsl.utils.run.FSL_PREFIX = None

Global override for the FSL executable location used by runfsl().

exception fsl.utils.run.FSLNotPresent

Bases: Exception

Error raised by the runfsl() function when $FSLDIR cannot be found.

__module__ = 'fsl.utils.run'

__weakref__

list of weak references to the object (if defined)

fsl.utils.run.dryrun(*_)

Context manager which causes all calls to run() to be logged but not executed. See the DRY_RUN flag.

The returned standard output will be equal to ' '.join(args).

After this function returns, each command that was executed while the dryrun is active, along with any submission parameters, will be accessible within a list which is stored as DRY_RUN_COMMANDS.

fsl.utils.run.prepareArgs(args)

Used by the run() function. Ensures that the given arguments is a list of strings.

fsl.utils.run._forwardStream(in_, *outs)

Creates and starts a daemon thread which forwards the given input stream to one or more output streams. Used by the run() function to redirect a command’s standard output/error streams to more than one destination.

It is necessary to read the process stdout/ stderr on separate threads to avoid deadlocks.

Parameters:

• in – Input stream

• outs – Output stream(s)

Returns:

The thread that has been started.

fsl.utils.run.run(*args, **kwargs)

Call a command and return its output. You can pass the command and arguments as a single string, or as a regular or unpacked sequence.

The command can be run on a cluster by using the submit keyword argument.

An exception is raised if the command returns a non-zero exit code, unless the exitcode option is set to True.

Parameters:

• stdout – Must be passed as a keyword argument. Defaults to True. If True, standard output is captured and returned. Ignored if submit is specified.

• stderr – Must be passed as a keyword argument. Defaults to False. If True, standard error is captured and returned. Ignored if submit is specified.

• exitcode – Must be passed as a keyword argument. Defaults to False. If True, and the command’s return code is non-0, an exception is not raised. Ignored if submit is specified.

• submit – Must be passed as a keyword argument. Defaults to None. If True, the command is submitted as a cluster job via the fsl.wrappers.fsl_sub function. May also be a dictionary containing arguments to that function.

• cmdonly – Defaults to False. If True, the command is not executed, but rather is returned directly, as a list of arguments.

• log –

  Must be passed as a keyword argument. Defaults to {'tee' : True}. An optional dict which may be used to redirect the command’s standard output and error. Ignored if submit is specified. The following keys are recognised:

  • tee: If True (the default), the command’s

    standard output/error streams are forwarded to the output streams of this process, in addition to being captured and returned.

  • stdout: Optional callable or file-like object to which

    the command’s standard output stream can be forwarded.

  • stderr: Optional callable or file-like object to which

    the command’s standard error stream can be forwarded.

  • cmd: Optional callable or file-like object to which

    the command itself is logged.

• silent – Suppress standard output/error. Equivalent to passing log={'tee' : False}. Ignored if log is also passed.

All other keyword arguments are passed through to the subprocess.Popen object (via _realrun()), unless submit=True, in which case they are passed through to the fsl_sub() function.

Returns:

If submit is provided, the ID of the submitted job is returned as a string. Otherwise returns a single value or a tuple, based on the based on the stdout, stderr, and exitcode arguments.

fsl.utils.run._dryrun(submit, returnStdout, returnStderr, returnExitcode, *args)

Used by the run() function when the DRY_RUN flag is active.

fsl.utils.run._realrun(tee, logStdout, logStderr, logCmd, *args, **kwargs)

Used by run(). Runs the given command and manages its standard output and error streams.

Parameters:

• tee – If True, the command’s standard output and error streams are forwarded to this process’ standard output/ error.

• logStdout – Optional callable or file-like object to which the command’s standard output stream can be forwarded.

• logStderr – Optional callable or file-like object to which the command’s standard error stream can be forwarded.

• logCmd – Optional callable or file-like to which the command itself is logged.

• args – Command to run

• kwargs – Passed through to the subprocess.Popen object.

Returns:

A tuple containing: - the command’s standard output as a string. - the command’s standard error as a string. - the command’s exit code.

fsl.utils.run.runfsl(*args, **kwargs)

Call a FSL command and return its output.

This function searches for the command in the following locations (ordered by priority):

1. FSL_PREFIX

2. $FSLDEVDIR/bin

3. $FSLDIR/bin

If found, the full path to the command is then passed to run().

fsl.utils.run.runfunc(func, args=None, kwargs=None, tmp_dir=None, clean='never', verbose=False, **run_kwargs)

Run the given python function as a shell command. See func_to_cmd() for details on the arguments.

The remaining run_kwargs arguments are passed through to the run() function.

fsl.utils.run.func_to_cmd(func, args=None, kwargs=None, tmp_dir=None, clean='never', verbose=False)

Save the given python function to an executable file. Return a string containing a command that can be used to run the function.

..warning:: If submitting a function defined in the __main__ script,

the script will be run again to retrieve this function. Make sure there is a if __name__ == '__main__' guard to prevent the full script from being re-run.

Parameters:

• func – function to be run

• args – positional arguments

• kwargs – keyword arguments

• tmp_dir – directory where to store the temporary file (default: the system temporary directory)

• clean –

  Whether the script should be removed after running. There are three options:

  • "never": (default) Script is kept

  • "on_success": only remove if script successfully

    finished (i.e., no error is raised)

  • "always": always remove the script, even if it

    raises an error

• verbose – If set to True, the script will print its own filename before running

fsl.utils.run.wslcmd(cmdpath, *args)

Convert a command + arguments into an equivalent set of arguments that will run the command under Windows Subsystem for Linux

Parameters:

• cmdpath – Fully qualified path to the command. This is essentially a WSL path not a Windows one since FSLDIR is specified as a WSL path, however it may have backslashes as path separators due to previous use of os.path.join

• args – Sequence of command arguments (the first of which is the unqualified command name)

Returns:

If cmdpath exists and is executable in WSL, return a sequence of command arguments which when executed will run the command in WSL. Windows paths in the argument list will be converted to WSL paths. If cmdpath was not executable in WSL, returns None

fsl.utils.run.hold(job_ids, hold_filename=None, timeout=10)

Waits until all specified cluster jobs have finished.

Parameters:

• job_ids – Possibly nested sequence of job ids. The job ids themselves should be strings.

• hold_filename – Filename to use as a hold file. The containing directory should exist, but the file itself should not. Defaults to a ./.<random characters>.hold in the current directory.

• timeout – Number of seconds to sleep between status checks.

fsl.utils.run.job_output(job_id, logdir='.', command=None, name=None)

Returns the output of the given cluster-submitted job.

On SGE cluster systems, the standard output and error streams of a submitted job are saved to files named <job_id>.o and <job_id>.e. This function simply reads those files and returns their content.

Parameters:

• job_id – String containing job ID.

• logdir – Directory containing the log - defaults to the current directory.

• command – Command that was run. Not currently used.

• name – Job name if it was specified. Not currently used.

Returns:

A tuple containing the standard output and standard error.