Models - Wherobots

from wherobots import RunView, TaskRun

CreateRunPayload

CreateRunPayload(
    name: str,
    runtime: str | None = None,
    version: str = 'latest',
    timeout_seconds: int = 3600,
    run_python: RunPythonPayload | None = None,
    run_jar: RunJarPayload | None = None,
    environment: RunEnvironment | None = None,
)

Full payload for POST /runs.

Parameters

str

required

str | None

default:"None"

str

default:"'latest'"

int

default:"3600"

RunPythonPayload | None

default:"None"

RunJarPayload | None

default:"None"

RunEnvironment | None

default:"None"

DirectoryPage

DirectoryPage(entries: list[FileEntry] = list(), next_cursor: str | None = None)

One page of a Files drive listing.

Parameters

list[FileEntry]

default:"list()"

The files and folders on this page.

str | None

default:"None"

Cursor for the next page, or None on the last page.

FileDependency

FileDependency(file_path: str, file_type: DependencyFileType | None = None)

A file-based dependency (JAR, wheel, zip, etc.).

Parameters

str

required

DependencyFileType | None

default:"None"

FileEntry

FileEntry(
    name: str,
    path: str,
    is_dir: bool,
    size: int = 0,
    last_modified: datetime | None = None,
)

One file or folder in a Files drive listing.

Parameters

str

required

The entry’s own name, without a trailing /.

str

required

The entry’s path as the API reports it.

bool

required

True for a folder.

int

default:"0"

Size in bytes (0 for folders).

datetime | None

default:"None"

Last modification time, when the API reports one.

FileUploadTarget

FileUploadTarget(destination: str, upload_url: str)

Where a Files upload lands, and the presigned URL to send it to.

Parameters

str

required

The storage location the file will be written to.

str

required

Presigned PUT URL. It is a bearer credential, so repr hides it.

KubeAppEvent

KubeAppEvent(
    id: str = '',
    create_time: str = '',
    update_time: str = '',
    code: str | None = None,
    message: str | None = None,
    event_meta: RunEventMeta | None = None,
)

Kubernetes application event (OpenAPI KubeAppEvent).

Parameters

str

default:"''"

str

default:"''"

str

default:"''"

str | None

default:"None"

str | None

default:"None"

RunEventMeta | None

default:"None"

LogItem

LogItem(
    raw: str = '',
    timestamp: int | str | None = None,
    level: str | None = None,
    message: str | None = None,
    extra: dict[str, Any] = dict(),
)

A single log entry. The timestamp field is typed as Union[int, str, None] because the Wherobots API returns integer epoch values (e.g. 0) while other sources may use ISO-8601 strings.

Parameters

str

default:"''"

int | str | None

default:"None"

str | None

default:"None"

str | None

default:"None"

dict[str, Any]

default:"dict()"

LogsResponse

LogsResponse(
    items: list[LogItem] = list(),
    next_page: int | str | None = None,
    current_page: int | str | None = None,
    raw: dict[str, Any] = dict(),
)

Response from GET /runs/{id}/logs. The API returns current_page (int) and next_page (int) for cursor-based pagination. raw holds the original server response so callers can reach new fields without a SDK release.

Parameters

list[LogItem]

default:"list()"

int | str | None

default:"None"

int | str | None

default:"None"

dict[str, Any]

default:"dict()"

OffsetPage

OffsetPage(items: list[T], total: int, limit: int, offset: int)

One page of a limit/offset listing.

Parameters

list[T]

required

The items on this page.

int

required

How many items match in all, across every page.

int

required

The page size the server applied.

int

required

How many matching items precede this page.

next_offset

OffsetPage.next_offset: int | None

The offset of the next page, or None on the last page.

OrganizationCustomer

OrganizationCustomer(
    id: str = '',
    create_time: str = '',
    update_time: str = '',
    email: str | None = None,
    name: str | None = None,
    roles: list[str] = list(),
)

A user/customer in the organization (OpenAPI OrganizationCustomer). Returned on RunView.triggeredBy to identify the user who submitted a run.

Parameters

str

default:"''"

str

default:"''"

str

default:"''"

str | None

default:"None"

str | None

default:"None"

list[str]

default:"list()"

PyPiDependency

