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

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)

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)

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

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 fslsub.submit() function.

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)

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

• 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.wait(job_ids)

Proxy for fslsub.wait().