exe

Exes/commands

Classes:

• ExeConfig –

  Serializable configuration for an ExeABC subclass

• ExeABC –

  Base class for command/executable wrapper objects

• Exe –

  Callable wrapper around an executable

• ExeAsync –

  Awaitable wrapper around an executable

ExeConfig dataclass

ExeConfig(
    cmd: str,
    subcmd: tuple[str, ...] | None = None,
    abspath: str | None = None,
    env: dict[str, str] | None = None,
    cwd: str | None = None,
    shell: bool = False,
    verbose: bool = False,
    timeout: float | int | None = None,
    ok_code: int | set[int] = (lambda: {0})(),
    check: bool = False,
)

Serializable configuration for an ExeABC subclass

Attributes:

• cmd (str) –

  Name of (or path to) the executable

• subcmd (tuple[str, ...] | None) –

  Sub-command args always prepended to the exe's args

• abspath (str | None) –

  Resolved absolute path to the executable, if known/cached

• env (dict[str, str] | None) –

  Environment variables to run the executable with

• cwd (str | None) –

  Working directory to run the executable in

• shell (bool) –

  Run the executable through the shell

• verbose (bool) –

  Echo stdout/stderr of each run to the parent process

• timeout (float | int | None) –

  Timeout in seconds for each run; None for no timeout

• ok_code (int | set[int]) –

  Return code(s) considered ok

• check (bool) –

  Raise DoneError if the return code is not ok

cmd instance-attribute

cmd: str

Name of (or path to) the executable

subcmd class-attribute instance-attribute

subcmd: tuple[str, ...] | None = None

Sub-command args always prepended to the exe's args

abspath class-attribute instance-attribute

abspath: str | None = None

Resolved absolute path to the executable, if known/cached

env class-attribute instance-attribute

env: dict[str, str] | None = None

Environment variables to run the executable with

cwd class-attribute instance-attribute

cwd: str | None = None

Working directory to run the executable in

shell class-attribute instance-attribute

shell: bool = False

Run the executable through the shell

verbose class-attribute instance-attribute

verbose: bool = False

Echo stdout/stderr of each run to the parent process

timeout class-attribute instance-attribute

timeout: float | int | None = None

Timeout in seconds for each run; None for no timeout

ok_code class-attribute instance-attribute

ok_code: int | set[int] = field(default_factory=lambda: {0})

Return code(s) considered ok

check class-attribute instance-attribute

check: bool = False

Raise DoneError if the return code is not ok

ExeABC

ExeABC(
    cmd: str,
    *,
    subcmd: tuple[str, ...] | list[str] | str | None = None,
    abspath: str | None = None,
    check: bool = False,
    cwd: FsPath | None = None,
    env: dict[str, str] | None = None,
    ok_code: int
    | list[int]
    | tuple[int, ...]
    | set[int] = 0,
    shell: bool = False,
    timeout: float | int | None = None,
    verbose: bool = False,
)

Base class for command/executable wrapper objects

Holds the defaults (env, cwd, timeout, ...) that each invocation of the wrapped executable is run with. Subclassed by Exe and ExeAsync, which make instances callable.

Parameters:

• cmd

  (str) –

  Name of (or path to) the executable

• subcmd

  (tuple[str, ...] | list[str] | str | None, default: None ) –

  Sub-command args always prepended to the exe's args

• abspath

  (str | None, default: None ) –

  Absolute path to the executable; skips the which lookup

• check

  (bool, default: False ) –

  Raise DoneError if the return code is not ok

• cwd

  (FsPath | None, default: None ) –

  Working directory to run the executable in

• env

  (dict[str, str] | None, default: None ) –

  Environment variables to run the executable with

• ok_code

  (int | list[int] | tuple[int, ...] | set[int], default: 0 ) –

  Return code (or collection of return codes) considered ok

• shell

  (bool, default: False ) –

  Run the executable through the shell

• timeout

  (float | int | None, default: None ) –

  Timeout in seconds for each run; None for no timeout

• verbose

  (bool, default: False ) –

  Echo stdout/stderr of each run to the parent process

Methods:

• which –

  Return the absolute path to the exe

Attributes:

• subcmd (tuple[str, ...] | None) –

  Sub-command args always prepended to the exe's args

• cmd (str) –

  Name of (or path to) the executable

• abspath (str | None) –

  Resolved absolute path to the executable, if known/cached

• env (dict[str, str] | None) –

  Environment variables to run the executable with

• cwd (FsPath | None) –

  Working directory to run the executable in

• shell (bool) –

  Run the executable through the shell