PyPiDependency(library_name: str, library_version: str)

A PyPI package dependency.

Parameters

str

required

str

required

RunAppMeta

RunAppMeta(
    spark_ui_url: str | None = None,
    spark_eventlogs_url: str | None = None,
    resolved_version: str | None = None,
)

Application metadata attached to a run (OpenAPI RunAppMeta).

Parameters

str | None

default:"None"

str | None

default:"None"

str | None

default:"None"

RunEnvironment

RunEnvironment(
    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,
)

Environment configuration for a job run.

Parameters

dict[str, str] | None

default:"None"

list[dict[str, Any]] | None

default:"None"

int | None

default:"None"

int | None

default:"None"

RunEventMeta

RunEventMeta(start_timestamp: int | None = None, end_timestamp: int | None = None)

Timestamp window attached to a KubeAppEvent (OpenAPI RunEventMeta).

Parameters

int | None

default:"None"

int | None

default:"None"

RunJarPayload

RunJarPayload(uri: str, main_class: str = '', args: list[str] = list())

JAR execution payload. Note: per the API spec, mainClass is optional on responses (the server may infer it). Kept as a string here with "" as the “unset” sentinel so existing callers who read the field unconditionally continue to work.

Parameters

str

required

str

default:"''"

list[str]

default:"list()"

RunKubeApp

RunKubeApp(
    id: str = '',
    create_time: str = '',
    update_time: str = '',
    instance_id: str = '',
    app_type: AppType | str | None = None,
    status: AppStatus | str | None = None,
    created_by_id: str | None = None,
    api_payload: dict[str, Any] | None = None,
    app_meta: RunAppMeta | None = None,
    events: list[KubeAppEvent] = list(),
    cpu_usage: int = 0,
    region_name: str = '',
    message: str | None = None,
)

Kubernetes application details for a run (OpenAPI RunKubeApp). Forward-compat: app_type and status round-trip unknown server values as raw strings rather than silently dropping them.

Parameters

str

default:"''"

str

default:"''"

str

default:"''"

str

default:"''"

AppType | str | None

default:"None"

AppStatus | str | None

default:"None"

str | None

default:"None"

dict[str, Any] | None

default:"None"

RunAppMeta | None

default:"None"

list[KubeAppEvent]

default:"list()"

int

default:"0"

str

default:"''"

str | None

default:"None"

RunListPage

RunListPage(
    items: list[RunView] = list(),
    total: int = 0,
    next_page: str | None = None,
    previous_page: str | None = None,
    current_page: str | None = None,
    current_page_backwards: str | None = None,
    raw: dict[str, Any] = dict(),
)

Paginated list of runs (GET /runs response). The Wherobots API returns string-based pagination cursors: next_page, previous_page, current_page, current_page_backwards.

Parameters

list[RunView]

default:"list()"

int

default:"0"

str | None

default:"None"

str | None

default:"None"

str | None

default:"None"

str | None

default:"None"

dict[str, Any]

default:"dict()"

cursor

RunListPage.cursor: str | None

Alias for next_page — kept for backward compatibility.

RunMetricsResponse

RunMetricsResponse(
    series_metrics: dict[str, Any] = dict(),
    instant_metrics: dict[str, Any] = dict(),
    extra: dict[str, Any] = dict(),
    raw: dict[str, Any] = dict(),
)

Response from GET /runs/{id}/metrics. Per the OpenAPI spec the metrics blobs use snake_case keys (series_metrics / instant_metrics) and are typed as plain object (the server’s internal metric shape is not stable enough to type against). The SDK exposes them as untyped dicts keyed by metric name; callers can inspect raw for any new fields the server adds.

Parameters

dict[str, Any]

default:"dict()"

dict[str, Any]

default:"dict()"

dict[str, Any]

default:"dict()"

dict[str, Any]

default:"dict()"

RunPythonPayload

RunPythonPayload(uri: str, args: list[str] = list())

Python script execution payload.

Parameters

str

required

list[str]

default:"list()"

RunView

