# `oslo_concurrency.processutils`

System-level utilities and helper functions.

exception oslo_concurrency.processutils.InvalidArgumentError(message: object = None)

  Bases: `Exception`

class oslo_concurrency.processutils.LogErrors(*values)

  Bases: `IntEnum`

  Enumerations that affect if stdout and stderr are logged on error.

  Added in version 2.7.

  ALL = 1

    Log an error on each occurence of an error.

  DEFAULT = 0

    No logging on errors.

  FINAL = 2

    Log an error on the last attempt that errored only.

exception oslo_concurrency.processutils.NoRootWrapSpecified(message: object = None)

  Bases: `Exception`

exception oslo_concurrency.processutils.ProcessExecutionError(stdout: str | None = None, stderr: str | None = None, exit_code: str | int | None = None, cmd: list[str] | str | None = None, description: str | None = None)

  Bases: `Exception`

class oslo_concurrency.processutils.ProcessLimits(*, address_space: int | None = None, core_file_size: int | None = None, cpu_time: int | None = None, data_size: int | None = None, file_size: int | None = None, memory_locked: int | None = None, number_files: int | None = None, number_processes: int | None = None, resident_set_size: int | None = None, stack_size: int | None = None)

  Bases: `object`

  Resource limits on a process.

  Attributes:

  - address_space: Address space limit in bytes

  - core_file_size: Core file size limit in bytes

  - cpu_time: CPU time limit in seconds

  - data_size: Data size limit in bytes

  - file_size: File size limit in bytes

  - memory_locked: Locked memory limit in bytes

  - number_files: Maximum number of open files

  - number_processes: Maximum number of processes

  - resident_set_size: Maximum Resident Set Size (RSS) in bytes

  - stack_size: Stack size limit in bytes

  This object can be used for the prlimit parameter of `execute()`.

  prlimit_args() → list[str]

    Create a list of arguments for the prlimit command line.

exception oslo_concurrency.processutils.UnknownArgumentError(message: object = None)

  Bases: `Exception`

oslo_concurrency.processutils.execute(*cmd: str, cwd: str | None = None, process_input: str | bytes | None = None, env_variables: dict[str, str] | None = None, check_exit_code: bool | int | Iterable[int] | None = 0, delay_on_retry: bool = True, attempts: int = 1, run_as_root: bool = False, root_helper: str = '', shell: bool = False, loglevel: int = logging.DEBUG, log_errors: LogErrors = LogErrors.DEFAULT, binary: Literal[False] = False, on_execute: Callable[[...], Any] | None = None, on_completion: Callable[[...], Any] | None = None, preexec_fn: Callable[[...], Any] | None = None, prlimit: ProcessLimits | None = None, python_exec: str | None = None, timeout: int | None = None) → tuple[str, str]
oslo_concurrency.processutils.execute(*cmd: str, cwd: str | None = None, process_input: str | bytes | None = None, env_variables: dict[str, str] | None = None, check_exit_code: bool | int | Iterable[int] | None = 0, delay_on_retry: bool = True, attempts: int = 1, run_as_root: bool = False, root_helper: str = '', shell: bool = False, loglevel: int = logging.DEBUG, log_errors: LogErrors = LogErrors.DEFAULT, binary: Literal[True] = False, on_execute: Callable[[...], Any] | None = None, on_completion: Callable[[...], Any] | None = None, preexec_fn: Callable[[...], Any] | None = None, prlimit: ProcessLimits | None = None, python_exec: str | None = None, timeout: int | None = None) → tuple[bytes, bytes]
oslo_concurrency.processutils.execute(*cmd: str, cwd: str | None = None, process_input: str | bytes | None = None, env_variables: dict[str, str] | None = None, check_exit_code: bool | int | Iterable[int] | None = 0, delay_on_retry: bool = True, attempts: int = 1, run_as_root: bool = False, root_helper: str = '', shell: bool = False, loglevel: int = logging.DEBUG, log_errors: LogErrors = LogErrors.DEFAULT, binary: bool = False, on_execute: Callable[[...], Any] | None = None, on_completion: Callable[[...], Any] | None = None, preexec_fn: Callable[[...], Any] | None = None, prlimit: ProcessLimits | None = None, python_exec: str | None = None, timeout: int | None = None) → tuple[str, str] | tuple[bytes, bytes]

  Helper method to shell out and execute a command through subprocess.

  Allows optional retry.

  Parameters:

    - cmd – Passed to subprocess.Popen.

    - cwd – Set the current working directory

    - process_input – Send to opened process.

    - env_variables – Environment variables and their values that will be set for the process.

    - check_exit_code – Single bool, int, or list of allowed exit codes. Defaults to [0]. Raise `ProcessExecutionError` unless program exits with one of these code.

    - delay_on_retry – True | False. Defaults to True. If set to True, wait a short amount of time before retrying.

    - attempts – How many times to retry cmd.

    - run_as_root – True | False. Defaults to False. If set to True, the command is prefixed by the command specified in the root_helper kwarg.

    - root_helper – command to prefix to commands called with run_as_root=True

    - shell – whether or not there should be a shell used to execute this command. Defaults to false.

    - loglevel – log level for execute commands.

    - log_errors – Should stdout and stderr be logged on error? Possible values are `DEFAULT`, `FINAL`, or `ALL`. Note that the values `FINAL` and `ALL` are only relevant when multiple attempts of command execution are requested using the `attempts` parameter.

    - binary – On Python 3, return stdout and stderr as bytes if binary is True, as Unicode otherwise.

    - on_execute – This function will be called upon process creation with the object as a argument. The Purpose of this is to allow the caller of processutils.execute to track process creation asynchronously.

    - on_completion – This function will be called upon process completion with the object as a argument. The Purpose of this is to allow the caller of processutils.execute to track process completion asynchronously.

    - preexec_fn – This function will be called in the child process just before the child is executed. WARNING: On windows, we silently drop this preexec_fn as it is not supported by subprocess.Popen on windows (throws a ValueError)

    - prlimit – Set resource limits on the child process. See below for a detailed description.

    - python_exec – The python executable to use for enforcing prlimits. If this is not set or is None, it will default to use sys.executable.

    - timeout – Timeout (in seconds) to wait for the process termination. If timeout is reached, `subprocess.TimeoutExpired` is raised.

  Returns:

    (stdout, stderr) from process execution

  Raises:

    `UnknownArgumentError` on receiving unknown arguments

  Raises:

    `ProcessExecutionError`

  Raises:

    `OSError`

  Raises:

    `subprocess.TimeoutExpired`

  The prlimit parameter can be used to set resource limits on the child process. If this parameter is used, the child process will be spawned by a wrapper process which will set limits before spawning the command.

  Changed in version 3.17: process_input can now be either bytes or string on python3.

  Changed in version 3.4: Added prlimit optional parameter.

  Changed in version 1.5: Added cwd optional parameter.

  Changed in version 1.9: Added binary optional parameter. On Python 3, stdout and stderr are now returned as Unicode strings by default, or bytes if binary is true.

  Changed in version 2.1: Added on_execute and on_completion optional parameters.

  Changed in version 2.3: Added preexec_fn optional parameter.