• verbose (bool) –

  Echo stdout/stderr of each run to the parent process

• timeout (float | int | None) –

  Timeout in seconds for each run; None for no timeout

• ok_code (int | set[int]) –

  Return code(s) considered ok

• check (bool) –

  Raise DoneError if the return code is not ok

subcmd class-attribute instance-attribute

subcmd: tuple[str, ...] | None = None

Sub-command args always prepended to the exe's args

cmd instance-attribute

cmd: str = cmd

Name of (or path to) the executable

abspath class-attribute instance-attribute

abspath: str | None = abspath

Resolved absolute path to the executable, if known/cached

env class-attribute instance-attribute

env: dict[str, str] | None = env

Environment variables to run the executable with

cwd class-attribute instance-attribute

cwd: FsPath | None = cwd

Working directory to run the executable in

shell class-attribute instance-attribute

shell: bool = shell

Run the executable through the shell

verbose class-attribute instance-attribute

verbose: bool = verbose

Echo stdout/stderr of each run to the parent process

timeout class-attribute instance-attribute

timeout: float | int | None = timeout

Timeout in seconds for each run; None for no timeout

ok_code class-attribute instance-attribute

ok_code: int | set[int] = (
    {ok_code} if isinstance(ok_code, int) else set(ok_code)
)

Return code(s) considered ok

check class-attribute instance-attribute

check: bool = check

Raise DoneError if the return code is not ok

which

which() -> str

Return the absolute path to the exe

Returns:

• str –

  Absolute path to the executable

Raises:

• FileNotFoundError –

  If the executable is not found on the PATH

Exe

Exe(
    cmd: str,
    *,
    subcmd: tuple[str, ...] | list[str] | str | None = None,
    abspath: str | None = None,
    check: bool = False,
    cwd: FsPath | None = None,
    env: dict[str, str] | None = None,
    ok_code: int
    | list[int]
    | tuple[int, ...]
    | set[int] = 0,
    shell: bool = False,
    timeout: float | int | None = None,
    verbose: bool = False,
)

Bases: ExeABC

Callable wrapper around an executable

Examples:

>>> from shellfish.exe import Exe
>>> git = Exe("git", subcmd="status", verbose=False)
>>> git.cmd
'git'
>>> git.subcmd
('status',)
>>> git.ok_code
{0}

Calling the instance runs the executable and returns a Done object:

done = git("--porcelain")
done.check()
print(done.stdout)

Parameters:

• cmd

  (str) –

  Name of (or path to) the executable

• subcmd

  (tuple[str, ...] | list[str] | str | None, default: None ) –

  Sub-command args always prepended to the exe's args

• abspath

  (str | None, default: None ) –

  Absolute path to the executable; skips the which lookup

• check

  (bool, default: False ) –

  Raise DoneError if the return code is not ok

• cwd

  (FsPath | None, default: None ) –

  Working directory to run the executable in

• env

  (dict[str, str] | None, default: None ) –

  Environment variables to run the executable with

• ok_code

  (int | list[int] | tuple[int, ...] | set[int], default: 0 ) –

  Return code (or collection of return codes) considered ok

• shell

  (bool, default: False ) –

  Run the executable through the shell

• timeout

  (float | int | None, default: None ) –

  Timeout in seconds for each run; None for no timeout

• verbose

  (bool, default: False ) –

  Echo stdout/stderr of each run to the parent process

Methods:

• which –

  Return the absolute path to the exe

Attributes:

• cmd (str) –

  Name of (or path to) the executable

• subcmd (tuple[str, ...] | None) –

  Sub-command args always prepended to the exe's args

• abspath (str | None) –

  Resolved absolute path to the executable, if known/cached

• env (dict[str, str] | None) –

  Environment variables to run the executable with

• cwd (FsPath | None) –

  Working directory to run the executable in

• shell (bool) –

  Run the executable through the shell

• verbose (bool) –

  Echo stdout/stderr of each run to the parent process

• timeout (float | int | None) –

  Timeout in seconds for each run; None for no timeout

• ok_code (int | set[int]) –

  Return code(s) considered ok

• check (bool) –

  Raise DoneError if the return code is not ok

cmd instance-attribute

cmd: str = cmd

Name of (or path to) the executable

subcmd class-attribute instance-attribute

subcmd: tuple[str, ...] | None = None

Sub-command args always prepended to the exe's args

abspath class-attribute instance-attribute

abspath: str | None = abspath

Resolved absolute path to the executable, if known/cached

env class-attribute instance-attribute

env: dict[str, str] | None = env

