Exec

This module provides helpers to run subprocesses and get their output.

It handles subprocess’ stderr and stdout in a way that doesn’t break loggers from yuio.io.

yuio.exec.exec(

*args: str | Path,

cwd: None | str | Path = None,

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

capture_io: bool = True,

input: None | str | bytes = None,

logger: Logger | LoggerAdapter[Any] | str | None = None,

level: int | None = None,

text: bool = True,

) → str | bytes | None

Run an executable and return its stdout.

Command’s stderr is interactively printed to the log.

Parameters:

• args – command arguments.

• cwd – set the current directory before the command is executed.

• env – define the environment variables for the command.

• input – string with command’s stdin. If text is set to False, this should be bytes, otherwise it should be a str.

• capture_io – if set to False, process’ stdout and stderr are not captured; logger and level arguments can’t be given in this case, and this function returns None instead of process’ output.

• logger – logger that will be used for logging command’s output. Default is to log to yuio.exec.

• level – logging level for stderr outputs. Default is logging.DEBUG.

• text – if set to False, stdout is returned as bytes.

Returns:

string (or bytes) with command’s stdout, or None if capture_io is False.

Raises:

If the command fails, a CalledProcessError is raised. If command can’t be started, raises OSError.

class yuio.exec.ExecError(returncode, cmd, output=None, stderr=None)

Raised when executed command returns a non-zero status.

returncode: int

Return code of the called command.

cmd: tuple[str | pathlib.Path, ...]

Initial args passed to the exec().

output: str | bytes | None

stdout: str | bytes | None

Captured stdout.

stderr: str | bytes | None

Captured stderr.