Skip to main content

Module clients.sandbox.process.client

Classes​

ProcessClient​

class ProcessClient(connection_config: h2o_engine_manager.clients.connection_config.ConnectionConfig, verify_ssl: bool = True, ssl_ca_cert: Optional[str] = None)

ProcessClient manages process operations within a SandboxEngine.

Args​
connection_config
AIEM connection configuration object.
verify_ssl
Set to False to disable SSL certificate verification.
ssl_ca_cert
Path to a CA cert bundle with certificates of trusted CAs.

Methods​

create_process ​

def create_process(self, parent: str, process: h2o_engine_manager.clients.sandbox.process.ps.Process, process_id: str = '', auto_run: bool = False) ‑> h2o_engine_manager.clients.sandbox.process.ps.Process

Create a new process in the sandbox engine.

Args​
parent : str
The parent SandboxEngine resource name. Format: "workspaces//sandboxEngines/"
process : Process
The Process to create.
process_id : str
Optional ID for the process. Must be 1-63 characters, lowercase alphanumeric or hyphen, start and end with alphanumeric. If not provided, a UUID is generated.
auto_run : bool
If True, starts execution immediately. If False, the process is created in STATE_PENDING and requires a separate start_process() call.
Returns​
Process
The created process.

get_process ​

def get_process(self, name: str) ‑> h2o_engine_manager.clients.sandbox.process.ps.Process

Get a process by its resource name.

Args​
name : str
Process resource name. Format: "workspaces//sandboxEngines//processes/*"
Returns​
Process
The process.

list_processes ​

def list_processes(self, parent: str, page_size: int = 0, page_token: str = '', filter: str = '') ‑> tuple[typing.List[h2o_engine_manager.clients.sandbox.process.ps.Process], str]

List processes in a sandbox engine.

Args​
parent : str
The parent SandboxEngine resource name. Format: "workspaces//sandboxEngines/"
page_size : int
Maximum number of processes to return. If unspecified (or set to 0), the server default will be used.
page_token : str
Token for pagination. Leave unset to receive the initial page.
filter : str
Filter expression.
Returns​
tuple[List[Process], str]
A tuple of (processes, next_page_token).

read_output ​

def read_output(self, name: str, output_stream: str = 'OUTPUT_STREAM_COMBINED') ‑> bytes

Read the complete output from a process.

Args​
name : str
Process resource name. Format: "workspaces//sandboxEngines//processes/*"
output_stream : str
Which output stream to read. Options: • "OUTPUT_STREAM_STDOUT": Read only stdout • "OUTPUT_STREAM_STDERR": Read only stderr • "OUTPUT_STREAM_COMBINED": Read combined stdout and stderr (default)
Returns​
bytes
The output data as bytes.

read_output_frames ​

def read_output_frames(self, name: str) ‑> List[Dict[str, object]]

Read the structured output of a process as ordered, per-stream-tagged frames.

Returns the same byte content as read_output(OUTPUT_STREAM_COMBINED) but preserves chunk boundaries and per-stream identity (stdout vs. stderr). Suitable for one-shot, post-completion log persistence — an alternative to subscribing to stream_output purely to capture output for durable storage.

Args​
name : str
Process resource name. Format: "workspaces//sandboxEngines//processes/*"
Returns​
List[Dict[str, object]]
A list of frames in arrival order. Each

frame is a dict with two keys: - "stream" (str): One of "OUTPUT_STREAM_STDOUT" or "OUTPUT_STREAM_STDERR". - "data" (bytes): The raw bytes captured for this chunk. Chunks may contain partial lines, multiple lines, or no newlines at all.

send_signal ​

def send_signal(self, name: str, signal: int) ‑> h2o_engine_manager.clients.sandbox.process.ps.Process

Send a signal to a running process.

Args​
name : str
Process resource name. Format: "workspaces//sandboxEngines//processes/*"
signal : int
The signal number to send (e.g., 9 for SIGKILL, 15 for SIGTERM).
Returns​
Process
The process after sending the signal.

start_process ​

def start_process(self, name: str) ‑> h2o_engine_manager.clients.sandbox.process.ps.Process

Start a process that is in STATE_PENDING.

Args​
name : str
Process resource name. Format: "workspaces//sandboxEngines//processes/*"
Returns​
Process
The started process.

stream_output ​

def stream_output(self, name: str, skip_replay: bool = False) ‑> Iterator[h2o_engine_manager.clients.sandbox.process.stream_output_chunk.StreamOutputChunk]

Stream the live output of a process as it becomes available.

Each yielded chunk carries the stream that produced it (stdout or stderr), so callers can separate or interleave the two. To consume only one stream, filter on chunk.stream; to reconstruct the combined output, concatenate chunk.data in arrival order.

Args​
name : str
Process resource name. Format: "workspaces//sandboxEngines//processes/*"
skip_replay : bool
If True, skips replaying output captured before the subscription began and streams only new output. If False (default), replays the captured output first.
Yields​
StreamOutputChunk
Output chunks in arrival order, each tagged with its source stream.

wait_process ​

def wait_process(self, name: str) ‑> h2o_engine_manager.clients.sandbox.process.ps.Process

Wait for a process to complete (blocking call).

This method blocks until the process reaches a terminal state (STATE_SUCCEEDED or STATE_FAILED).

Args​
name : str
Process resource name. Format: "workspaces//sandboxEngines//processes/*"
Returns​
Process
The completed process.

wait_process_by_polling ​

def wait_process_by_polling(self, name: str, timeout_seconds: Optional[int] = 300, poll_interval_seconds: int = 1) ‑> h2o_engine_manager.clients.sandbox.process.ps.Process

Wait for a process to reach a final state by polling (client-side blocking).

This method repeatedly calls get_process until the process reaches a final state (STATE_SUCCEEDED or STATE_FAILED) or the timeout is reached.

Args​
name : str
Process resource name. Format: "workspaces//sandboxEngines//processes/*"
timeout_seconds : Optional[int]
Maximum time to wait in seconds (default: 300). If None, waits indefinitely.
poll_interval_seconds : int
Time to wait between polling attempts in seconds (default: 1).
Returns​
Process
The process in its final state.
Raises​
TimeoutError
If the process does not reach a final state within the timeout.
Feedback