RunView(
    id: str,
    name: str,
    status: JobStatus | str | None = None,
    runtime: str | None = None,
    region: str | None = None,
    version: str | None = None,
    timeout_seconds: int | None = None,
    create_time: str | None = None,
    update_time: str | None = None,
    start_time: str | None = None,
    complete_time: str | None = None,
    run_python: RunPythonPayload | None = None,
    run_jar: RunJarPayload | None = None,
    environment: RunEnvironment | None = None,
    app_meta: RunAppMeta | None = None,
    kube_app: RunKubeApp | None = None,
    triggered_by: OrganizationCustomer | None = None,
    extra: dict[str, Any] = dict(),
    raw: dict[str, Any] = dict(),
)

Complete view of a job run (GET /runs/{id} response). The Wherobots API nests payload fields (runtime, runPython, runJar, timeoutSeconds, environment) under a "payload" key. from_dict transparently flattens these so callers can access e.g. view.runtime directly. Timestamp fields from the API use createTime / startTime / completeTime; for convenience the parser also accepts the legacy createdAt / startedAt / completedAt aliases. Forward-compat:

status is typed as JobStatus | str | None so a status value the SDK doesn’t know about yet (e.g. a new terminal state added server-side) round-trips as the raw string instead of silently disappearing. Use is_terminal_status to check terminality without assuming the enum.
raw holds the full server response dict, so newly added fields are always reachable even when the typed surface hasn’t caught up.

Parameters

str

required

str

required

JobStatus | str | None

default:"None"

str | None

default:"None"

str | None

default:"None"

str | None

default:"None"

int | None

default:"None"

str | None

default:"None"

str | None

default:"None"

str | None

default:"None"

str | None

default:"None"

RunPythonPayload | None

default:"None"

RunJarPayload | None

default:"None"

RunEnvironment | None

default:"None"

RunAppMeta | None

default:"None"

RunKubeApp | None

default:"None"

OrganizationCustomer | None

default:"None"

dict[str, Any]

default:"dict()"

dict[str, Any]

default:"dict()"

completed_at

RunView.completed_at: str | None

Alias kept for backward compatibility.

created_at

RunView.created_at: str | None

Alias kept for backward compatibility.

started_at

RunView.started_at: str | None

Alias kept for backward compatibility.

StorageIntegration

StorageIntegration(
    id: str,
    name: str,
    path: str,
    region: str,
    type: str = 'INTEGRATION',
    create_time: str | None = None,
    update_time: str | None = None,
    role_arn: str | None = None,
    default_directory: str | None = None,
    raw: dict[str, Any] = dict(),
)

A storage source (managed or user-configured S3 integration). Represents one entry from GET /storage. The type field distinguishes the org’s MANAGED bucket from external INTEGRATION buckets the user has wired up.

Parameters

str

required

str

required

str

required

str

required

str

default:"'INTEGRATION'"

str | None

default:"None"

str | None

default:"None"

str | None

default:"None"

str | None

default:"None"

dict[str, Any]

default:"dict()"

is_managed

StorageIntegration.is_managed: bool

True if this is the org’s managed storage source.

Task

Task(
    name: str,
    display_name: str,
    description: str | None = None,
    regions: list[str] = list(),
    input_schema: dict[str, object] | None = None,
    output_schema: dict[str, object] | None = None,
    examples: list[TaskExample] = list(),
)

A task with the schemas of its inputs and outputs.

Parameters

str

required

str

required

str | None

default:"None"

list[str]

default:"list()"

dict[str, object] | None

default:"None"

JSON Schema the run inputs must satisfy, when the task has one.

dict[str, object] | None

default:"None"

JSON Schema of a successful run’s results, when the task has one.

list[TaskExample]

default:"list()"

Example inputs.

TaskExample

TaskExample(name: str, inputs: dict[str, object] = dict())

A named set of example inputs for a task.

Parameters

str

required

What the example shows.

dict[str, object]

default:"dict()"

Inputs to pass to Tasks.run.

TaskRun

TaskRun(
    task_run_id: str,
    task_name: str,
    state: TaskRunState | str,
    region: str,
    submitted_at: datetime | None = None,
    started_at: datetime | None = None,
    ended_at: datetime | None = None,
    duration_seconds: int | None = None,
    name: str | None = None,
    inputs: dict[str, object] = dict(),
    results: dict[str, object] | None = None,
    cached: bool = False,
    error_message: str | None = None,
)

One run of a task, with its inputs and outcome.

