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