tfep.utils.cli.tool.CLITool

class tfep.utils.cli.tool.CLITool(*args, executable_path=None, **kwargs)

Bases: object

Command line tool wrapper.

The class mainly fulfills two roles:

1. Encapsulates input and outputs of a command and provide a command specification that can be understood by tfep.utils.cli.Launcher.

2. Converts and sanitizes Python types to string command line parameters.

3. Provides CLI interfaces with readable parameter names avoiding abbreviations that makes the code harder to read.

Wrapping a new command line tool requires creating a new class that inherits from CLITool and defines its arguments using the options descriptors such as AbsolutePathOption and FlagOption (see examples below).

The constructor takes as input ordered and keyword arguments. Keyword arguments must match those defined with the option descriptors when the wrapper is declared. Ordered arguments must be strings are appended to the command as strings.

The path to the executable (or simply the executable name if it is in the system path) can be set globally through the class variable EXECUTABLE_PATH, or it can be specific to the command instance as specified in the constructor.

To associate a command to a particular subprogram, you can use the SUBPROGRAM class variable. E.g., for the gmx program in the GROMACS suite, creating CLITool that prepare a gmx mdrun ... command requires

setting SUBPROGRAM = 'mdrun'.

Once defined and instantiated, a command can be run either using a Launcher class or the standard module subprocess after building the command with the CLITool.to_subprocess() method.

Parameters:

executable_path (str, optional) – The executable path associated to the instance of the command. If this is not specified, the EXECUTABLE_PATH class variable is used instead.

See also

None

Launch and run commands.

Examples

Suppose we want to create a wrapper for a subset of the command grep that supports reading the pattern from a file. We can create a wrapper with the following syntax

>>> class MyGrep(CLITool):
...     EXECUTABLE_PATH = 'grep'
...     patterns_file_path = KeyValueOption('-f')
...     max_count = KeyValueOption('-m')
...     print_version = FlagOption('-v')

You can then create an command instance specifying the options. For example, FlagOption`s takes either ``True` or False.

>>> my_grep_cmd = MyGrep(print_version=True)

You can then pass the command to a Launcher or use the CLITool.to_subprocess() method can be used to convert the command to a sanitized list that can be executed by the Python standard module subprocess.

>>> my_grep_cmd.to_subprocess()
['grep', '-v']

Another example more complex example

>>> my_grep_cmd = MyGrep('input.txt', patterns_file_path='my_patterns.txt', max_count=3)
>>> my_grep_cmd.to_subprocess()
['grep', '-m', '3', '-f', 'my_patterns.txt', 'input.txt']

__init__(*args, executable_path=None, **kwargs)

Methods

__init__(*args[, executable_path])
to_subprocess()	Convert the command to a list that can be run with the subprocess module.

Attributes

SUBPROGRAM
executable_path	The path to the command executable to run.

property executable_path

The path to the command executable to run.

to_subprocess()

Convert the command to a list that can be run with the subprocess module.

Returns:

subprocess_cmd – The command in subprocess format. For example ['grep', '-v'].

Return type:

List[str]