Parameters

str

required

str

required

TaskRunState | str

required

str

required

datetime | None

default:"None"

datetime | None

default:"None"

datetime | None

default:"None"

int | None

default:"None"

str | None

default:"None"

The name given to the run, if any.

dict[str, object]

default:"dict()"

The inputs it ran with.

dict[str, object] | None

default:"None"

The task’s outputs by name (one output reads {"o0": ...}) once the run has succeeded.

bool

default:"False"

Whether it returned a stored result from an earlier identical run.

str | None

default:"None"

Why the run did not succeed.

is_active

TaskRun.is_active: bool

Return True while the run may still change state.

TaskRunCost

TaskRunCost(
    task_run_id: str,
    total_cost_usd: Decimal,
    units: int,
    unit_type: str,
    is_settling: bool,
)

What a task run cost.

Parameters

str

required

The run’s id.

Decimal

required

Total cost in US dollars.

int

required

Billed units.

str

required

What a unit measures.

bool

required

True while the cost may still change.

TaskRunLogEntry

TaskRunLogEntry(timestamp: str, level: str, message: str)

One log line of a task run.

Parameters

str

required

UTC instant to the nanosecond, as a string (datetime would round it).

str

required

Log level.

str

required

The line.

TaskRunLogs

TaskRunLogs(
    task_run_id: str,
    entries: list[TaskRunLogEntry] = list(),
    next_since: str | None = None,
)

One page of a task run’s logs.

Parameters

str

required

The run’s id.

list[TaskRunLogEntry]

default:"list()"

Log lines, oldest first.

str | None

default:"None"

Pass as since to fetch the lines after this page; None once the run has finished and every line has been returned.

TaskRunSummary

TaskRunSummary(
    task_run_id: str,
    task_name: str,
    state: TaskRunState | str,
    region: str,
    submitted_at: datetime | None = None,
    started_at: datetime | None = None,
    ended_at: datetime | None = None,
    duration_seconds: int | None = None,
)

One run of a task, as listings show it.

Parameters

str

required

The run’s id.

str

required

The task it ran.

TaskRunState | str

required

A TaskRunState, or the raw string for a state this SDK does not know.

str

required

The region it runs in.

datetime | None

default:"None"

When it was submitted.

datetime | None

default:"None"

When it started executing.

datetime | None

default:"None"

When it ended.

int | None

default:"None"

How long it executed (so far, while running).

is_active

TaskRunSummary.is_active: bool

Return True while the run may still change state.

TaskSummary

TaskSummary(
    name: str,
    display_name: str,
    description: str | None = None,
    regions: list[str] = list(),
)

A task the caller’s organization can run, as listings show it.

Parameters

str

required

The task’s unique name; pass it to Tasks.get and Tasks.run.

str

required

Human-readable name.

str | None

default:"None"

What the task does, when it says.

list[str]

default:"list()"

Regions the task can run in.

TemporaryAwsCredentials

TemporaryAwsCredentials(
    access_key_id: str,
    secret_access_key: str,
    session_token: str,
    expiration: datetime,
    region: str,
)

Short-lived AWS STS credentials vended by POST /storage/credentials. Scope is determined server-side from the requested S3 path: the server picks the right backing bucket (managed / releases / matching Storage Integration). Security posture:

Masked in repr/str. repr(creds) (and therefore str(creds) and any f-string interpolation) only show the last 4 characters of the access key ID. Secret + session token never appear.
Frozen. Attribute injection is rejected; wipe() is the only mutator (via object.__setattr__ internally).
No pickle / copy. __reduce__, __copy__, and __deepcopy__ raise TypeError so creds cannot be silently serialized to disk, queues, or another process.
Local eviction via wipe(). Zeros the secret fields and poisons expiration so any subsequent is_expired check returns True. Python strings are immutable so the original bytes may linger on the heap until garbage collection, but this drops our last live reference. AWS-side revocation is not possible via the SDK; rely on the short TTL (typically 1 h).

Parameters

str

required

str

required

str

required

datetime

required

str

required

is_expired()

is_expired(leeway_seconds: int = 60) -> bool

True if these creds are within leeway_seconds of expiry.

Parameters

int

default:"60"

wipe()

wipe() -> None

