ReferenceProcess
Process

The process sub-client is accessed via client.process on a SandboxClient instance.

Commands must be iterables of strings; plain strings are rejected client-side. Background commands return a SandboxBgExec handle, documented below, whose methods are rendered with a bg. prefix.

SandboxBgExec

polyaxon._client.sandbox.SandboxBgExec(process, start)

SandboxBgExec is a handle for a background command started with process.exec_bg.

It wraps the started exec's id and exposes convenience methods to poll status, read logs, signal, and wait for completion.

  • Example:
bg = client.process.exec_bg(command=["sh", "-lc", "sleep 2; echo done"])
print(bg.id, bg.pid, bg.started_at, bg.tag)
for chunk in bg.iter_stdout(timeout=10, interval=0.2):
    print(chunk, end="")
status = bg.wait(timeout=10)
print(status.state, status.exit_code)
  • Properties:
    • id: str, the background exec id.
    • exec_id: str, alias of id.
    • pid: int, the process pid.
    • started_at: datetime, when the process started.
    • tag: str, the optional tag passed at start time.
    • start: V1ExecBgStart, the raw start response.

exec

process.exec(command, env=None, workdir=None, stdin=None, timeout_ms=None)

Runs a command to completion and returns the buffered result.

The command must be an iterable of strings, plain strings are rejected. Use exec_stream for incremental output and exec_bg for detached commands.

  • Example:
result = client.process.exec(
    command=["python", "-c", "import os; print(os.getenv('MSG'))"],
    env={"MSG": "hello"},
    workdir="/tmp",
    timeout_ms=10_000,
)
print(result.exit_code, result.stdout, result.stderr)

  • Args:

    • command: List[str], the command and its arguments.
    • env: Dict[str, str], optional, environment variables to set. Values must be strings. POLYAXON_* keys are rejected by the server.
    • workdir: str, optional, working directory for the command.
    • stdin: str or bytes, optional, data to pass to the command's stdin.
    • timeout_ms: int, optional, server-side execution timeout in milliseconds.

  • Returns: V1ExecResult, with exit_code, stdout, stderr, signal, duration_ms, timed_out, stdout_truncated, stderr_truncated.

  • Raises:

    • TypeError: If the command or env values have the wrong shape.

exec_stream

process.exec_stream(command, env=None, workdir=None, stdin=None, timeout_ms=None, timeout=None)

Runs a command and streams its output as server-sent events.

Returns an iterator that is also a context manager. Breaking out of the loop early inside a with block closes the HTTP response. Events are dicts with a type key: stdout, stderr, error, and execution_complete.

  • Example:
with client.process.exec_stream(
    command=["sh", "-lc", "echo one; echo two"],
) as events:
    for event in events:
        print(event)
        if event.get("type") == "execution_complete":
            break

  • Args:

    • command: List[str], the command and its arguments.
    • env: Dict[str, str], optional, environment variables to set.
    • workdir: str, optional, working directory for the command.
    • stdin: str or bytes, optional, data to pass to the command's stdin.
    • timeout_ms: int, optional, server-side execution timeout in milliseconds.
    • timeout: int, optional, client-side request timeout in seconds.

  • Returns: An SSE iterator and context manager yielding event dicts.

  • Raises:

    • PolyaxonClientException: If the request or the stream fails.

exec_bg

process.exec_bg(command, env=None, workdir=None, stdin=None, timeout_ms=None, tag=None)

Starts a detached background command and returns a handle.

The command keeps running after this call returns. Use the returned handle to poll status, read logs, signal, and wait.

  • Example:
bg = client.process.exec_bg(
    command=["sh", "-lc", "for i in 1 2 3; do echo tick-$i; sleep 1; done"],
    tag="my-job",
)
status = bg.wait(timeout=10)
print(status.state, status.exit_code)

  • Args:

    • command: List[str], the command and its arguments.
    • env: Dict[str, str], optional, environment variables to set.
    • workdir: str, optional, working directory for the command.
    • stdin: str or bytes, optional, data to pass to the command's stdin.
    • timeout_ms: int, optional, server-side execution timeout in milliseconds.
    • tag: str, optional, a label to filter execs in list.

  • Returns: SandboxBgExec, a handle for the started command with id, pid, started_at, and tag properties, and methods to poll status, read logs, signal, and wait, documented below.

list

process.list(tag=None)

Lists background execs.

  • Args:

    • tag: str, optional, only return execs started with this tag.

  • Returns: V1ExecBgList, with execs, a list of V1ExecBgStatus.

get

process.get(id)

Fetches the status of a background exec by id.

  • Args:

    • id: str, the background exec id.

  • Returns: V1ExecBgStatus

logs

process.logs(id, stream=None, offset=None, max_bytes=None)

Fetches one page of captured logs for a background exec.

  • Args:

    • id: str, the background exec id.
    • stream: str, optional, stdout or stderr.
    • offset: int, optional, byte offset to read from.
    • max_bytes: int, optional, max bytes to return in this page.

  • Returns: V1ExecBgLogs, with data, next_offset, eof, and state.

signal

process.signal(id, signal)

Sends a signal to a background exec.

  • Args:
    • id: str, the background exec id.
    • signal: str, the signal name, e.g. SIGTERM or SIGKILL.

delete

process.delete(id)

Deletes a background exec record and its captured logs.

  • Args:
    • id: str, the background exec id.

wait

bg.wait(timeout=None, interval=1.0)

Polls the background exec until it reaches a terminal state.

Terminal states are: exited, signaled, timed_out, failed_to_start, orphaned.

  • Args:

    • timeout: int, optional, max seconds to wait before raising. A timeout of 0 polls exactly once.
    • interval: float, optional, seconds between polls, default: 1.0.

  • Returns: V1ExecBgStatus, the terminal status.

  • Raises:

    • PolyaxonClientException: If the timeout is reached before the exec terminates.

iter_logs

bg.iter_logs(stream='stdout', offset=0, max_bytes=None, timeout=None, interval=1.0)

Iterates over the captured logs by polling with increasing offsets.

The iterator yields data chunks as they become available and stops when the exec reaches a terminal state and all data is consumed.

  • Example:
for chunk in bg.iter_logs(stream="stdout", timeout=10, interval=0.2):
    print(chunk, end="")

  • Args:

    • stream: str, optional, stdout or stderr, default: stdout.
    • offset: int, optional, byte offset to start from.
    • max_bytes: int, optional, max bytes per polling request.
    • timeout: int, optional, max seconds to wait before raising.
    • interval: float, optional, seconds between polls, default: 1.0.

  • Yields: str, log data chunks.

  • Raises:

    • PolyaxonClientException: If the timeout is reached or the server returns inconsistent offsets.

iter_stdout

bg.iter_stdout()

Iterates over the captured stdout logs. See iter_logs.

iter_stderr

bg.iter_stderr()

Iterates over the captured stderr logs. See iter_logs.

stdout

bg.stdout(offset=0, max_bytes=None)

Returns the captured stdout data as a string.

This is a convenience that buffers the requested range in memory. Use iter_stdout to follow logs incrementally.

  • Args:

    • offset: int, optional, byte offset to read from.
    • max_bytes: int, optional, max bytes to return.

  • Returns: str

stderr

bg.stderr(offset=0, max_bytes=None)

Returns the captured stderr data as a string.

This is a convenience that buffers the requested range in memory. Use iter_stderr to follow logs incrementally.

  • Args:

    • offset: int, optional, byte offset to read from.
    • max_bytes: int, optional, max bytes to return.

  • Returns: str

output

bg.output(offset=0, max_bytes=None)

Returns both captured stdout and stderr, buffered in memory.

  • Args:

    • offset: int, optional, byte offset to read from.
    • max_bytes: int, optional, max bytes to return per stream.

  • Returns: SandboxBgOutput, with stdout and stderr strings.

kill

bg.kill(signal='SIGTERM')

Sends a termination signal to the background exec.

Alias of signal with a default of SIGTERM.

  • Args:
    • signal: str, optional, the signal name, default: SIGTERM.
Client
Filesystem

On this page

SandboxBgExecexecexec_streamexec_bglistgetlogssignaldeletewaititer_logsiter_stdoutiter_stderrstdoutstderroutputkill

Actions

Give us feedbackEdit this page on GitHub