wherobots-python-sdk 0.1.0__py3-none-any.whl

wherobots/api/files.py

@@ -0,0 +1,386 @@
+"""Files API — upload scripts via presigned URLs.
+
+Wraps the ``/organization``, ``/files/upload-url``, and
+``/storage/{id}/file-upload-url/{path}`` endpoints to enable script
+upload using only a Wherobots API key (no AWS credentials required).
+"""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from wherobots.api.base import BaseClient
+from wherobots.config import WherobotsConfig
+from wherobots.exceptions import WherobotsAPIError, WherobotsValidationError
+from wherobots.models import StorageIntegration
+from wherobots.utils.logger import get_logger
+
+logger = get_logger("api.files")
+
+#: Maximum upload file size: 500 MB.
+MAX_UPLOAD_FILE_SIZE_BYTES: int = 500 * 1024 * 1024
+
+
+class FilesAPI:
+    """Upload files to Wherobots managed storage via presigned URLs.
+
+    Uses the ``/files/upload-url`` endpoint to obtain a presigned S3
+    PUT URL, then uploads the file content directly.  No AWS credentials
+    are needed — authentication is handled entirely through the
+    Wherobots API key.
+
+    Args:
+        client: A configured ``BaseClient`` instance.
+    """
+
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+        self._integrations_cache: list[StorageIntegration] | None = None
+
+    # ------------------------------------------------------------------ #
+    # Factory
+    # ------------------------------------------------------------------ #
+
+    @classmethod
+    def from_config(cls, config: WherobotsConfig, **kwargs: Any) -> FilesAPI:
+        """Build a ``FilesAPI`` from a ``WherobotsConfig``.
+
+        Args:
+            config: Validated configuration object.
+            **kwargs: Additional keyword arguments forwarded to
+                ``BaseClient.__init__`` (e.g. ``max_retries``).
+
+        Returns:
+            A new ``FilesAPI`` instance backed by the configured client.
+        """
+        client = BaseClient(config, **kwargs)
+        return cls(client)
+
+    # ------------------------------------------------------------------ #
+    # Endpoints
+    # ------------------------------------------------------------------ #
+
+    def get_organization(self) -> dict[str, Any]:
+        """Fetch the current organization details (``GET /organization``).
+
+        Returns:
+            Organization dict including ``fileStore.bucketName`` and
+            ``id`` (org identifier).
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        response = self._client.get("/organization")
+        try:
+            org: dict[str, Any] = response.json()
+        except (ValueError, requests.exceptions.JSONDecodeError) as exc:
+            raise WherobotsAPIError(
+                f"Invalid JSON in /organization response (status {response.status_code})",
+                status_code=response.status_code,
+            ) from exc
+        return org
+
+    def get_upload_url(self, key: str) -> str:
+        """Get a presigned S3 PUT URL for a given key.
+
+        Calls ``POST /files/upload-url?key=<key>`` and returns the
+        presigned URL from the response.
+
+        Args:
+            key: The full destination key for the managed S3 bucket,
+                formatted as ``"{bucket}/{org_id}/{path}"``
+                (e.g. ``"wbts-bucket/org123/data/shared/scripts/my_script.py"``).
+                The ``upload_script`` method constructs this automatically.
+
+        Returns:
+            A presigned S3 PUT URL string.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        response = self._client.post(
+            "/files/upload-url",
+            params={"key": key},
+        )
+        try:
+            data = response.json()
+        except (ValueError, requests.exceptions.JSONDecodeError) as exc:
+            raise WherobotsAPIError(
+                f"Invalid JSON in /files/upload-url response (status {response.status_code})",
+                status_code=response.status_code,
+            ) from exc
+
+        upload_url = data.get("uploadUrl")
+        if not isinstance(upload_url, str) or not upload_url:
+            raise WherobotsAPIError(
+                "No 'uploadUrl' in /files/upload-url response",
+                response=data,
+            )
+        return upload_url
+
+    def upload_script(
+        self,
+        content: str,
+        filename: str | None = None,
+    ) -> str:
+        """Upload a Python script to Wherobots managed storage.
+
+        This is a high-level convenience method that:
+
+        1. Calls ``GET /organization`` to discover the bucket name and
+           org ID.
+        2. Constructs the S3 key:
+           ``{org_id}/data/shared/scripts/{filename}``.
+        3. Obtains a presigned PUT URL via ``POST /files/upload-url``.
+        4. Uploads the script content via a raw HTTP PUT.
+        5. Returns the ``s3://`` URI for the uploaded script.
+
+        Args:
+            content: The Python script source code.
+            filename: Optional filename. If not provided, a UUID-based
+                name is generated (``sdk-upload-{uuid}.py``).
+
+        Returns:
+            The ``s3://`` URI of the uploaded script, suitable for
+            passing to ``CreateRunPayload``.
+
+        Raises:
+            WherobotsValidationError: If the filename is invalid.
+            WherobotsAPIError: On Wherobots API or presigned PUT failures.
+        """
+        if filename is None:
+            filename = f"sdk-upload-{uuid.uuid4().hex[:12]}.py"
+
+        # Reject path-traversal characters in user-supplied filenames.
+        if "/" in filename or "\\" in filename or ".." in filename:
+            raise WherobotsValidationError(
+                f"Invalid filename '{filename}': must not contain '/', '\\', or '..'"
+            )
+
+        # 1. Discover bucket and org ID
+        org = self.get_organization()
+        bucket = org.get("fileStore", {}).get("bucketName")
+        org_id = org.get("id")
+
+        if not bucket or not org_id:
+            raise WherobotsAPIError(
+                "Could not determine bucket or org ID from /organization response",
+                response=org,
+            )
+
+        # 2. Construct the S3 key and the upload-url key.
+        #    The upload-url endpoint expects: {bucket}/{org_id}/{path}
+        #    The resulting S3 URI is: s3://{bucket}/{org_id}/{path}
+        relative_path = f"{org_id}/data/shared/scripts/{filename}"
+        upload_key = f"{bucket}/{relative_path}"
+
+        logger.info(
+            "Uploading script '%s' to s3://%s/%s",
+            filename,
+            bucket,
+            relative_path,
+        )
+
+        # 3. Get presigned upload URL
+        presigned_url = self.get_upload_url(upload_key)
+
+        # 4. PUT the content directly to S3 (no Wherobots auth headers)
+        put_response = requests.put(
+            presigned_url,
+            data=content.encode("utf-8"),
+            headers={},
+            timeout=60,
+            allow_redirects=False,
+        )
+        if not put_response.ok:
+            raise WherobotsAPIError(
+                f"Presigned PUT failed (HTTP {put_response.status_code}): "
+                f"{put_response.text[:500]}",
+                status_code=put_response.status_code,
+            )
+
+        # 5. Return the S3 URI
+        s3_uri = f"s3://{bucket}/{relative_path}"
+        logger.info("Upload complete: %s", s3_uri)
+        return s3_uri
+
+    def upload_file(
+        self,
+        local_path: str,
+        filename: str | None = None,
+        max_file_size_bytes: int = MAX_UPLOAD_FILE_SIZE_BYTES,
+    ) -> str:
+        """Upload a local file to Wherobots managed storage via presigned URL.
+
+        Unlike ``upload_script()`` which accepts a string of source code,
+        this method reads a file from disk in binary mode, making it
+        suitable for Python scripts, JARs, and other binary artifacts.
+
+        Args:
+            local_path: Filesystem path to the file to upload.
+            filename: Optional destination filename.  Defaults to the
+                basename of *local_path*.
+            max_file_size_bytes: Maximum allowed file size in bytes.
+                Defaults to ``MAX_UPLOAD_FILE_SIZE_BYTES`` (500 MB).
+                Set to ``0`` to disable the check.
+
+        Returns:
+            The ``s3://`` URI of the uploaded file.
+
+        Raises:
+            WherobotsValidationError: If the file exceeds the size limit,
+                does not exist, or the filename is invalid.
+            WherobotsAPIError: On Wherobots API failures or presigned
+                PUT failures.
+        """
+        path = Path(local_path)
+        if not path.is_file():
+            raise WherobotsValidationError(f"File not found: {local_path}")
+
+        if filename is None:
+            filename = path.name
+
+        # Reject path-traversal characters in user-supplied filenames.
+        if "/" in filename or "\\" in filename or ".." in filename:
+            raise WherobotsValidationError(
+                f"Invalid filename '{filename}': must not contain '/', '\\', or '..'"
+            )
+
+        # Size validation
+        if max_file_size_bytes > 0:
+            try:
+                file_size = path.stat().st_size
+            except OSError as exc:
+                raise WherobotsValidationError(f"Cannot read file '{local_path}': {exc}") from exc
+            if file_size > max_file_size_bytes:
+                size_mb = file_size / (1024 * 1024)
+                limit_mb = max_file_size_bytes / (1024 * 1024)
+                raise WherobotsValidationError(
+                    f"File '{path.name}' is {size_mb:.1f} MB, exceeding the "
+                    f"{limit_mb:.0f} MB upload limit. Use an S3 URI instead."
+                )
+
+        # 1. Discover bucket and org ID
+        org = self.get_organization()
+        bucket = org.get("fileStore", {}).get("bucketName")
+        org_id = org.get("id")
+
+        if not bucket or not org_id:
+            raise WherobotsAPIError(
+                "Could not determine bucket or org ID from /organization response",
+                response=org,
+            )
+
+        # 2. Construct the S3 key
+        relative_path = f"{org_id}/data/shared/scripts/{filename}"
+        upload_key = f"{bucket}/{relative_path}"
+
+        logger.info(
+            "Uploading file '%s' (%s) to s3://%s/%s",
+            path.name,
+            filename,
+            bucket,
+            relative_path,
+        )
+
+        # 3. Get presigned upload URL
+        presigned_url = self.get_upload_url(upload_key)
+
+        # 4. Stream the file to S3 without loading it fully into memory.
+        with path.open("rb") as fh:
+            put_response = requests.put(
+                presigned_url,
+                data=fh,
+                headers={},
+                timeout=120,
+                allow_redirects=False,
+            )
+        if not put_response.ok:
+            raise WherobotsAPIError(
+                f"Presigned PUT failed (HTTP {put_response.status_code}): "
+                f"{put_response.text[:500]}",
+                status_code=put_response.status_code,
+            )
+
+        # 5. Return the S3 URI
+        s3_uri = f"s3://{bucket}/{relative_path}"
+        logger.info("Upload complete: %s", s3_uri)
+        return s3_uri
+
+    # ------------------------------------------------------------------ #
+    # Storage Integration Endpoints
+    # ------------------------------------------------------------------ #
+
+    def list_integrations(self) -> list[StorageIntegration]:
+        """List all configured storage integrations (``GET /storage``).
+
+        Returns:
+            A list of ``StorageIntegration`` objects.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        response = self._client.get("/storage")
+        try:
+            data = response.json()
+        except (ValueError, requests.exceptions.JSONDecodeError) as exc:
+            raise WherobotsAPIError(
+                f"Invalid JSON in /storage response (status {response.status_code})",
+                status_code=response.status_code,
+            ) from exc
+        return [StorageIntegration.from_dict(item) for item in data]
+
+    def resolve_integration(
+        self,
+        name_or_id: str,
+        *,
+        refresh: bool = False,
+    ) -> StorageIntegration:
+        """Find a storage integration by name (case-insensitive) or ID.
+
+        Results from ``list_integrations`` are cached on the instance to
+        avoid repeated ``GET /storage`` calls. Pass ``refresh=True`` to
+        force a fresh fetch if the set of integrations has changed.
+
+        Args:
+            name_or_id: The integration name or unique ID.
+            refresh: Force a fresh fetch of integrations.
+
+        Returns:
+            The matching ``StorageIntegration``.
+
+        Raises:
+            WherobotsValidationError: If no matching integration is found.
+            WherobotsAPIError: On HTTP failures.
+        """
+        if refresh or self._integrations_cache is None:
+            self._integrations_cache = self.list_integrations()
+        integrations = self._integrations_cache
+        query = name_or_id.lower()
+        for integration in integrations:
+            if integration.id == name_or_id or integration.name.lower() == query:
+                return integration
+        available = [i.name for i in integrations]
+        raise WherobotsValidationError(
+            f"Storage integration '{name_or_id}' not found. Available integrations: {available}"
+        )
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle
+    # ------------------------------------------------------------------ #
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release resources."""
+        self._client.close()
+
+    def __enter__(self) -> FilesAPI:
+        """Enter the runtime context (context-manager protocol)."""
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        """Exit the runtime context, closing the client."""
+        self.close()

