wherobots-python-sdk 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

wherobots/__init__.py

@@ -3,6 +3,7 @@
 from wherobots.__version__ import __version__
 from wherobots.api.drive import Files, FilesDrive
 from wherobots.api.files import FilesAPI
+from wherobots.api.tasks import TaskRuns, Tasks
 from wherobots.client import WherobotsJob
 from wherobots.config import WherobotsConfig
 from wherobots.enums import (
@@ -14,6 +15,7 @@ from wherobots.enums import (
     JobStatus,
     Region,
     Runtime,
+    TaskRunState,
     is_terminal_status,
 )
 from wherobots.exceptions import (
@@ -34,6 +36,7 @@ from wherobots.models import (
     KubeAppEvent,
     LogItem,
     LogsResponse,
+    OffsetPage,
     OrganizationCustomer,
     PyPiDependency,
     RunAppMeta,
@@ -46,6 +49,14 @@ from wherobots.models import (
     RunPythonPayload,
     RunView,
     StorageIntegration,
+    Task,
+    TaskExample,
+    TaskRun,
+    TaskRunCost,
+    TaskRunLogEntry,
+    TaskRunLogs,
+    TaskRunSummary,
+    TaskSummary,
     TemporaryAwsCredentials,
     UtilizationStats,
 )
@@ -63,6 +74,8 @@ __all__ = [
     "WherobotsJob",
     "Job",
     "FilesAPI",
+    "Tasks",
+    "TaskRuns",
     "WherobotsConfig",
     # Enums
     "Runtime",
@@ -73,6 +86,7 @@ __all__ = [
     "AppType",
     "DependencyType",
     "DependencyFileType",
+    "TaskRunState",
     "is_terminal_status",
     # Exceptions
     "WherobotsJobError",
@@ -105,4 +119,13 @@ __all__ = [
     "TemporaryAwsCredentials",
     "UtilizationStats",
     "FileEntry",
+    "OffsetPage",
+    "TaskSummary",
+    "Task",
+    "TaskExample",
+    "TaskRunSummary",
+    "TaskRun",
+    "TaskRunLogs",
+    "TaskRunLogEntry",
+    "TaskRunCost",
 ]

wherobots/__version__.py

@@ -1,5 +1,5 @@
 """Version information."""
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 __author__ = "Wherobots"
 __email__ = "support@wherobots.com"

wherobots/api/__init__.py

@@ -4,5 +4,6 @@ from wherobots.api.base import BaseClient
 from wherobots.api.drive import Files, FilesDrive
 from wherobots.api.files import FilesAPI
 from wherobots.api.runs import RunsAPI
+from wherobots.api.tasks import TaskRuns, Tasks
 
-__all__ = ["BaseClient", "Files", "FilesAPI", "FilesDrive", "RunsAPI"]
+__all__ = ["BaseClient", "Files", "FilesAPI", "FilesDrive", "RunsAPI", "TaskRuns", "Tasks"]

wherobots/api/base.py

@@ -35,6 +35,21 @@ _RETRIABLE_STATUS_CODES = (429, 502, 503)
 _REDIRECT_STATUS_CODES = frozenset({301, 302, 303, 307, 308})
 
 
+def json_object(response: requests.Response) -> dict[str, object]:
+    """Parse a JSON object body, or raise ``WherobotsAPIError``."""
+    try:
+        data = response.json()
+    except ValueError as exc:
+        raise WherobotsAPIError(
+            "Wherobots API returned a non-JSON body", status_code=response.status_code
+        ) from exc
+    if not isinstance(data, dict):
+        raise WherobotsAPIError(
+            "Wherobots API returned an unexpected body", status_code=response.status_code
+        )
+    return data
+
+
 class BaseClient:
     """Thin HTTP wrapper around ``requests.Session``.
 

wherobots/api/drive.py

@@ -21,6 +21,7 @@ from urllib.parse import quote
 
 import requests
 
+from wherobots.api.base import json_object
 from wherobots.enums import Drive, Region
 from wherobots.exceptions import (
     WherobotsAPIError,
@@ -99,21 +100,6 @@ def _encode(segments: list[str]) -> str:
     return "/".join(quote(segment, safe="") for segment in segments)
 
 
-def _json_object(response: requests.Response) -> dict[str, object]:
-    """Parse a JSON object body, or raise ``WherobotsAPIError``."""
-    try:
-        data = response.json()
-    except ValueError as exc:
-        raise WherobotsAPIError(
-            "Files API returned a non-JSON body", status_code=response.status_code
-        ) from exc
-    if not isinstance(data, dict):
-        raise WherobotsAPIError(
-            "Files API returned an unexpected body", status_code=response.status_code
-        )
-    return data
-
-
 class FilesDrive:
     """One Files drive in one region: list, create folders, transfer, rename, delete.
 
@@ -175,7 +161,7 @@ class FilesDrive:
             if cursor is not None:
                 params["cursor"] = cursor
             response = self._call("GET", route, params=params, root_listing=not route_segments)
-            page = DirectoryPage.from_dict(_json_object(response))
+            page = DirectoryPage.from_dict(json_object(response))
             entries.extend(page.entries)
             # Any cursor seen before means the server is cycling; stop rather than loop forever.
             if page.next_cursor is None or page.next_cursor in seen:
@@ -227,7 +213,7 @@ class FilesDrive:
         segments = self._required(path, directory=False)
         response = self._call("POST", self._route("file-upload-url", segments))
         try:
-            target = FileUploadTarget.from_dict(_json_object(response))
+            target = FileUploadTarget.from_dict(json_object(response))
         except ValueError as exc:
             raise WherobotsAPIError(str(exc), status_code=response.status_code) from exc
         if not target.upload_url.startswith("https://"):

wherobots/api/tasks.py

@@ -0,0 +1,265 @@
+"""Tasks — typed wrappers around the ``/tasks`` and ``/task-runs`` endpoints.
+
+A task is a named unit of work, such as RasterFlow inference, that the caller's
+organization can run. Each run is a task run, addressable by its own id, so
+``Tasks`` and ``TaskRuns`` are siblings, as they are in the API.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC
+from typing import TYPE_CHECKING
+from urllib.parse import quote
+
+from wherobots.api.base import json_object
+from wherobots.enums import Region, TaskRunState
+from wherobots.exceptions import WherobotsAPIError
+from wherobots.models import (
+    OffsetPage,
+    Task,
+    TaskRun,
+    TaskRunCost,
+    TaskRunLogs,
+    TaskRunSummary,
+    TaskSummary,
+)
+from wherobots.utils.logger import get_logger
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from datetime import datetime
+
+    from wherobots.api.base import BaseClient
+
+logger = get_logger("api.tasks")
+
+
+def _region_name(region: Region | str) -> str:
+    return region.value if isinstance(region, Region) else region
+
+
+def _region_names(regions: Region | str | Sequence[Region | str]) -> list[str]:
+    # A lone string is one region, not a sequence of one-letter regions.
+    items = [regions] if isinstance(regions, (Region, str)) else regions
+    return [_region_name(r) for r in items]
+
+
+def _state_names(states: TaskRunState | str | Sequence[TaskRunState | str]) -> list[str]:
+    items = [states] if isinstance(states, (TaskRunState, str)) else states
+    return [s.value if isinstance(s, TaskRunState) else s for s in items]
+
+
+def _task_route(task_name: str) -> str:
+    return f"/tasks/{quote(task_name, safe='')}"
+
+
+class Tasks:
+    """The tasks the caller's organization can run.
+
+    Obtain it from ``Wherobots.tasks``; do not build it directly.
+
+    Args:
+        client: The shared API connection.
+        region: Region new runs use when ``run`` is given none; ``None`` lets the
+            API apply the organization's default region.
+    """
+
+    def __init__(self, client: BaseClient, region: str | None = None) -> None:
+        """Bind to a connection and default region; see the class docstring."""
+        self._client = client
+        self._region = region
+
+    def list(
+        self,
+        *,
+        regions: Region | str | Sequence[Region | str] | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> OffsetPage[TaskSummary]:
+        """List tasks, ordered by name (``GET /tasks``).
+
+        Args:
+            regions: Only tasks that can run in this region, or in any of these regions.
+            limit: Page size, 1 to 100.
+            offset: How many matching tasks to skip.
+
+        Returns:
+            One page of tasks; ``OffsetPage.next_offset`` fetches the next.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        params: dict[str, object] = {"limit": limit, "offset": offset}
+        if regions:
+            params["regions"] = _region_names(regions)
+        response = self._client.get("/tasks", params=params)
+        return OffsetPage.from_dict(json_object(response), TaskSummary.from_dict)
+
+    def get(self, task_name: str) -> Task:
+        """Fetch a task with its input and output schemas (``GET /tasks/{name}``).
+
+        Args:
+            task_name: The task's name.
+
+        Returns:
+            The task.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        response = self._client.get(_task_route(task_name))
+        return Task.from_dict(json_object(response))
+
+    def run(
+        self,
+        task_name: str,
+        inputs: Mapping[str, object] | None = None,
+        *,
+        region: Region | str | None = None,
+        name: str | None = None,
+    ) -> TaskRunSummary:
+        """Start a run of a task (``POST /tasks/{name}/runs``).
+
+        Args:
+            task_name: The task's name.
+            inputs: Inputs matching the task's ``input_schema``.
+            region: Region to run in; defaults to the configured region, then to
+                the organization's default region.
+            name: A name for the run, shown as ``TaskRun.name``.
+
+        Returns:
+            The new run; poll ``TaskRuns.get`` with its ``task_run_id``.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures, including
+                inputs the task's schema rejects.
+        """
+        body: dict[str, object] = {"inputs": dict(inputs or {})}
+        resolved_region = _region_name(region) if region else self._region
+        if resolved_region:
+            body["region"] = resolved_region
+        if name:
+            body["name"] = name
+        logger.info("Running task '%s' in %s", task_name, resolved_region or "org default")
+        response = self._client.post(f"{_task_route(task_name)}/runs", json_body=body)
+        return TaskRunSummary.from_dict(json_object(response))
+
+
+class TaskRuns:
+    """Runs of the organization's tasks.
+
+    Obtain it from ``Wherobots.task_runs``; do not build it directly.
+
+    Args:
+        client: The shared API connection.
+    """
+
+    def __init__(self, client: BaseClient) -> None:
+        """Bind to a connection; see the class docstring."""
+        self._client = client
+
+    def list(
+        self,
+        *,
+        task_name: str | None = None,
+        states: TaskRunState | str | Sequence[TaskRunState | str] | None = None,
+        created_after: datetime | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> OffsetPage[TaskRunSummary]:
+        """List task runs, newest first (``GET /task-runs``).
+
+        Args:
+            task_name: Only runs of this task; a trailing ``*`` matches a prefix.
+            states: Only runs in this state, or in any of these states.
+            created_after: Only runs submitted after this instant; a naive
+                ``datetime`` is read as local time.
+            limit: Page size, 1 to 100.
+            offset: How many matching runs to skip.
+
+        Returns:
+            One page of runs; ``OffsetPage.next_offset`` fetches the next.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        params: dict[str, object] = {"limit": limit, "offset": offset}
+        if task_name:
+            params["taskName"] = task_name
+        if states:
+            params["state"] = _state_names(states)
+        if created_after:
+            params["createdAfter"] = created_after.astimezone(UTC).isoformat()
+        response = self._client.get("/task-runs", params=params)
+        return OffsetPage.from_dict(json_object(response), TaskRunSummary.from_dict)
+
+    def get(self, task_run_id: str) -> TaskRun:
+        """Fetch a run with its inputs and results (``GET /task-runs/{id}``).
+
+        Args:
+            task_run_id: The run's id.
+
+        Returns:
+            The run.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        response = self._client.get(self._route(task_run_id))
+        return TaskRun.from_dict(json_object(response))
+
+    def logs(self, task_run_id: str, since: str | None = None) -> TaskRunLogs:
+        """Fetch a page of a run's logs (``GET /task-runs/{id}/logs``).
+
+        Args:
+            task_run_id: The run's id.
+            since: The previous page's ``next_since``; omit for the first page.
+
+        Returns:
+            Log lines logged after ``since``.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        params = {"since": since} if since else None
+        response = self._client.get(self._route(task_run_id, "logs"), params=params)
+        return TaskRunLogs.from_dict(json_object(response))
+
+    def cost(self, task_run_id: str) -> TaskRunCost:
+        """Fetch what a run cost (``GET /task-runs/{id}/cost``).
+
+        Args:
+            task_run_id: The run's id.
+
+        Returns:
+            The run's cost; ``is_settling`` is ``True`` while it may still change.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures, or a cost the
+                SDK cannot read (rather than reporting it as zero).
+        """
+        response = self._client.get(self._route(task_run_id, "cost"))
+        try:
+            return TaskRunCost.from_dict(json_object(response))
+        except (TypeError, ValueError) as exc:
+            raise WherobotsAPIError(str(exc), status_code=response.status_code) from exc
+
+    def cancel(self, task_run_id: str) -> None:
+        """Request that a run stop (``POST /task-runs/{id}/cancel``).
+
+        The run moves to ``CANCELLING`` and then ``CANCELLED`` once the stop is
+        confirmed.
+
+        Args:
+            task_run_id: The run's id.
+
+        Raises:
+            WherobotsAPIError: On HTTP failures.
+        """
+        self._client.post(self._route(task_run_id, "cancel"))
+        logger.info("Cancel requested for task run %s", task_run_id)
+
+    @staticmethod
+    def _route(task_run_id: str, action: str | None = None) -> str:
+        route = f"/task-runs/{quote(task_run_id, safe='')}"
+        return f"{route}/{action}" if action else route

wherobots/enums.py

@@ -148,3 +148,36 @@ class Drive(Enum):
     """
 
     MY_FILES = "my_files"
+
+
+class TaskRunState(Enum):
+    """Task run states (OpenAPI ``TaskRunState``)."""
+
+    PENDING = "PENDING"
+    SUBMITTED = "SUBMITTED"
+    RUNNING = "RUNNING"
+    SUCCEEDED = "SUCCEEDED"
+    FAILED = "FAILED"
+    TIMED_OUT = "TIMED_OUT"
+    CANCELLING = "CANCELLING"
+    CANCELLED = "CANCELLED"
+    UNKNOWN = "UNKNOWN"
+    SKIPPED = "SKIPPED"
+    MISSED = "MISSED"
+    REJECTED = "REJECTED"
+
+    @property
+    def is_active(self) -> bool:
+        """Return ``True`` while the run may still change state."""
+        return self in _ACTIVE_TASK_RUN_STATES
+
+
+# Mirrors the server's TaskRunState.active_states.
+_ACTIVE_TASK_RUN_STATES = frozenset(
+    {
+        TaskRunState.PENDING,
+        TaskRunState.SUBMITTED,
+        TaskRunState.RUNNING,
+        TaskRunState.CANCELLING,
+    }
+)

wherobots/models.py

@@ -7,8 +7,14 @@ for JSON round-tripping without requiring pydantic.
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from datetime import datetime, timedelta, timezone
-from typing import Any  # noqa: TID251
+from datetime import UTC, datetime, timedelta
+from decimal import Decimal, InvalidOperation
+from typing import (
+    TYPE_CHECKING,
+    Any,  # noqa: TID251
+    Generic,
+    TypeVar,
+)
 
 from wherobots.enums import (
     AppStatus,
@@ -16,8 +22,12 @@ from wherobots.enums import (
     DependencyFileType,
     DependencyType,
     JobStatus,
+    TaskRunState,
 )
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
 # ---------------------------------------------------------------------------
 # Dependency models
 # ---------------------------------------------------------------------------
@@ -1280,7 +1290,7 @@ class TemporaryAwsCredentials:
     def is_expired(self, leeway_seconds: int = 60) -> bool:
         """True if these creds are within *leeway_seconds* of expiry."""
         deadline = self.expiration - timedelta(seconds=leeway_seconds)
-        return datetime.now(timezone.utc) >= deadline
+        return datetime.now(UTC) >= deadline
 
     def wipe(self) -> None:
         """Evict secret material from this object.
@@ -1295,7 +1305,7 @@ class TemporaryAwsCredentials:
         object.__setattr__(self, "access_key_id", "")
         object.__setattr__(self, "secret_access_key", "")
         object.__setattr__(self, "session_token", "")
-        object.__setattr__(self, "expiration", datetime.now(timezone.utc) - timedelta(seconds=1))
+        object.__setattr__(self, "expiration", datetime.now(UTC) - timedelta(seconds=1))
 
     def __reduce__(self) -> Any:  # noqa: ANN401, D105
         raise TypeError(
@@ -1339,11 +1349,9 @@ class TemporaryAwsCredentials:
         if missing:
             raise ValueError(f"Credential response is missing required field(s): {missing}")
         raw_exp = data["expiration"]
-        # Accept trailing ``Z`` (some servers use it instead of +00:00).
-        normalized = raw_exp.replace("Z", "+00:00") if isinstance(raw_exp, str) else ""
-        expiration = datetime.fromisoformat(normalized)
+        expiration = datetime.fromisoformat(raw_exp if isinstance(raw_exp, str) else "")
         if expiration.tzinfo is None:
-            expiration = expiration.replace(tzinfo=timezone.utc)
+            expiration = expiration.replace(tzinfo=UTC)
         return cls(
             access_key_id=data["accessKeyId"],
             secret_access_key=data["secretAccessKey"],
@@ -1369,10 +1377,10 @@ def _parse_timestamp(value: object) -> datetime | None:
     if not isinstance(value, str) or not value:
         return None
     try:
-        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        parsed = datetime.fromisoformat(value)
     except ValueError:
         return None
-    return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=timezone.utc)
+    return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=UTC)
 
 
 @dataclass(frozen=True)
@@ -1481,3 +1489,332 @@ class FileUploadTarget:
         if destination is None or upload_url is None:
             raise ValueError("Upload URL response is missing 'destination' or 'uploadUrl'")
         return cls(destination=destination, upload_url=upload_url)
+
+
+# ---------------------------------------------------------------------------
+# Tasks
+# ---------------------------------------------------------------------------
+
+T = TypeVar("T")
+
+
+def _optional_int(data: dict[str, object], key: str) -> int | None:
+    """Return ``data[key]`` when it is an integer (not a bool), else ``None``."""
+    value = data.get(key)
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _object(value: object) -> dict[str, object] | None:
+    """Return ``value`` when it is a JSON object, else ``None``."""
+    return value if isinstance(value, dict) else None
+
+
+def _objects(value: object) -> list[dict[str, object]]:
+    """Return the JSON objects in ``value`` when it is a list, else ``[]``."""
+    return [item for item in value if isinstance(item, dict)] if isinstance(value, list) else []
+
+
+@dataclass(frozen=True)
+class OffsetPage(Generic[T]):
+    """One page of a limit/offset listing.
+
+    Attributes:
+        items: The items on this page.
+        total: How many items match in all, across every page.
+        limit: The page size the server applied.
+        offset: How many matching items precede this page.
+    """
+
+    items: list[T]
+    total: int
+    limit: int
+    offset: int
+
+    @property
+    def next_offset(self) -> int | None:
+        """The ``offset`` of the next page, or ``None`` on the last page."""
+        end = self.offset + len(self.items)
+        return end if self.items and end < self.total else None
+
+    @classmethod
+    def from_dict(
+        cls, data: dict[str, object], parse_item: Callable[[dict[str, object]], T]
+    ) -> OffsetPage[T]:
+        """Deserialize a ``LimitOffsetPage`` body, parsing each item with ``parse_item``."""
+        items = [parse_item(item) for item in _objects(data.get("items"))]
+        return cls(
+            items=items,
+            total=_optional_int(data, "total") or 0,
+            limit=_optional_int(data, "limit") or len(items),
+            offset=_optional_int(data, "offset") or 0,
+        )
+
+
+@dataclass(frozen=True)
+class TaskSummary:
+    """A task the caller's organization can run, as listings show it.
+
+    Attributes:
+        name: The task's unique name; pass it to ``Tasks.get`` and ``Tasks.run``.
+        display_name: Human-readable name.
+        description: What the task does, when it says.
+        regions: Regions the task can run in.
+    """
+
+    name: str
+    display_name: str
+    description: str | None = None
+    regions: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> TaskSummary:
+        """Deserialize a ``TaskSummary`` body."""
+        regions = data.get("regions")
+        return cls(
+            name=_optional_str(data, "name") or "",
+            display_name=_optional_str(data, "displayName") or "",
+            description=_optional_str(data, "description"),
+            regions=[r for r in regions if isinstance(r, str)] if isinstance(regions, list) else [],
+        )
+
+
+@dataclass(frozen=True)
+class TaskExample:
+    """A named set of example inputs for a task.
+
+    Attributes:
+        name: What the example shows.
+        inputs: Inputs to pass to ``Tasks.run``.
+    """
+
+    name: str
+    inputs: dict[str, object] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> TaskExample:
+        """Deserialize a ``TaskExample`` body."""
+        return cls(
+            name=_optional_str(data, "name") or "",
+            inputs=_object(data.get("inputs")) or {},
+        )
+
+
+@dataclass(frozen=True)
+class Task(TaskSummary):
+    """A task with the schemas of its inputs and outputs.
+
+    Attributes:
+        input_schema: JSON Schema the run inputs must satisfy, when the task has one.
+        output_schema: JSON Schema of a successful run's results, when the task has one.
+        examples: Example inputs.
+    """
+
+    input_schema: dict[str, object] | None = None
+    output_schema: dict[str, object] | None = None
+    examples: list[TaskExample] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> Task:
+        """Deserialize a ``Task`` body."""
+        summary = TaskSummary.from_dict(data)
+        return cls(
+            name=summary.name,
+            display_name=summary.display_name,
+            description=summary.description,
+            regions=summary.regions,
+            input_schema=_object(data.get("inputSchema")),
+            output_schema=_object(data.get("outputSchema")),
+            examples=[TaskExample.from_dict(e) for e in _objects(data.get("examples"))],
+        )
+
+
+def _task_run_state(value: object) -> TaskRunState | str:
+    if not isinstance(value, str):
+        return TaskRunState.UNKNOWN
+    try:
+        return TaskRunState(value)
+    except ValueError:
+        # Keep a state this SDK does not know yet instead of losing it.
+        return value
+
+
+@dataclass(frozen=True)
+class TaskRunSummary:
+    """One run of a task, as listings show it.
+
+    Attributes:
+        task_run_id: The run's id.
+        task_name: The task it ran.
+        state: A ``TaskRunState``, or the raw string for a state this SDK does not know.
+        region: The region it runs in.
+        submitted_at: When it was submitted.
+        started_at: When it started executing.
+        ended_at: When it ended.
+        duration_seconds: How long it executed (so far, while running).
+    """
+
+    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
+
+    @property
+    def is_active(self) -> bool:
+        """Return ``True`` while the run may still change state."""
+        return isinstance(self.state, TaskRunState) and self.state.is_active
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> TaskRunSummary:
+        """Deserialize a ``TaskRunSummary`` body."""
+        return cls(
+            task_run_id=_optional_str(data, "taskRunId") or "",
+            task_name=_optional_str(data, "taskName") or "",
+            state=_task_run_state(data.get("state")),
+            region=_optional_str(data, "region") or "",
+            submitted_at=_parse_timestamp(data.get("submittedAt")),
+            started_at=_parse_timestamp(data.get("startedAt")),
+            ended_at=_parse_timestamp(data.get("endedAt")),
+            duration_seconds=_optional_int(data, "durationSeconds"),
+        )
+
+
+@dataclass(frozen=True)
+class TaskRun(TaskRunSummary):
+    """One run of a task, with its inputs and outcome.
+
+    Attributes:
+        name: The name given to the run, if any.
+        inputs: The inputs it ran with.
+        results: The task's outputs by name (one output reads ``{"o0": ...}``) once
+            the run has succeeded.
+        cached: Whether it returned a stored result from an earlier identical run.
+        error_message: Why the run did not succeed.
+    """
+
+    name: str | None = None
+    inputs: dict[str, object] = field(default_factory=dict)
+    results: dict[str, object] | None = None
+    cached: bool = False
+    error_message: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> TaskRun:
+        """Deserialize a ``TaskRun`` body."""
+        summary = TaskRunSummary.from_dict(data)
+        return cls(
+            task_run_id=summary.task_run_id,
+            task_name=summary.task_name,
+            state=summary.state,
+            region=summary.region,
+            submitted_at=summary.submitted_at,
+            started_at=summary.started_at,
+            ended_at=summary.ended_at,
+            duration_seconds=summary.duration_seconds,
+            name=_optional_str(data, "name"),
+            inputs=_object(data.get("inputs")) or {},
+            results=_object(data.get("results")),
+            cached=data.get("cached") is True,
+            error_message=_optional_str(data, "errorMessage"),
+        )
+
+
+@dataclass(frozen=True)
+class TaskRunLogEntry:
+    """One log line of a task run.
+
+    Attributes:
+        timestamp: UTC instant to the nanosecond, as a string (``datetime`` would round it).
+        level: Log level.
+        message: The line.
+    """
+
+    timestamp: str
+    level: str
+    message: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> TaskRunLogEntry:
+        """Deserialize a ``TaskRunLogEntry`` body."""
+        return cls(
+            timestamp=_optional_str(data, "timestamp") or "",
+            level=_optional_str(data, "level") or "",
+            message=_optional_str(data, "message") or "",
+        )
+
+
+@dataclass(frozen=True)
+class TaskRunLogs:
+    """One page of a task run's logs.
+
+    Attributes:
+        task_run_id: The run's id.
+        entries: Log lines, oldest first.
+        next_since: Pass as ``since`` to fetch the lines after this page; ``None`` once
+            the run has finished and every line has been returned.
+    """
+
+    task_run_id: str
+    entries: list[TaskRunLogEntry] = field(default_factory=list)
+    next_since: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> TaskRunLogs:
+        """Deserialize a ``TaskRunLogsResponse`` body."""
+        return cls(
+            task_run_id=_optional_str(data, "taskRunId") or "",
+            entries=[TaskRunLogEntry.from_dict(e) for e in _objects(data.get("items"))],
+            next_since=_optional_str(data, "nextSince"),
+        )
+
+
+@dataclass(frozen=True)
+class TaskRunCost:
+    """What a task run cost.
+
+    Attributes:
+        task_run_id: The run's id.
+        total_cost_usd: Total cost in US dollars.
+        units: Billed units.
+        unit_type: What a unit measures.
+        is_settling: ``True`` while the cost may still change.
+    """
+
+    task_run_id: str
+    total_cost_usd: Decimal
+    units: int
+    unit_type: str
+    is_settling: bool
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> TaskRunCost:
+        """Deserialize a ``TaskRunCost`` body.
+
+        Strict, unlike the other models: a cost read as zero would claim the run was free.
+
+        Raises:
+            TypeError: If ``totalCostUsd`` is not a number or ``isSettling`` is not a bool.
+            ValueError: If ``totalCostUsd`` is not a finite number.
+        """
+        raw_total = data.get("totalCostUsd")
+        is_settling = data.get("isSettling")
+        if isinstance(raw_total, bool) or not isinstance(raw_total, (str, int, float)):
+            raise TypeError(f"Task run cost has no readable totalCostUsd: {raw_total!r}")
+        if not isinstance(is_settling, bool):
+            raise TypeError(f"Task run cost has no readable isSettling: {is_settling!r}")
+        try:
+            total = Decimal(str(raw_total))
+        except InvalidOperation as exc:
+            raise ValueError(f"Task run cost has no readable totalCostUsd: {raw_total!r}") from exc
+        if not total.is_finite():
+            raise ValueError(f"Task run cost has no readable totalCostUsd: {raw_total!r}")
+        return cls(
+            task_run_id=_optional_str(data, "taskRunId") or "",
+            total_cost_usd=total,
+            units=_optional_int(data, "units") or 0,
+            unit_type=_optional_str(data, "unitType") or "",
+            is_settling=is_settling,
+        )

wherobots/sdk.py

@@ -6,6 +6,7 @@ One object, one API connection, one config::
 
     with wherobots.Wherobots() as wb:
         wb.files.my_files.list_directory()
+        wb.tasks.list()
 """
 
 from __future__ import annotations
@@ -15,6 +16,7 @@ from typing import TYPE_CHECKING, final
 
 from wherobots.api.base import BaseClient
 from wherobots.api.drive import Files
+from wherobots.api.tasks import TaskRuns, Tasks
 from wherobots.config import WherobotsConfig
 from wherobots.enums import Region
 
@@ -56,6 +58,8 @@ class Wherobots:
         self._config = config
         self._client = BaseClient(config)
         self._files: Files | None = None
+        self._tasks: Tasks | None = None
+        self._task_runs: TaskRuns | None = None
 
     def __repr__(self) -> str:
         """Return a representation whose config masks the API key."""
@@ -73,6 +77,20 @@ class Wherobots:
             self._files = Files(self._client, self._config.region)
         return self._files
 
+    @property
+    def tasks(self) -> Tasks:
+        """The tasks your organization can run (``wb.tasks.list()``, ``wb.tasks.run(...)``)."""
+        if self._tasks is None:
+            self._tasks = Tasks(self._client, self._config.region)
+        return self._tasks
+
+    @property
+    def task_runs(self) -> TaskRuns:
+        """Runs of your organization's tasks (``wb.task_runs.get(...)``)."""
+        if self._task_runs is None:
+            self._task_runs = TaskRuns(self._client)
+        return self._task_runs
+
     def close(self) -> None:
         """Close the API connection."""
         self._client.close()

{wherobots_python_sdk-0.5.0.dist-info → wherobots_python_sdk-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.5.0
+Version: 0.6.0
 Summary: Python SDK for Wherobots (currently covers the Jobs REST API)
 Author-email: Wherobots <support@wherobots.com>
 License-Expression: Apache-2.0
@@ -13,22 +13,21 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: requests>=2.33.0
-Requires-Dist: boto3>=1.34.0
+Requires-Dist: requests>=2.34.2
+Requires-Dist: boto3>=1.43.108
 Dynamic: license-file
 
 # Wherobots Python SDK
 
 [![CI](https://github.com/wherobots/wherobots-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/wherobots/wherobots-python-sdk/actions/workflows/ci.yml)
-[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 [![Version](https://img.shields.io/pypi/v/wherobots-python-sdk?color=orange)](https://pypi.org/project/wherobots-python-sdk/)
 
@@ -46,6 +45,7 @@ Additional Wherobots surfaces will be added over time.
 - Typed dataclass models for all API responses (no pydantic dependency)
 - Environment-based configuration
 - Files: list, create folders, upload, download, rename and delete in your Wherobots file area
+- Tasks: list and run tasks such as RasterFlow inference, then follow their runs, logs and cost
 
 ## Installation
 
@@ -462,6 +462,47 @@ with wherobots.Wherobots() as wb:
 
 The three `Wherobots*Error` classes above subclass `WherobotsAPIError`.
 
+## Tasks
+
+A task is a named unit of work, such as RasterFlow inference, that your organization can run.
+`wb.tasks` lists and runs tasks; `wb.task_runs` follows the runs. Tasks need the Runs feature on
+your organization.
+
+```python
+import time
+
+import wherobots
+
+with wherobots.Wherobots() as wb:
+    for task in wb.tasks.list().items:
+        print(task.name, task.display_name, task.regions)
+
+    task = wb.tasks.get("my-task")
+    print(task.input_schema)  # JSON Schema the inputs must satisfy
+
+    started = wb.tasks.run("my-task", {"aoi": "s3://bucket/aoi.geojson"}, name="nightly")
+    run = wb.task_runs.get(started.task_run_id)
+    while run.is_active:
+        time.sleep(10)
+        run = wb.task_runs.get(run.task_run_id)
+
+    print(run.state, run.results, run.error_message)
+    print(wb.task_runs.logs(run.task_run_id).entries)
+    print(wb.task_runs.cost(run.task_run_id).total_cost_usd)
+```
+
+- `tasks.run` uses `region=` if passed, then the configured region, then your organization's
+  default region.
+- Listings return an `OffsetPage`; pass `page.next_offset` as `offset=` for the next one.
+- `TaskRunState.is_active` is `True` for `PENDING`, `SUBMITTED`, `RUNNING` and `CANCELLING`. A
+  state the SDK does not know yet is kept as its raw string and counts as not active, so a
+  polling loop stops on it.
+- A run's state can lag the run by up to 2 minutes.
+- `task_runs.logs` pages forward: pass the previous page's `next_since` as `since=`. It is `None`
+  once the run has finished and every line has been returned.
+- `task_runs.cost` can take up to 45 minutes after a run ends to settle; `is_settling` stays
+  `True` until then.
+
 ## Enums
 
 ### JobStatus
@@ -689,6 +730,14 @@ To set up a Storage Integration, follow the
 | GET    | `/runs/{id}/logs`      | Get run logs       |
 | GET    | `/runs/{id}/metrics`   | Get run metrics    |
 | GET    | `/runs`                | List runs          |
+| GET    | `/tasks`               | List tasks         |
+| GET    | `/tasks/{name}`        | Get a task         |
+| POST   | `/tasks/{name}/runs`   | Run a task         |
+| GET    | `/task-runs`           | List task runs     |
+| GET    | `/task-runs/{id}`      | Get a task run     |
+| GET    | `/task-runs/{id}/logs` | Get task run logs  |
+| GET    | `/task-runs/{id}/cost` | Get task run cost  |
+| POST   | `/task-runs/{id}/cancel` | Cancel a task run |
 
 Base URL: `https://api.cloud.wherobots.com`
 

wherobots_python_sdk-0.6.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+wherobots/__init__.py,sha256=MUFjzOBaVW2lzPw35F5SBlTChJBKl1n0-p16qUnIO9k,2759
+wherobots/__version__.py,sha256=WRvsZqweFyYGBAqr3rBDrYgY5bSG3iA5gCa_nhBsI1U,111
+wherobots/client.py,sha256=mFShTtxXfCg9GLVMykM7jC1SvuDCZ_sY9JnHIOlOwxQ,37797
+wherobots/config.py,sha256=d1QePrl7V0ooSlv_Ut0GJ5o0ShMBDH1k9yqgQ1cnxmE,7376
+wherobots/enums.py,sha256=T_x0QzDCmrZZTfYuEjkdjT_tbt0DDP5S-Kr5HnC8j2o,5218
+wherobots/exceptions.py,sha256=JnqMghCANt9Ci6IPmYssbysovqvxxfbB1QMV8xJ3uGY,2565
+wherobots/models.py,sha256=A1KxUivCoUUzFFhhMJCfu7qJHs_2ouYJR27gk39UzWs,62256
+wherobots/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wherobots/sdk.py,sha256=AcLC_ZFqTl24Vthcu_EfK7FFUJEyftGJJkusEp-zayI,3481
+wherobots/api/__init__.py,sha256=VT1nx6K777qV-PX-7hrBfCWPL1h6WYc4ljj_-qqhdko,360
+wherobots/api/base.py,sha256=xBMGH_x4Ryk7dQ_EORHviINKy1R0jnlJHrt2uvTSBxA,12001
+wherobots/api/drive.py,sha256=sWShECz7yjgWK_vlcB_0IWi6javG1nh-AGEKUk-jSzc,18799
+wherobots/api/files.py,sha256=_v89I8tJ_ANnxaTZd4AxtxrkZfZc0BDbL2jpmPBwvWw,23294
+wherobots/api/runs.py,sha256=y0yF_h74S4ScebgCxHjT07kBlj8aIHlfYN6iBaBktgs,8654
+wherobots/api/tasks.py,sha256=9knNtwU0Kb2NYkuabaaNkhiOyZjscec-JT8rkZZbIiY,9144
+wherobots/utils/__init__.py,sha256=cTM2QNJDauQWyGBTJPE5yH4ULc4Ucg_4KFzemjM3HaA,193
+wherobots/utils/client_header.py,sha256=-zczKIl8QfFBs1uTLbzp6cGLEzit1qGgdWbV9MLYEcM,8083
+wherobots/utils/logger.py,sha256=eclhD9Vf2LsSm4engRzT3jE2v0wdHJH01OfeI3ml4HM,1103
+wherobots/utils/validation.py,sha256=mjWGGhNji1crdn1AhLZoTIfknSQm38X0MmgI4ow14T8,907
+wherobots_python_sdk-0.6.0.dist-info/licenses/LICENSE,sha256=U1EH466XmvxbqaWOY0cax49w0R87_6w6yJLyV14v4bc,10767
+wherobots_python_sdk-0.6.0.dist-info/METADATA,sha256=yypXZowpLiuYE1VhuXGcBJyoTn0Rlfe5d1WTmbXL79Y,32834
+wherobots_python_sdk-0.6.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+wherobots_python_sdk-0.6.0.dist-info/top_level.txt,sha256=oL-n-9GIG0rmUeukuytUqdN6yfROIsVh8bNrgZsOdxw,10
+wherobots_python_sdk-0.6.0.dist-info/RECORD,,

{wherobots_python_sdk-0.5.0.dist-info → wherobots_python_sdk-0.6.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (84.0.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

wherobots_python_sdk-0.5.0.dist-info/RECORD

@@ -1,23 +0,0 @@
-wherobots/__init__.py,sha256=851lY2cWlkalilGZ2pvjCBOJIRdixrXRkHOuIkgRMTw,2330
-wherobots/__version__.py,sha256=Jb0N0VuH9FWKfWZpo_RdVUCfOylgV7rwlsHL5uwLslo,111
-wherobots/client.py,sha256=mFShTtxXfCg9GLVMykM7jC1SvuDCZ_sY9JnHIOlOwxQ,37797
-wherobots/config.py,sha256=d1QePrl7V0ooSlv_Ut0GJ5o0ShMBDH1k9yqgQ1cnxmE,7376
-wherobots/enums.py,sha256=0Wdw50bwWrZbslL6eb6pV8ebzWNPV6ouBjVX6PizbsY,4435
-wherobots/exceptions.py,sha256=JnqMghCANt9Ci6IPmYssbysovqvxxfbB1QMV8xJ3uGY,2565
-wherobots/models.py,sha256=iUeSxARQFlKGz8xtkweordFMsPwMavPGsLmSrEwIqbE,50926
-wherobots/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-wherobots/sdk.py,sha256=Cvp2a1I_Wvvk5Bp_qsawGfOqQ3DiMcS6JKhyrHtM6ds,2804
-wherobots/api/__init__.py,sha256=KbpcEzKbQ0Z35_hwHsm63Zmn7hfqSApDcRb8u5Y-Af0,291
-wherobots/api/base.py,sha256=EeMq2ESZ50oTf5Wpv50cqC6ljPlXXScg3SU8xfWMero,11471
-wherobots/api/drive.py,sha256=qdhOgL8d34noxE0SwEbqpI3Ql6u53pgLU0cePRwHEmM,19281
-wherobots/api/files.py,sha256=_v89I8tJ_ANnxaTZd4AxtxrkZfZc0BDbL2jpmPBwvWw,23294
-wherobots/api/runs.py,sha256=y0yF_h74S4ScebgCxHjT07kBlj8aIHlfYN6iBaBktgs,8654
-wherobots/utils/__init__.py,sha256=cTM2QNJDauQWyGBTJPE5yH4ULc4Ucg_4KFzemjM3HaA,193
-wherobots/utils/client_header.py,sha256=-zczKIl8QfFBs1uTLbzp6cGLEzit1qGgdWbV9MLYEcM,8083
-wherobots/utils/logger.py,sha256=eclhD9Vf2LsSm4engRzT3jE2v0wdHJH01OfeI3ml4HM,1103
-wherobots/utils/validation.py,sha256=mjWGGhNji1crdn1AhLZoTIfknSQm38X0MmgI4ow14T8,907
-wherobots_python_sdk-0.5.0.dist-info/licenses/LICENSE,sha256=U1EH466XmvxbqaWOY0cax49w0R87_6w6yJLyV14v4bc,10767
-wherobots_python_sdk-0.5.0.dist-info/METADATA,sha256=CWI2ckQPnC8dvVleWq2yVHClzodf7rImM1ELiay7KTk,30682
-wherobots_python_sdk-0.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-wherobots_python_sdk-0.5.0.dist-info/top_level.txt,sha256=oL-n-9GIG0rmUeukuytUqdN6yfROIsVh8bNrgZsOdxw,10
-wherobots_python_sdk-0.5.0.dist-info/RECORD,,