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.

dryrun

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

hold

Waits until all jobs have finished

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.

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

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

fsl.utils.run._realrun(tee, logStdout, logStderr, logCmd, *args, **kwargs)[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

  • 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)[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.wslcmd(cmdpath, *args)[source]

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

Waits until all 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.

Returns

only returns when all the jobs have finished