API: Subprocess

class exec_helpers.Subprocess[source]
__init__(logger, log_mask_re=None, *, logger=logging.getLogger("exec_helpers.subprocess_runner"))[source]

ExecHelper global API.

Parameters:
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • logger (logging.Logger) – logger instance to use

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

typing.Optional[str]

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 (typing.Optional[str]) – chroot path or none for working without chroot.
Returns:context manager with selected chroot state inside
Return type:typing.ContextManager

Note

Enter and exit main context manager is produced as well.

New in version 4.1.0.

execute_async(command, stdin=None, open_stdout=True, open_stderr=True, verbose=False, log_mask_re=None, *, chroot_path=None, cwd=None, env=None, **kwargs)[source]

Execute command in async mode and return Popen with IO objects.

Parameters:
  • command (str) – Command for execution
  • stdin (typing.Union[str, bytes, bytearray, None]) – pass STDIN text to the process
  • open_stdout (bool) – open STDOUT stream for read
  • open_stderr (bool) – open STDERR stream for read
  • verbose (bool) – produce verbose log record on command call
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • chroot_path (typing.Optional[str]) – chroot path override
  • cwd (typing.Optional[typing.Union[str, bytes]]) – Sets the current directory before the child is executed.
  • env (typing.Optional[typing.Mapping[typing.Union[str, bytes], typing.Union[str, bytes]]]) – Defines the environment variables for the new process.
Return type:

SubprocessExecuteAsyncResult

Raises:

OSError – impossible to process STDIN

New in version 1.2.0.

Changed in version 2.1.0: Use typed NamedTuple as result

Changed in version 3.2.0: Expose cwd and env as optional keyword-only arguments

execute(command, verbose=False, timeout=1*60*60, *, log_mask_re=None, stdin=None, **kwargs)

Execute command and wait for return code.

Parameters:
  • command (str) – Command for execution
  • verbose (bool) – Produce log.info records for command call and output
  • timeout (typing.Union[int, float, None]) – Timeout for command execution.
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • stdin (typing.Union[bytes, str, bytearray, None]) – pass STDIN text to the 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, **kwargs)

Execute command and wait for return code.

Parameters:
  • command (str) – Command for execution
  • verbose (bool) – Produce log.info records for command call and output
  • timeout (typing.Union[int, float, None]) – Timeout for command execution.
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • stdin (typing.Union[bytes, str, bytearray, None]) – pass STDIN text to the 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, exception_class=CalledProcessError, **kwargs)

Execute command and check for return code.

Parameters:
  • command (str) – Command for execution
  • verbose (bool) – Produce log.info records for command call and output
  • timeout (typing.Union[int, float, None]) – Timeout for command execution.
  • error_info (typing.Optional[str]) – Text for error details, if fail happens
  • expected (typing.Iterable[typing.Union[int, ExitCodes]]) – expected return codes (0 by default)
  • raise_on_err (bool) – Raise exception on unexpected return code
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • stdin (typing.Union[bytes, str, bytearray, None]) – pass STDIN text to the process
  • exception_class (typing.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, exception_class=CalledProcessError, **kwargs)

Execute command expecting return code 0 and empty STDERR.

Parameters:
  • command (str) – Command for execution
  • verbose (bool) – Produce log.info records for command call and output
  • timeout (typing.Union[int, float, None]) – Timeout for command execution.
  • error_info (typing.Optional[str]) – Text for error details, if fail happens
  • raise_on_err (bool) – Raise exception on unexpected return code
  • expected (typing.Iterable[typing.Union[int, ExitCodes]]) – expected return codes (0 by default)
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • stdin (typing.Union[bytes, str, bytearray, None]) – pass STDIN text to the process
  • exception_class (typing.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[source]

Typed NamedTuple

interface

subprocess.Popen

stdin

typing.Optional[typing.IO]

stderr

typing.Optional[typing.IO]

stdout

typing.Optional[typing.IO]

started

datetime.datetime

New in version 3.4.1.