process_capture()

def process_capture(argv) -> string

Run a command and return its trimmed stdout, raising on non-zero exit.

This is a convenience function for the common case where you want to capture command output and ensure the command succeeded. The output is automatically trimmed of leading and trailing whitespace.

Raises: Error: If argv is empty, or if the command: - Cannot be spawned - Exits with non-zero status - Has stderr output (stderr is captured separately)

Args

• argv: list: List of command and arguments: - argv[0]: Command to execute - argv[1:]: Command arguments

Returns

str: The process’s stdout, trimmed of whitespace

process_is_running()

def process_is_running(handle) -> bool

Check if a background process is still running.

Raises: Error: If the handle is invalid or the process registry is corrupted

Args

• handle: int: The process handle returned by process_spawn

Returns

bool: True if the process is still running, False if it has finished

process_kill()

def process_kill(handle, signal) -> bool

Send a signal to a background process to terminate it.

Raises: Error: If the handle is invalid, signal is unsupported, or killing fails

Args

• handle: int: The process handle returned by process_spawn
• signal: string: The signal to send (default: “SIGTERM”): - “SIGTERM”: Graceful termination (allows cleanup) - “SIGKILL”: Hard kill (immediate termination, no cleanup)

Returns

bool: True if the signal was sent successfully

process_options()

def process_options(command, args, env, cwd, stdin, stdout, stderr, timeout_ms, check) -> dict

Build a typed options dictionary for process execution.

This function assembles a complete options dictionary for passing to process_run(), process_spawn(), or other process execution functions. All options have sensible defaults and type hints.

Args

• command: string: The command to execute (required).
• args: Command line arguments (default: None).
• env: Environment variables to set (default: None).
• cwd: Working directory for the command (default: None).
• stdin: Text to write to the process’s stdin (default: None).
• stdout: Output handling option (default: None). Use process_stdout_inherit(), process_stdout_capture(), process_stdout_null(), or process_stdout_file(path).
• stderr: Error handling option (default: None). Use process_stderr_inherit(), process_stderr_capture(), process_stderr_null(), process_stderr_merge(), or process_stderr_file(path).
• timeout_ms: Maximum time in milliseconds (default: None).
• check: bool: Raise error on non-zero exit (default: False).

Returns

dict: A complete options dictionary for process execution

process_pipeline()

def process_pipeline(steps) -> dict

Execute a series of commands in a pipeline, piping output between them.

This function runs multiple commands in sequence, with the stdout of each command fed as stdin to the next. This is similar to shell pipeline syntax like cmd1 | cmd2 | cmd3. The final result contains the exit status of the last command and its output.

Raises: Error: If any command cannot be spawned, if a command times out, or if check=true and any command exits with non-zero status

Args

• steps: list: Use a list of return values from process_options().

Returns

dict: A result dictionary with the following keys: - status (int): Exit code of the final command - stdout (str): Output from the final command - stderr (str): Captured errors (implementation-dependent) - duration_ms (int): Total execution time in milliseconds

process_run()

def process_run(options) -> dict

Run a process with advanced control over I/O redirection and timeouts.

This function provides fine-grained control over process execution, including separate stdout/stderr handling, file redirection, timeout support, and optional exit code checking.

Raises: Error: If the command cannot be spawned, times out, or if check=true and the process exits with non-zero status

Args

• options: dict: Use the return value of process_options().

Returns

dict: A result dictionary with the following keys: - status (int): Exit code of the process - stdout (str): Captured standard output (if applicable) - stderr (str): Captured standard error (if applicable) - duration_ms (int): Time taken in milliseconds

process_spawn()

def process_spawn(options) -> int

Spawn a background process and return an opaque handle for later management.

This function starts a process in the background and returns a handle that can be used with process_is_running, process_kill, and process_wait to manage the process. By default, stdout and stderr are inherited (shown to the user).

Raises: Error: If the command cannot be spawned

Args

• options: dict: Use the return value of process_options().

Returns

int: An opaque process handle for use with other process functions

process_stderr_capture()

def process_stderr_capture() -> string

Stderr handling option: capture to string.

When used, the process’s stderr is captured and returned in the result dictionary. This is typically the default for run operations.

Returns

str: The string “capture” for use in process options

process_stderr_file()

def process_stderr_file(path) -> dict

Stderr handling option: redirect to file.

When used, the process’s stderr is written to the specified file. If the file does not exist, it will be created. If it already exists, it will be overwritten.

Args

• path: string:

Returns

dict: A dictionary for use in process options with the file redirect

process_stderr_inherit()

def process_stderr_inherit() -> string

Stderr handling option: inherit (show process errors).

When used, the process’s stderr is displayed directly to the user, not captured. This is typically the default for spawned processes.

Returns

str: The string “inherit” for use in process options

process_stderr_merge()

def process_stderr_merge() -> string

Stderr handling option: merge into stdout.

When used, the process’s stderr is merged into stdout. This is useful when you want to capture both output streams together.

Returns

str: The string “merge” for use in process options

process_stderr_null()

def process_stderr_null() -> string

Stderr handling option: discard (send to /dev/null).

When used, the process’s stderr is discarded and not displayed or captured.

Returns

str: The string “null” for use in process options

process_stdout_capture()

def process_stdout_capture() -> string

Stdout handling option: capture to string.

When used, the process’s stdout is captured and returned in the result dictionary. This is typically the default for run operations.

Returns

str: The string “capture” for use in process options

process_stdout_file()

def process_stdout_file(path) -> dict

Stdout handling option: redirect to file.

When used, the process’s stdout is written to the specified file. If the file does not exist, it will be created. If it already exists, it will be overwritten.

Args

• path: string:

Returns

dict: A dictionary for use in process options with the file redirect

process_stdout_inherit()

def process_stdout_inherit() -> string

Stdout handling option: inherit (show process output).

When used, the process’s stdout is displayed directly to the user, not captured. This is typically the default for spawned processes.

Returns

str: The string “inherit” for use in process options

process_stdout_null()

def process_stdout_null() -> string

Stdout handling option: discard (send to /dev/null).

When used, the process’s stdout is discarded and not displayed or captured.

Returns

str: The string “null” for use in process options

process_wait()

def process_wait(handle, timeout_ms) -> dict

Wait for a background process to complete and return its result.

This function blocks until the process finishes, either due to completion or timeout. Once a process is waited on, the handle is consumed and cannot be used again. The returned dictionary includes exit status, output (if captured), and execution duration.

Raises: Error: If the handle is invalid, process doesn’t finish within timeout, or waiting fails

Args

• handle: int: The process handle returned by process_spawn
• timeout_ms: Maximum time to wait in milliseconds (optional): - If None: Wait indefinitely - If specified: Raise error if process doesn’t finish in time

Returns

dict: A result dictionary with the following keys: - status (int): Exit code of the process (0 = success) - stdout (str): Captured standard output (empty if not captured) - stderr (str): Captured standard error (empty if not captured) - duration_ms (int): Time from spawn to completion in milliseconds