Environment variables to run the executable with

cwd class-attribute instance-attribute

cwd: FsPath | None = cwd

Working directory to run the executable in

shell class-attribute instance-attribute

shell: bool = shell

Run the executable through the shell

verbose class-attribute instance-attribute

verbose: bool = verbose

Echo stdout/stderr of each run to the parent process

timeout class-attribute instance-attribute

timeout: float | int | None = timeout

Timeout in seconds for each run; None for no timeout

ok_code class-attribute instance-attribute

ok_code: int | set[int] = (
    {ok_code} if isinstance(ok_code, int) else set(ok_code)
)

Return code(s) considered ok

check class-attribute instance-attribute

check: bool = check

Raise DoneError if the return code is not ok

which

which() -> str

Return the absolute path to the exe

Returns:

• str –

  Absolute path to the executable

Raises:

• FileNotFoundError –

  If the executable is not found on the PATH

ExeAsync

ExeAsync(
    cmd: str,
    *,
    subcmd: tuple[str, ...] | list[str] | str | None = None,
    abspath: str | None = None,
    check: bool = False,
    cwd: FsPath | None = None,
    env: dict[str, str] | None = None,
    ok_code: int
    | list[int]
    | tuple[int, ...]
    | set[int] = 0,
    shell: bool = False,
    timeout: float | int | None = None,
    verbose: bool = False,
)

Bases: ExeABC

Awaitable wrapper around an executable

Same configuration as Exe, but calling an instance returns a coroutine:

git = ExeAsync("git")
done = await git("status", "--porcelain")

Parameters:

• cmd

  (str) –

  Name of (or path to) the executable

• subcmd

  (tuple[str, ...] | list[str] | str | None, default: None ) –

  Sub-command args always prepended to the exe's args

• abspath

  (str | None, default: None ) –

  Absolute path to the executable; skips the which lookup

• check

  (bool, default: False ) –

  Raise DoneError if the return code is not ok

• cwd

  (FsPath | None, default: None ) –

  Working directory to run the executable in

• env

  (dict[str, str] | None, default: None ) –

  Environment variables to run the executable with

• ok_code

  (int | list[int] | tuple[int, ...] | set[int], default: 0 ) –

  Return code (or collection of return codes) considered ok

• shell

  (bool, default: False ) –

  Run the executable through the shell

• timeout

  (float | int | None, default: None ) –

  Timeout in seconds for each run; None for no timeout

• verbose

  (bool, default: False ) –

  Echo stdout/stderr of each run to the parent process

Methods:

• which –

  Return the absolute path to the exe

Attributes:

• cmd (str) –

  Name of (or path to) the executable

• subcmd (tuple[str, ...] | None) –

  Sub-command args always prepended to the exe's args

• abspath (str | None) –

  Resolved absolute path to the executable, if known/cached

• env (dict[str, str] | None) –

  Environment variables to run the executable with

• cwd (FsPath | None) –

  Working directory to run the executable in

• shell (bool) –

  Run the executable through the shell

• verbose (bool) –

  Echo stdout/stderr of each run to the parent process

• timeout (float | int | None) –

  Timeout in seconds for each run; None for no timeout

• ok_code (int | set[int]) –

  Return code(s) considered ok

• check (bool) –

  Raise DoneError if the return code is not ok

cmd instance-attribute

cmd: str = cmd

Name of (or path to) the executable

subcmd class-attribute instance-attribute

subcmd: tuple[str, ...] | None = None

Sub-command args always prepended to the exe's args

abspath class-attribute instance-attribute

abspath: str | None = abspath

Resolved absolute path to the executable, if known/cached

env class-attribute instance-attribute

env: dict[str, str] | None = env

Environment variables to run the executable with

cwd class-attribute instance-attribute

cwd: FsPath | None = cwd

Working directory to run the executable in

shell class-attribute instance-attribute

shell: bool = shell

Run the executable through the shell

verbose class-attribute instance-attribute

verbose: bool = verbose

Echo stdout/stderr of each run to the parent process

timeout class-attribute instance-attribute

timeout: float | int | None = timeout

Timeout in seconds for each run; None for no timeout

ok_code class-attribute instance-attribute

ok_code: int | set[int] = (
    {ok_code} if isinstance(ok_code, int) else set(ok_code)
)

Return code(s) considered ok

check class-attribute instance-attribute

check: bool = check

Raise DoneError if the return code is not ok

which

which() -> str

Return the absolute path to the exe

Returns:

• str –

  Absolute path to the executable

Raises:

• FileNotFoundError –

  If the executable is not found on the PATH