plox.tools.system

Utilities for interaction with local system binaries, executables, etc.

from plox.tools import system

Functions

block_until(condition, effect[, timeout_s, ...])

Block execution (up to timeout_s) until (condition) returns True.

sync_command(cmd[, shell, exit_on_error])

Executed a system command.

sys_exec(cwd, executable, exec_args, environment[, ...])

Execute a system command, threaded logging safe.

syscall_to_condition(call)

Convert syscall function (returns int) to boolean with exception catch.

Module Contents

plox.tools.system.block_until(condition, effect, timeout_s=360, condition_fail_wait_s=10)

Block execution (up to timeout_s) until (condition) returns True.

When condition returns true, executes effect.

Parameters:

  • condition (Callable[[], bool]) – Condition to wait for.

  • effect (Callable[[], int]) – Effect to trigger once condition is met.

  • timeout_s (int) – Max time in seconds to wait for condition. By default, is 6 minutes (360 seconds).

  • condition_fail_wait_s (int) – On condition fail, time to wait before attempting to check condition again. By default, is 10 seconds.

Returns:

effect’s return code.

Return type:

int

plox.tools.system.sync_command(cmd, shell=False, exit_on_error=False)

Executed a system command.

Parameters:

  • cmd (str) – Command to execute on host.

  • shell (bool) – Whether or not to execute the command as passed, or if should be tokenized and passed as list of values to subprocess. By default, passed command is split for safety.

  • exit_on_error (bool) – Whether or not hard exit should occur if process does not return successfully. By default, false.

Returns:

The completed process.

Return type:

subprocess.CompletedProcess[bytes]

plox.tools.system.sys_exec(cwd, executable, exec_args, environment, stdout_file_dest=None, quiet_stderr=False, exec_timeout_mins=24)

Execute a system command, threaded logging safe.

Parameters:

  • cwd (pathlib.Path) – Current directory that command is being invoked from.

  • executable (pathlib.Path) – Path to local binary that should be excecuted.

  • exec_args (list[str]) – List of args to pass to the executable.

  • environment (dict[Any, Any]) – Dictionary of k:v pairings to pass to the executable process’ environment.

  • stdout_file_dest (Optional[pathlib.Path]) – Optional file to log output text to. By default, does not log to file.

  • quiet_stderr (bool) – Whether or not stderr output should be silenced. By default, stderr is not silenced.

  • exec_timeout_mins (int) – Time in minutes before command is timed out. By default, is 24 minutes.

Returns:

Return code of executed process.

Return type:

int

plox.tools.system.syscall_to_condition(call)

Convert syscall function (returns int) to boolean with exception catch.

Parameters:

call (Callable[[], int]) – System call funciton that should be wrapped into a condition that is awaited until exit code.

Returns:

Wrapped system call.

Return type:

Callable[[], bool]