mafw.tools.shell_tools

Shell execution utilities.

This module provides unified functions for executing external commands via subprocess, with support for dry-runs, environment merging, and standardized output.

Module Attributes

CONSOLE

Shared console for standardized output.

Functions

run(command, *[, cwd, dry_run, env, quiet])

Execute a subprocess command and return a completed process object.

run_stdout(command, *[, dry_run, quiet])

Execute a command and return stripped standard output.
mafw.tools.shell_tools._to_command_line(command: str | list[str]) → str[source]

Convert a command into a printable shell-like string.

Parameters:

command (str | list[str]) – Command expressed as a string or tokenized list.

Returns:

Human-readable command line.

Return type:

str

mafw.tools.shell_tools.run(command: str | list[str], *, cwd: Path | str | None = None, dry_run: bool = False, env: dict[str, str] | None = None, quiet: bool = False, **kwargs: Any) → CompletedProcess[Any][source]

Execute a subprocess command and return a completed process object.

The command line is always printed with a standard prefix. In dry-run mode, execution is skipped and a successful synthetic CompletedProcess is returned.

Added in version 2.2: Add the quiet parameter to do not display the command being executed

Parameters:

  • command (str | list[str]) – Command to execute.

  • cwd (Path | str | None) – Working directory for command execution.

  • dry_run (bool) – If True, print the command without executing it.

  • env (dict[str, str] | None) – Optional environment variables to merge with the current environment.

  • quiet (bool) – Suppress the standard console banner when True.

  • kwargs (Any) – Additional keyword arguments forwarded to subprocess.run.

Returns:

Completed process produced by the command execution.

Return type:

subprocess.CompletedProcess[Any]

mafw.tools.shell_tools.run_stdout(command: str | list[str], *, dry_run: bool = False, quiet: bool = False, **kwargs: Any) → str[source]

Execute a command and return stripped standard output.

Added in version 2.2: Add the quiet parameter to do not display the command being executed

Parameters:

  • command (str | list[str]) – Command to execute.

  • dry_run (bool) – If True, do not execute the command.

  • quiet (bool) – Suppress the standard console banner when True.

  • kwargs (Any) – Additional keyword arguments forwarded to run.

Returns:

Standard output stripped of leading and trailing whitespace.

Return type:

str

mafw.tools.shell_tools.CONSOLE = <console width=80 None>

Shared console for standardized output.