wherobots/api/runs.py

@@ -0,0 +1,255 @@
+"""Runs API — typed wrappers around ``/runs`` endpoints."""
+
+from __future__ import annotations
+
+import builtins
+from typing import Any
+from urllib.parse import quote as _url_quote
+
+import requests
+
+from wherobots.api.base import BaseClient
+from wherobots.config import WherobotsConfig
+from wherobots.enums import JobStatus
+from wherobots.exceptions import WherobotsAPIError
+from wherobots.models import (
+    CreateRunPayload,
+    LogsResponse,
+    RunListPage,
+    RunMetricsResponse,
+    RunView,
+)
+from wherobots.utils.logger import get_logger
+
+logger = get_logger("api.runs")
+
+
+class RunsAPI:
+    """High-level, typed API surface for Wherobots job runs.
+
+    Wraps the low-level ``BaseClient`` and provides typed request/response
+    methods for every ``/runs`` endpoint.
+
+    Args:
+        client: A configured ``BaseClient`` instance.
+    """
+
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+
+    # ------------------------------------------------------------------ #
+    # Helpers
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _safe_run_id(run_id: str) -> str:
+        """URL-encode a run ID for safe path interpolation.
+
+        Args:
+            run_id: Raw run identifier.
+
+        Returns:
+            The percent-encoded run ID string.
+        """
+        return _url_quote(run_id, safe="")
+
+    @staticmethod
+    def _parse_json(response: requests.Response) -> dict[str, Any]:
+        """Safely parse JSON from an HTTP response.
+
+        Args:
+            response: The ``requests.Response`` to parse.
+
+        Returns:
+            Parsed JSON body as a dictionary.
+
+        Raises:
+            WherobotsAPIError: If the body is not valid JSON.
+        """
+        try:
+            parsed: dict[str, Any] = response.json()
+        except (ValueError, requests.exceptions.JSONDecodeError) as exc:
+            raise WherobotsAPIError(
+                f"Invalid JSON in API response (status {response.status_code})",
+                status_code=response.status_code,
+            ) from exc
+        return parsed
+
+    # ------------------------------------------------------------------ #
+    # Factory
+    # ------------------------------------------------------------------ #
+
+    @classmethod
+    def from_config(cls, config: WherobotsConfig, **kwargs: Any) -> RunsAPI:
+        """Build a ``RunsAPI`` from a ``WherobotsConfig``.
+
+        Args:
+            config: Validated configuration object.
+            **kwargs: Additional keyword arguments forwarded to
+                ``BaseClient.__init__`` (e.g. ``max_retries``).
+
+        Returns:
+            A new ``RunsAPI`` instance backed by the configured client.
+        """
+        client = BaseClient(config, **kwargs)
+        return cls(client)
+
+    # ------------------------------------------------------------------ #
+    # Endpoints
+    # ------------------------------------------------------------------ #
+
+    def create(
+        self,
+        payload: CreateRunPayload,
+        region: str = "aws-us-west-2",
+    ) -> RunView:
+        """Submit a new job run (``POST /runs``).
+
+        Args:
+            payload: The run configuration including script/JAR
+                details, runtime, and resource settings.
+            region: Wherobots deployment region (default
+                ``"aws-us-west-2"``).
+
+        Returns:
+            A ``RunView`` representing the created run.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        params = {"region": region}
+        body = payload.to_dict()
+        logger.info("Creating run '%s' in %s", payload.name, region)
+        response = self._client.post("/runs", params=params, json_body=body)
+        return RunView.from_dict(self._parse_json(response))
+
+    def get(self, run_id: str) -> RunView:
+        """Fetch a single run (``GET /runs/{run_id}``).
+
+        Args:
+            run_id: Unique identifier of the run to retrieve.
+
+        Returns:
+            A ``RunView`` with the current run state.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        safe_id = self._safe_run_id(run_id)
+        response = self._client.get(f"/runs/{safe_id}")
+        return RunView.from_dict(self._parse_json(response))
+
+    def cancel(self, run_id: str) -> None:
+        """Cancel a run (``POST /runs/{run_id}/cancel``).
+
+        Args:
+            run_id: Unique identifier of the run to cancel.
+
+        Raises:
+            WherobotsAPIError: On HTTP failures.
+        """
+        safe_id = self._safe_run_id(run_id)
+        self._client.post(f"/runs/{safe_id}/cancel")
+        logger.info("Cancel requested for run %s", run_id)
+
+    def get_logs(
+        self,
+        run_id: str,
+        cursor: int | str = 0,
+        size: int = 100,
+    ) -> LogsResponse:
+        """Fetch logs (``GET /runs/{run_id}/logs``).
+
+        Args:
+            run_id: Unique identifier of the run.
+            cursor: Pagination cursor — accepts either an integer byte
+                offset (legacy) or a string cursor returned by the API
+                via ``LogsResponse.next_page``. Defaults to ``0``.
+            size: Maximum number of log lines to return. Defaults to
+                ``100``.
+
+        Returns:
+            A ``LogsResponse`` containing log items and pagination info.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        safe_id = self._safe_run_id(run_id)
+        params: dict[str, Any] = {"cursor": cursor, "size": size}
+        response = self._client.get(f"/runs/{safe_id}/logs", params=params)
+        return LogsResponse.from_dict(self._parse_json(response))
+
+    def get_metrics(self, run_id: str) -> RunMetricsResponse:
+        """Fetch metrics (``GET /runs/{run_id}/metrics``).
+
+        Args:
+            run_id: Unique identifier of the run.
+
+        Returns:
+            A ``RunMetricsResponse`` with instant and series metrics.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        safe_id = self._safe_run_id(run_id)
+        response = self._client.get(f"/runs/{safe_id}/metrics")
+        return RunMetricsResponse.from_dict(self._parse_json(response))
+
+    def list(
+        self,
+        region: str | None = None,
+        name_pattern: str | None = None,
+        created_after: str | None = None,
+        status: builtins.list[str | JobStatus] | None = None,
+        cursor: str | None = None,
+        size: int = 50,
+    ) -> RunListPage:
+        """List runs with optional filters (``GET /runs``).
+
+        Args:
+            region: Filter by deployment region.
+            name_pattern: Filter by job name (substring match).
+            created_after: ISO-8601 timestamp; only return runs created
+                after this time.
+            status: Filter by one or more job statuses (strings or
+                ``JobStatus`` enum values).
+            cursor: Opaque pagination cursor from a previous response.
+            size: Page size (max ``100``). Defaults to ``50``.
+
+        Returns:
+            A ``RunListPage`` containing the matched runs, total count,
+            and an optional cursor for the next page.
+
+        Raises:
+            WherobotsAPIError: On HTTP or JSON-parsing failures.
+        """
+        params: dict[str, Any] = {"size": min(size, 100)}
+        if region:
+            params["region"] = region
+        if name_pattern:
+            params["name"] = name_pattern
+        if created_after:
+            params["created_after"] = created_after
+        if status:
+            params["status"] = [s.value if isinstance(s, JobStatus) else s for s in status]
+        if cursor:
+            params["cursor"] = cursor
+
+        response = self._client.get("/runs", params=params)
+        return RunListPage.from_dict(self._parse_json(response))
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle
+    # ------------------------------------------------------------------ #
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release resources."""
+        self._client.close()
+
+    def __enter__(self) -> RunsAPI:
+        """Enter the runtime context (context-manager protocol)."""
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        """Exit the runtime context, closing the client."""
+        self.close()