Job runs (WherobotsJob)

from wherobots import WherobotsJob

WherobotsJob

WherobotsJob(
    script: str,
    name: str,
    runtime: str | Runtime | None = None,
    region: str | Region | None = None,
    api_key: str | None = None,
    version: str | None = None,
    timeout_seconds: int = 3600,
    args: list[str] | None = None,
    spark_configs: dict[str, str] | None = None,
    dependencies: list[dict[str, Any]] | None = None,
    spark_driver_disk_gb: int | None = None,
    spark_executor_disk_gb: int | None = None,
    s3_bucket: str | None = None,
    s3_prefix: str | None = None,
    jar_main_class: str | None = None,
    auto_upload: bool = True,
    base_url: str | None = None,
    request_timeout_seconds: int | None = None,
    config: WherobotsConfig | None = None,
    client_chain: str | None = None,
)

Wherobots Job Run Manager. Manages the lifecycle of Wherobots job runs including submission, monitoring, log streaming, and cancellation. Use from_run_id to attach to an existing run for read-only log/metrics access without binding a script. Initialize a Wherobots Job.

Parameters

str

required

Path to Python script (.py) or JAR file (.jar). Can be local path or S3 URI (s3://bucket/key)

str

required

Job name (8-255 chars, alphanumeric, _, -, .)

str | Runtime | None

default:"None"

The compute runtime to use. Accepts a Runtime enum value or a raw string; strings are passed to the API as-is. Override the default runtime set for your organization — only set this if you need a specific runtime instead of the one your administrator has configured. When omitted, your organization’s default runtime is used.

str | Region | None

default:"None"

The compute region to run in. Accepts a Region enum value or a raw string (e.g. a BYOC region such as byoc-acme-us-east-1); strings are passed to the API as-is. Override the default region set for your organization — only set this if you intend to use a specific region instead of the one your administrator has configured. When omitted, your organization’s default region is used.

str | None

default:"None"

Wherobots API key (or set WHEROBOTS_API_KEY env var)

str | None

default:"None"

Wherobots version (“latest” or “preview”)

int

default:"3600"

Job timeout in seconds (default: 3600)

list[str] | None

default:"None"

Optional list of arguments to pass to script

dict[str, str] | None

default:"None"

Optional Spark configuration dict

list[dict[str, Any]] | None

default:"None"

Optional list of PyPI or file dependencies

int | None

default:"None"

Optional driver disk size

int | None

default:"None"

Optional executor disk size

str | None

default:"None"

Deprecated. Ignored; presigned uploads are used instead. Will be removed in a future release.

str | None

default:"None"

Deprecated. Ignored; presigned uploads are used instead. Will be removed in a future release.

str | None

default:"None"

Main class for JAR files (required for JARs)

bool

default:"True"

Automatically upload local scripts via presigned URL (default: True)

str | None

default:"None"

Override the API base URL

int | None

default:"None"

HTTP request timeout in seconds

WherobotsConfig | None

default:"None"

Optional WherobotsConfig to override defaults

str | None

default:"None"

Upstream X-Wherobots-Client chain for tools that embed this SDK. The SDK appends its own hop to the right of it so the originating client stays leftmost. Advisory only — it never affects authentication.

Raises

WherobotsValidationError: If script is None/empty, disk sizes are negative, or jar_main_class is missing for JARs.

add_file_dependency()

WherobotsJob.add_file_dependency(file_path: str) -> dict[str, Any]

Create a file dependency entry. Accepts either an s3:// URI (used as-is) or a local file path. Local paths are marked for lazy upload at submit() time — auto-upload always targets managed storage. Need to upload to a Storage Integration (or a custom subdir)? Use wherobots.FilesAPI directly to upload, then pass the resulting s3:// URI here. Keeps this method focused on dependency declaration; FilesAPI owns “where files go.”

Parameters

str

required

s3://... URI or local filesystem path ending in .jar, .whl, .zip, or .json.

Returns

dict[str, Any]

Dependency dictionary. May carry an internal _pendingUpload sentinel when a local path is given; it is stripped during request building.

Raises

WherobotsValidationError: If the extension is not one of .jar / .whl / .zip / .json.

add_pypi_dependency()

WherobotsJob.add_pypi_dependency(
    library_name: str,
    library_version: str,
) -> dict[str, str]

Create a PyPI dependency object.

Parameters

str

required

PyPI package name

str

required

Package version

Returns

dict[str, str]

Dependency dictionary

cancel()

cancel() -> bool

Cancel the job run.

Returns

bool

True if cancellation request was successful

close()

close() -> None

Close the underlying API session. Should be called when the job manager is no longer needed, or use as a context manager instead.

from_run_id()

WherobotsJob.from_run_id(
    run_id: str,
    *,
    api_key: str | None = None,
    config: WherobotsConfig | None = None,
    base_url: str | None = None,
    region: str | None = None,
    request_timeout_seconds: int | None = None,
    client_chain: str | None = None,
) -> WherobotsJob

Attach to an existing run for read-only log/metric access. Unlike the regular constructor this does not require a script or name — only a run_id. The returned instance is read-only: submit will raise. All other read methods (get_logs, iter_logs, poll_for_logs, get_metrics, get_cpu_utilization, get_mem_utilization, get_status, cancel, wait_for_completion) work normally.

Parameters

str

required

Run identifier from a prior submission, the CLI, or the Wherobots UI.

str | None

default:"None"

Wherobots API key (or set WHEROBOTS_API_KEY).

WherobotsConfig | None

default:"None"

Pre-built WherobotsConfig to use instead of the environment.

str | None

default:"None"

Override the API base URL.

str | None

default:"None"

AWS region override.

int | None

default:"None"

HTTP request timeout in seconds.

str | None

default:"None"

Upstream X-Wherobots-Client chain for tools that embed this SDK. The SDK appends its own hop to the right of it so the originating client stays leftmost.

Returns

WherobotsJob

A WherobotsJob bound to run_id with descriptive fields (name, runtime, status, …) hydrated from the API.

Raises

WherobotsValidationError: If run_id is empty.
WherobotsAPIError: If the initial refresh fails.

get_consumed_spatial_units()

get_consumed_spatial_units() -> float | None

Get the spatial units (SUs) consumed by the run.

Returns

float | None

SUs consumed (e.g. 11.27), or None if not reported.

get_cost()

get_cost() -> float | None

Get the run’s total cost in USD.

Returns

float | None

Cost in USD (e.g. 16.90), or None if the server did not surface a cost for this run (typical for runs that are still running or have not yet been billed).

get_cpu_utilization()

get_cpu_utilization() -> UtilizationStats

Get aggregated CPU utilization for the run.

Returns

UtilizationStats

UtilizationStats with latest/max/avg/series. All fields are None/empty when the CPU metric is absent from the server response.

get_logs()

get_logs(cursor: int | str = 0, size: int = 100) -> LogsResponse

Get job logs.

Parameters

int | str

default:"0"

Position to start reading logs. Accepts integer byte offsets (legacy) or string cursors returned in LogsResponse.next_page. Defaults to 0.

int

default:"100"

Maximum number of log entries to retrieve (default: 100)

Returns

LogsResponse

LogsResponse with items and pagination info

get_mem_utilization()

get_mem_utilization() -> UtilizationStats

Get aggregated memory utilization for the run.

Returns

UtilizationStats

UtilizationStats with latest/max/avg/series. All fields are None/empty when the memory metric is absent from the server response.

get_metrics()

get_metrics() -> RunMetricsResponse

Get job metrics for the run.

Returns

RunMetricsResponse

RunMetricsResponse with series and instant metrics

get_status()

get_status() -> RunView

Get current job status and details.

Returns

RunView

RunView with full job details

iter_logs()

iter_logs(
    cursor: int | str = 0,
    size: int = 100,
    max_pages: int = 10000,
) -> Iterator[dict[str, Any]]

Iterate over log entries until pagination ends.

Parameters

int | str

default:"0"

Initial pagination cursor.

int

default:"100"

Page size passed to get_logs.

int

default:"10000"

Hard ceiling on pages fetched, to guard against a buggy server that always returns a distinct next_page cursor. Defaults to 10_000.

Raises

WherobotsJobError: If the page ceiling is hit.

list_runs()

WherobotsJob.list_runs(
    api_key: str | None = None,
    region: str | None = None,
    name_pattern: str | None = None,
    created_after: str | None = None,
    status: list[str | JobStatus] | None = None,
    cursor: str | None = None,
    size: int = 50,
    base_url: str | None = None,
    request_timeout_seconds: int | None = None,
    config: WherobotsConfig | None = None,
) -> RunListPage

List job runs in the organization.

Parameters

str | None

default:"None"

Wherobots API key (or use WHEROBOTS_API_KEY env var)

str | None

default:"None"

Filter by region

str | None

default:"None"

Filter by name pattern (supports * wildcard)

str | None

default:"None"

Filter runs created after this ISO timestamp

list[str | JobStatus] | None

default:"None"

Filter by status (list of statuses)

str | None

default:"None"

Pagination cursor

int

default:"50"

Number of results per page (default: 50, max: 100)

str | None

default:"None"

Override API base URL

int | None

default:"None"

HTTP request timeout in seconds

WherobotsConfig | None

default:"None"

Optional WherobotsConfig to override defaults

Returns

RunListPage

RunListPage with items, total, and pagination cursor

poll_for_logs()

poll_for_logs(
    follow: bool = True,
    interval: float = 2.0,
    log_handler: Callable[[dict[str, Any]], None] | None = None,
    max_errors: int = 10,
    _deadline: float | None = None,
) -> None

Poll and print job logs.

Parameters

bool

default:"True"

If True, continue polling until job completes.

float

default:"2.0"

Polling interval in seconds (default: 2.0).

Callable[[dict[str, Any]], None] | None

default:"None"

Optional handler for each log item dict.

int

default:"10"

Max consecutive transient errors before giving up (default: 10). Non-transient errors (4xx except 429) are raised immediately.

float | None

default:"None"

Internal. Monotonic clock deadline for timeout enforcement. Callers should use wait_for_completion(max_wait_seconds=...) instead.

Raises

WherobotsJobError: If the job has not been submitted.
WherobotsTimeoutError: If _deadline is set and exceeded.
WherobotsAPIError: On non-transient HTTP errors.

refresh()

refresh() -> RunView

Re-fetch the run from the API and update local fields. Updates status, name, runtime, region, and version in place. Works in both attached and submitted modes.

Returns

RunView

The freshly fetched RunView.

Raises

WherobotsJobError: If run_id is not set.

submit()

submit() -> str

Submit the job run.

Returns

str

Run ID

wait_for_completion()

wait_for_completion(
    poll_interval: float = 5.0,
    stream_logs: bool = True,
    log_interval: float = 2.0,
    max_wait_seconds: float | None = None,
) -> JobStatus | str

Wait for job to complete, optionally streaming logs.

Parameters

float

default:"5.0"

Status check interval in seconds (default: 5.0)

bool

default:"True"

Stream logs while waiting (default: True)

float

default:"2.0"

Log polling interval in seconds (default: 2.0)

float | None

default:"None"

Maximum time to wait before raising WherobotsTimeoutError. None means wait indefinitely (default: None).

Returns

JobStatus | str

Final job status

Raises

WherobotsTimeoutError: If max_wait_seconds is exceeded.

​WherobotsJob

​Parameters

​Raises

​add_file_dependency()

​Parameters

​Returns

​Raises

​add_pypi_dependency()

​Parameters

​Returns

​cancel()

​Returns

​close()

​from_run_id()

​Parameters

​Returns

​Raises

​get_consumed_spatial_units()

​Returns

​get_cost()

​Returns

​get_cpu_utilization()

​Returns

​get_logs()

​Parameters

​Returns

​get_mem_utilization()

​Returns

​get_metrics()

​Returns

​get_status()

​Returns

​iter_logs()

​Parameters

​Raises

​list_runs()

​Parameters

​Returns

​poll_for_logs()

​Parameters

​Raises

​refresh()

​Returns

​Raises

​submit()

​Returns

​wait_for_completion()

​Parameters

​Returns

​Raises

WherobotsJob

Parameters

Raises

add_file_dependency()

Parameters

Returns

Raises

add_pypi_dependency()

Parameters

Returns

cancel()

Returns

close()

from_run_id()

Parameters

Returns

Raises

get_consumed_spatial_units()

Returns

get_cost()

Returns

get_cpu_utilization()

Returns

get_logs()

Parameters

Returns

get_mem_utilization()

Returns

get_metrics()

Returns

get_status()

Returns

iter_logs()

Parameters

Raises

list_runs()

Parameters

Returns

poll_for_logs()

Parameters

Raises

refresh()

Returns

Raises

submit()

Returns

wait_for_completion()

Parameters

Returns

Raises