Evict secret material from this object. Overwrites access_key_id / secret_access_key / session_token with empty strings and forces expiration into the past so any post-wipe reuse is detected by is_expired. Idempotent; safe to call multiple times.

UtilizationStats

UtilizationStats(
    latest: float | None = None,
    max: float | None = None,
    avg: float | None = None,
    series: list[tuple[float, float]] = list(),
)

Aggregated utilization for a single metric (e.g. CPU or memory). series is the raw time-series of (timestamp, value) points as returned by the server, normalized to floats. latest / max / avg are derived from that series for convenience. All fields are None / empty when the metric was not present in the response.

Parameters

float | None

default:"None"

float | None

default:"None"

float | None

default:"None"

list[tuple[float, float]]

default:"list()"

from_metric()

UtilizationStats.from_metric(
    instant: dict[str, Any],
    series: dict[str, Any],
    keys: tuple[str, ...],
) -> UtilizationStats

Build stats from the server’s untyped metric dicts.

Parameters

dict[str, Any]

required

RunMetricsResponse.instant_metrics.

dict[str, Any]

required

RunMetricsResponse.series_metrics.

tuple[str, ...]

required

Candidate metric names to look up, in priority order. The first key found in series (or instant as a fallback) is used. Multiple candidates are supported because metric names are server-defined and untyped.

Returns

UtilizationStats

A populated UtilizationStats, or an empty instance if none of the candidate keys are present.

Tie-break is “first key with ≥1 parseable point wins” — once we begin parsing a given key we do not fall through to subsequent candidates, even if some points within that key are malformed. In practice the primary (UPPERCASE) production key matches and the lowercase aliases only get tried when the primary key is entirely absent from the response.

​CreateRunPayload

​Parameters

​DirectoryPage

​Parameters

​FileDependency

​Parameters

​FileEntry

​Parameters

​FileUploadTarget

​Parameters

​KubeAppEvent

​Parameters

​LogItem

​Parameters

​LogsResponse

​Parameters

​OffsetPage

​Parameters

​next_offset

​OrganizationCustomer

​Parameters

​PyPiDependency

​Parameters

​RunAppMeta

​Parameters

​RunEnvironment

​Parameters

​RunEventMeta

​Parameters

​RunJarPayload

​Parameters

​RunKubeApp

​Parameters

​RunListPage

​Parameters

​cursor

​RunMetricsResponse

​Parameters

​RunPythonPayload

​Parameters

​RunView

​Parameters

​completed_at

​created_at

​started_at

​StorageIntegration

​Parameters

​is_managed

​Task

​Parameters

​TaskExample

​Parameters

​TaskRun

​Parameters

​is_active

​TaskRunCost

​Parameters

​TaskRunLogEntry

​Parameters

​TaskRunLogs

​Parameters

​TaskRunSummary

​Parameters

​is_active

​TaskSummary

​Parameters

​TemporaryAwsCredentials

​Parameters

​is_expired()

​Parameters

​wipe()

​UtilizationStats

​Parameters

​from_metric()

​Parameters

​Returns

CreateRunPayload

Parameters

DirectoryPage

Parameters

FileDependency

Parameters

FileEntry

Parameters

FileUploadTarget

Parameters

KubeAppEvent

Parameters

LogItem

Parameters

LogsResponse

Parameters

OffsetPage

Parameters

next_offset

OrganizationCustomer

Parameters

PyPiDependency

Parameters

RunAppMeta

Parameters

RunEnvironment

Parameters

RunEventMeta

Parameters

RunJarPayload

Parameters

RunKubeApp

Parameters

RunListPage

Parameters

cursor

RunMetricsResponse

Parameters

RunPythonPayload

Parameters

RunView

Parameters

completed_at

created_at

started_at

StorageIntegration

Parameters

is_managed

Task

Parameters

TaskExample

Parameters

TaskRun

Parameters

is_active

TaskRunCost

Parameters

TaskRunLogEntry

Parameters

TaskRunLogs

Parameters

TaskRunSummary

Parameters

is_active

TaskSummary

Parameters

TemporaryAwsCredentials

Parameters

is_expired()

Parameters

wipe()

UtilizationStats

Parameters

from_metric()

Parameters

Returns