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. |
|
Context manager which causes all calls to |
|
Waits until all jobs have finished |
-
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.
All other keyword arguments are passed through to the
subprocess.Popen
object (via_realrun()
), unlesssubmit=True
, in which case they are passed through to thefslsub.submit()
function.- 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, **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):
FSL_PREFIX
$FSLDEVDIR/bin
$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. Ifcmdpath
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