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 executionverbose (
bool
) – Produce log.info records for command call and outputtimeout (
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 processopen_stdout (
bool
) – open STDOUT stream for readlog_stdout (
bool
) – log STDOUT during readopen_stderr (
bool
) – open STDERR stream for readlog_stderr (
bool
) – log STDERR during readcwd (
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:
- 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 executionverbose (
bool
) – Produce log.info records for command call and outputtimeout (
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 processopen_stdout (
bool
) – open STDOUT stream for readlog_stdout (
bool
) – log STDOUT during readopen_stderr (
bool
) – open STDERR stream for readlog_stderr (
bool
) – log STDERR during readcwd (
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:
- 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 executionverbose (
bool
) – Produce log.info records for command call and outputtimeout (
int | float | None
) – Timeout for command execution.error_info (
str | None
) – Text for error details, if fail happensexpected (Iterable[int | ExitCodes]) – expected return codes (0 by default)
raise_on_err (
bool
) – Raise exception on unexpected return codelog_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 processopen_stdout (
bool
) – open STDOUT stream for readlog_stdout (
bool
) – log STDOUT during readopen_stderr (
bool
) – open STDERR stream for readlog_stderr (
bool
) – log STDERR during readcwd (
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:
- Raises:
ExecHelperTimeoutError – Timeout exceeded
CalledProcessError – Unexpected exit code
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 executionverbose (
bool
) – Produce log.info records for command call and outputtimeout (
int | float | None
) – Timeout for command execution.error_info (
str | None
) – Text for error details, if fail happensraise_on_err (
bool
) – Raise exception on unexpected return codeexpected (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 processopen_stdout (
bool
) – open STDOUT stream for readlog_stdout (
bool
) – log STDOUT during readopen_stderr (
bool
) – open STDERR stream for readlog_stderr (
bool
) – log STDERR during readcwd (
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:
- Raises:
ExecHelperTimeoutError – Timeout exceeded
CalledProcessError – Unexpected exit code or stderr presents
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