Executable#

class Executable(name: str | Path)#

Create a callable object for the executable name

Parameters:

name – The path to an executable which is run when called. If name is not an absolute or relative path on the filesystem, the path to the executable is looked for on PATH.

Examples

>>> ls = Executable("ls")
>>> result = ls("-la", stdout=os.devnull)
>>> result.returncode
0
static find(name: str | Path) → Path#

Find the path to the command name

property command: str#

The command-line string.

Returns:

The executable and default arguments

Return type:

str

property name: str#

The executable name.

Returns:

The basename of the executable

Return type:

str

property path: Path#

The path to the executable.

Returns:

The path to the executable

Return type:

str

add_default_args(*args: str) → None#

Add flags to this executable’s default arguments

add_default_env(*args: dict[str, str], **kwargs: str) → None#

Add variables to this executable’s runtime environment

Parameters:

  • args – A dictionary of environment variables

  • kwargs – Environment variables

__call__(*args_in: str, stdout: type[str] | TextIO | Path | str | None = None, stderr: type[str] | TextIO | Path | str | None = None, output: type[str] | TextIO | Path | str | None = None, error: type[str] | TextIO | Path | str | None = None, env: dict[str, str] | None = None, expected_returncode: int = 0, fail_on_error: bool = True, timeout: float = -1.0, verbose: bool = False) → Result#

Run this executable in a subprocess.

Parameters:

*args_in – Command-line arguments to the executable to run

Keyword Arguments:

  • env – The environment to run the executable with

  • fail_on_error – Raise an exception if the subprocess returns an error. Default is True. The return code is available as exe.returncode

  • expected_returncode – Expected returncode. If expected_returncode < 0, this process will not raise an exception even if fail_on_error is set to True

  • stdout – Where to send stdout

  • stderr – Where to send stderr

  • output – Alias for stdout

  • error – Alias for stderr

  • verbose – Write the command line to output

Returns:

A Result dataclass with the following members:

result.cmd: The command line result.returncode: Exit code from subprocess result.out, result.err: See discussion below

Return type:

result

Accepted values for stdout and stderr:

  • python streams, e.g. open Python file objects, or os.devnull

  • filenames, which will be automatically opened for writing

  • str, as in the Python string type. If you set these to str, result.out and result.err will contain the processes stdout and stderr, respectively, as strings.