tfep.utils.cli.launcher.Launcher

class tfep.utils.cli.launcher.Launcher[source]

Bases: object

Runs an executable as a standard command line subprocess.

The class can run a command that is specified either as a list of strings (in the same format used by the standard module subprocess) or as a tfep.utils.cli.CLITool. See the documentation of CLITool for details on how to create a CLI wrapper compatible with Launcher.

Note

When commands are run in a different working directory, relative file/directory paths passed as command arguments are interpreted relative to the specified working directory.

To avoid this behavior, you can either specify absolute paths or use the CLI options tfep.utils.cli.AbsolutePathOption when wrapping your command with CLITool.

See also

tfep.utils.cli.CLITool: CLI wrapper utility.

Examples

>>> launcher = Launcher()
>>> result = launcher.run(['echo', 'print this'], capture_output=True, text=True)
>>> print(result.stdout.strip())
print this

For more complicated cases, it may be convenient to use the CLI wrapping utilities in tfep.utils.cli

>>> import tfep.utils.cli
>>> class Echo(tfep.utils.cli.CLITool):
...     EXECUTABLE_PATH = 'echo'
...
>>> echo_cmd = Echo('print this')
>>> result = launcher.run(echo_cmd, capture_output=True, text=True)
>>> print(result.stdout.strip())
print this

It is possible to launch multiple commands in parallel and obtain the results of all of them.

>>> results = launcher.run(Echo('print1'), Echo('print2'), capture_output=True, text=True)
>>> for res in results:
...     print(res.stdout.strip())
...
print1
print2

__init__()

Methods

`__init__`()
`run`(*commands[, capture_output, timeout, ...])	Run one or more subprocesses in parallel.

run(*commands, capture_output=False, timeout=None, check=False, stdin=None, stdout=None, stderr=None, cwd=None, **kwargs)[source]

Run one or more subprocesses in parallel.

The method runs all the commands in parallel and waits for all of them to complete, collects their output (if capture_output is set) and return them.

Currently, the method supports all keyword arguments supported by the subprocess.Popen. Moreover, it handles running multiple processes in parallel, and, for some of the subprocess.Popen such as stdout and cwd, allow to specify process-specific arguments.

Parameters:

commands (List[str] or tfep.utils.cli.CLITool) – One or more commands to execute, either in the same list format used by subprocess.Popen or as a CLITool.
capture_output (bool, optional) – If True, stdout and stderr will be captured and returned as an attribute of the subprocess.CompletedProcess objects. If True, this overwrites the values of the stdout and stderr arguments.
timeout (float, optional) – The timeout (in seconds) is passed to Popen.communicate. If it expires for any of the processes, subprocess.TimeoutExpired error is raised.
check (bool, optional) – If True and the exit code of any of the subprocesses was non-zero, a subprocess.CalledProcessError error is raised.
stdin (optional) – This can take any value accepted by subprocess.Popen. If multiple commands are run, this can be a list specifying one stdin per process.
stdout (optional) – This can take any value accepted by subprocess.Popen. If multiple commands are run, this can be a list specifying one stdout per process.
stderr (optional) – This can take any value accepted by subprocess.Popen. If multiple commands are run, this can be a list specifying one stderr per process.
cwd (str or List[str], optional) – This can take any value accepted by subprocess.Popen. If multiple commands are run, this can be a list specifying one current working directory per process.
**kwargs – Other keyword arguments to pass to subprocess.Popen.

Returns:

result – The object encapsulating the results of the project. If multiple processes are run in parallel, this is a list of results, one for each process.

Return type:

subprocess.CompletedProcess or List[subprocess.CompletedProcess]

Raises:

subprocess.CalledProcessError – If any of the run processes returned a non-zero status and check is True.
subprocess.TimeoutExpired`` – If timeout was set and the timeout expired.