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.
Call a command and return its output. |
|
Call a FSL command and return its output. |
|
Proxy for |
|
Context manager which causes all calls to |
-
fsl.utils.run.
DRY_RUN
= False¶ If
True
, therun()
function will only log commands, but will not execute them.
-
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 theDRY_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 toTrue
.- Parameters
stdout – Must be passed as a keyword argument. Defaults to
True
. IfTrue
, standard output is captured and returned. Ignored ifsubmit
is specified.stderr – Must be passed as a keyword argument. Defaults to
False
. IfTrue
, standard error is captured and returned. Ignored ifsubmit
is specified.exitcode – Must be passed as a keyword argument. Defaults to
False
. IfTrue
, and the command’s return code is non-0, an exception is not raised. Ignored ifsubmit
is specified.submit – Must be passed as a keyword argument. Defaults to
None
. IfTrue
, the command is submitted as a cluster job via thefslsub.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.
- tee: If
- 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 offslsub()
is returned. Otherwise returns a single value or a tuple, based on the based on thestdout
,stderr
, andexitcode
arguments.
-
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):
FSL_PREFIX
$FSLDEVDIR/bin
$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()
.