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.
wait Proxy for fslsub.wait().
dryrun Context manager which causes all calls to run() to be logged but not executed.
fsl.utils.run.DRY_RUN = False

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

fsl.utils.run.FSL_PREFIX = None

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

exception fsl.utils.run.FSLNotPresent[source]

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(*args)[source]

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

fsl.utils.run.prepareArgs(args)[source]

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

fsl.utils.run._forwardStream(in_, *outs)[source]

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)[source]

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 fslsub.submit() function. May also be a dictionary containing arguments to that function.
  • log

    Must be passed as a keyword argument. An optional dict which may be used to redirect the command’s standard output and error. The following keys are recognised:

    • tee: If True, the command’s standard output/error
      streams are forwarded to this processes streams.
    • stdout: Optional file-like object to which the command’s
      standard output stream can be forwarded.
    • stderr: Optional file-like object to which the command’s
      standard error stream can be forwarded.
    • cmd: Optional file-like object to which the command
      itself is logged.
Returns:

If submit is provided, the return value of fslsub() is returned. 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)[source]

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

fsl.utils.run._realrun(tee, logStdout, logStderr, logCmd, *args)[source]

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 file-like object to which the command’s standard output stream can be forwarded.
  • logStderr – Optional file-like object to which the command’s standard error stream can be forwarded.
  • logCmd – Optional file-like object to which the command itself is logged.
  • args – Command to run
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)[source]

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.wait(job_ids)[source]

Proxy for fslsub.wait().