oslo_concurrency.processutils.get_worker_count() → int

  Utility to get the default worker count.

  Returns:

    The number of CPUs if that can be determined, else a default worker count of 1 is returned.

oslo_concurrency.processutils.ssh_execute(ssh: paramiko.client.SSHClient, cmd: str, process_input: bytes | None = None, addl_env: Any = None, check_exit_code: bool = True, binary: Literal[True] = True, timeout: int | None = None, sanitize_stdout: bool = True) → tuple[bytes, bytes]
oslo_concurrency.processutils.ssh_execute(ssh: paramiko.client.SSHClient, cmd: str, process_input: bytes | None = None, addl_env: Any = None, check_exit_code: bool = True, binary: Literal[False] = False, timeout: int | None = None, sanitize_stdout: bool = True) → tuple[str, str]
oslo_concurrency.processutils.ssh_execute(ssh: paramiko.client.SSHClient, cmd: str, process_input: bytes | None = None, addl_env: Any = None, check_exit_code: bool = True, binary: bool = False, timeout: int | None = None, sanitize_stdout: bool = True) → tuple[str, str] | tuple[bytes, bytes]

  Run a command through SSH.

  Parameters:

    - ssh – An SSH Connection object.

    - cmd – The command string to run.

    - check_exit_code – If an exception should be raised for non-zero exit.

    - timeout – Max time in secs to wait for command execution.

    - sanitize_stdout – Defaults to True. If set to True, stdout is sanitized i.e. any sensitive information like password in command output will be masked.

  Returns:

    (stdout, stderr) from command execution through SSH.

  Changed in version 1.9: Added binary optional parameter.

oslo_concurrency.processutils.trycmd(*cmd: str, cwd: str | None = None, process_input: str | bytes | None = None, env_variables: dict[str, str] | None = None, check_exit_code: bool | int | Iterable[int] | None = 0, delay_on_retry: bool = True, attempts: int = 1, run_as_root: bool = False, root_helper: str = '', shell: bool = False, loglevel: int = 10, log_errors: LogErrors = LogErrors.DEFAULT, binary: bool = False, on_execute: Callable[[...], Any] | None = None, on_completion: Callable[[...], Any] | None = None, preexec_fn: Callable[[...], Any] | None = None, prlimit: ProcessLimits | None = None, python_exec: str | None = None, timeout: int | None = None, discard_warnings: bool = False) → tuple[str | bytes, str | bytes]

  A wrapper around execute() to more easily handle warnings and errors.

  Returns an (out, err) tuple of strings containing the output of the command’s stdout and stderr. If ‘err’ is not empty then the command can be considered to have failed.

  Parameters:

    discard_warnings – True | False. Defaults to False. If set to True, then for succeeding commands, stderr is cleared

  Returns:

    (out, err) from process execution

this page last updated: 2026-04-14 09:41:44

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug