API: Subprocess

class exec_helpers.Subprocess[source]
__init__(logger, log_mask_re=None)[source]

ExecHelper global API.

Parameters:

log_mask_re (str | re.Pattern[str] | None) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’

Changed in version 1.2.0: log_mask_re regex rule for masking cmd

Changed in version 3.1.0: Not singleton anymore. Only lock is shared between all instances.

Changed in version 3.2.0: Logger can be enforced.

Changed in version 4.1.0: support chroot

Changed in version 4.3.0: Lock is not shared anymore: allow parallel call of different instances

log_mask_re

str | None

regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’

lock

threading.RLock

__enter__()

Open context manager

Changed in version 1.1.0: lock on enter

__exit__(self, exc_type, exc_val, exc_tb)

Close context manager

Changed in version 1.1.0: release lock on exit

chroot(path)

Context manager for changing chroot rules.

Parameters:

path (str | pathlib.Path | None) – chroot path or none for working without chroot.

Returns:

context manager with selected chroot state inside

Return type:

ContextManager

Note

Enter and exit main context manager is produced as well.

New in version 4.1.0.

execute(command, verbose=False, timeout=1 * 60 * 60, *, log_mask_re=None, stdin=None, open_stdout=True, log_stdout=True, open_stderr=True, log_stderr=True, cwd=None, env=None, env_patch=None, **kwargs)[source]

Execute command and wait for return code.

Parameters:
  • command (str | Iterable[str]) – Command for execution

  • verbose (bool) – Produce log.info records for command call and output

  • timeout (int | float | None) – Timeout for command execution.

  • log_mask_re (str | None) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’

  • stdin (bytes | str | bytearray | None) – pass STDIN text to the process

  • open_stdout (bool) – open STDOUT stream for read

  • log_stdout (bool) – log STDOUT during read

  • open_stderr (bool) – open STDERR stream for read

  • log_stderr (bool) – log STDERR during read

  • cwd (str | bytes | pathlib.Path | None) – Sets the current directory before the child is executed.

  • env (Mapping[str | bytes, str | bytes] | None) – Defines the environment variables for the new process.

  • env_patch (Mapping[str | bytes, str | bytes] | None) – Defines the environment variables to ADD for the new process.

Return type:

ExecResult

Raises:

ExecHelperTimeoutError – Timeout exceeded

Note

stdin channel is closed after the input processing

Changed in version 1.1.0: make method

Changed in version 1.2.0: open_stdout and open_stderr flags

Changed in version 1.2.0: default timeout 1 hour

Changed in version 1.2.0: stdin data

__call__(command, verbose=False, timeout=1 * 60 * 60, *, log_mask_re=None, stdin=None, open_stdout=True, log_stdout=True, open_stderr=True, log_stderr=True, cwd=None, env=None, env_patch=None, **kwargs)[source]

Execute command and wait for return code.

Parameters:
  • command (str | Iterable[str]) – Command for execution

  • verbose (bool) – Produce log.info records for command call and output

  • timeout (int | float | None) – Timeout for command execution.

  • log_mask_re (str | None) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’

  • stdin (bytes | str | bytearray | None) – pass STDIN text to the process

  • open_stdout (bool) – open STDOUT stream for read

  • log_stdout (bool) – log STDOUT during read

  • open_stderr (bool) – open STDERR stream for read

  • log_stderr (bool) – log STDERR during read

  • cwd (str | bytes | pathlib.Path | None) – Sets the current directory before the child is executed.

  • env (Mapping[str | bytes, str | bytes] | None) – Defines the environment variables for the new process.

  • env_patch (Mapping[str | bytes, str | bytes] | None) – Defines the environment variables to ADD for the new process.

Return type:

ExecResult

Raises:

ExecHelperTimeoutError – Timeout exceeded

Note

stdin channel is closed after the input processing

New in version 3.3.0.

check_call(command, verbose=False, timeout=1 * 60 * 60, error_info=None, expected=(0,), raise_on_err=True, *, log_mask_re=None, stdin=None, open_stdout=True, log_stdout=True, open_stderr=True, log_stderr=True, cwd=None, env=None, env_patch=None, exception_class=CalledProcessError, **kwargs)[source]

Execute command and check for return code.

Parameters:
  • command (str | Iterable[str]) – Command for execution

  • verbose (bool) – Produce log.info records for command call and output

  • timeout (int | float | None) – Timeout for command execution.

  • error_info (str | None) – Text for error details, if fail happens

  • expected (Iterable[int | ExitCodes]) – expected return codes (0 by default)

  • raise_on_err (bool) – Raise exception on unexpected return code

  • log_mask_re (str | None) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’

  • stdin (bytes | str | bytearray | None) – pass STDIN text to the process

  • open_stdout (bool) – open STDOUT stream for read

  • log_stdout (bool) – log STDOUT during read

  • open_stderr (bool) – open STDERR stream for read

  • log_stderr (bool) – log STDERR during read

  • cwd (str | bytes | pathlib.Path | None) – Sets the current directory before the child is executed.

  • env (Mapping[str | bytes, str | bytes] | None) – Defines the environment variables for the new process.

  • env_patch (Mapping[str | bytes, str | bytes] | None) – Defines the environment variables to ADD for the new process.

  • exception_class (Type[CalledProcessError]) – Exception class for errors. Subclass of CalledProcessError is mandatory.

Return type:

ExecResult

Raises:

Changed in version 1.1.0: make method

Changed in version 1.2.0: default timeout 1 hour

Changed in version 3.2.0: Exception class can be substituted

Changed in version 3.4.0: Expected is not optional, defaults os dependent

check_stderr(command, verbose=False, timeout=1 * 60 * 60, error_info=None, raise_on_err=True, *, expected=(0,), log_mask_re=None, stdin=None, open_stdout=True, log_stdout=True, open_stderr=True, log_stderr=True, cwd=None, env=None, env_patch=None, exception_class=CalledProcessError, **kwargs)[source]

Execute command expecting return code 0 and empty STDERR.

Parameters:
  • command (str | Iterable[str]) – Command for execution

  • verbose (bool) – Produce log.info records for command call and output

  • timeout (int | float | None) – Timeout for command execution.

  • error_info (str | None) – Text for error details, if fail happens

  • raise_on_err (bool) – Raise exception on unexpected return code

  • expected (Iterable[int | ExitCodes]) – expected return codes (0 by default)

  • log_mask_re (str | None) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’

  • stdin (bytes | str | bytearray | None) – pass STDIN text to the process

  • open_stdout (bool) – open STDOUT stream for read

  • log_stdout (bool) – log STDOUT during read

  • open_stderr (bool) – open STDERR stream for read

  • log_stderr (bool) – log STDERR during read

  • cwd (str | bytes | pathlib.Path | None) – Sets the current directory before the child is executed.

  • env (Mapping[str | bytes, str | bytes] | None) – Defines the environment variables for the new process.

  • env_patch (Mapping[str | bytes, str | bytes] | None) – Defines the environment variables to ADD for the new process.

  • exception_class (Type[CalledProcessError]) – Exception class for errors. Subclass of CalledProcessError is mandatory.

Return type:

ExecResult

Raises:

Changed in version 1.1.0: make method

Changed in version 1.2.0: default timeout 1 hour

Changed in version 3.2.0: Exception class can be substituted

Changed in version 3.4.0: Expected is not optional, defaults os dependent

class exec_helpers.SubprocessExecuteAsyncResult

Typed NamedTuple

interface

subprocess.Popen[bytes]

stdin

IO[bytes] | None

stderr

IO[bytes] | None

stdout

IO[bytes] | None

started

datetime.datetime

New in version 3.4.1.