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.

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.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 ret 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.
• err – Deprecated - use stderr instead.
• ret – Deprecated - use exitcode instead.
• 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: If True, the command itself is logged to the

    standard output stream(s).

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.runfsl(*args, **kwargs)

Call a FSL command and return its output. This function simply prepends $FSLDIR/bin/ to the command before passing it to run().

fsl.utils.run.wait(job_ids)

Proxy for fslsub.wait().