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

wherobots/config.py

@@ -0,0 +1,165 @@
+"""Configuration helpers for the Wherobots Jobs client."""
+
+from __future__ import annotations
+
+import os
+import warnings
+from dataclasses import dataclass
+
+from wherobots.exceptions import WherobotsConfigError
+
+
+@dataclass(frozen=True, repr=False)
+class WherobotsConfig:
+    """Immutable configuration for the Wherobots Jobs client.
+
+    Attributes:
+        api_key: Wherobots API key.
+        region: Default deployment region (e.g. ``"aws-us-west-2"``).
+        s3_bucket: S3 bucket for script uploads.
+        s3_prefix: Key prefix within the bucket.
+        base_url: Wherobots API base URL (must use HTTPS).
+        version: API version string.
+        request_timeout_seconds: HTTP request timeout in seconds.
+    """
+
+    api_key: str | None = None
+    region: str | None = None
+    s3_bucket: str | None = None
+    s3_prefix: str = "wherobots-jobs"
+    base_url: str = "https://api.cloud.wherobots.com"
+    version: str = "latest"
+    request_timeout_seconds: int = 30
+
+    def __repr__(self) -> str:
+        """Return a string representation with the API key masked."""
+        masked_key: str | None = None
+        if self.api_key:
+            # Show the last 4 characters only when the key is long
+            # enough that those 4 characters don't meaningfully leak
+            # the secret. For keys of 8 characters or fewer, mask the
+            # entire value.
+            masked_key = f"***{self.api_key[-4:]}" if len(self.api_key) > 8 else "***"
+        return (
+            f"WherobotsConfig("
+            f"api_key={masked_key!r}, "
+            f"region={self.region!r}, "
+            f"s3_bucket={self.s3_bucket!r}, "
+            f"s3_prefix={self.s3_prefix!r}, "
+            f"base_url={self.base_url!r}, "
+            f"version={self.version!r}, "
+            f"request_timeout_seconds={self.request_timeout_seconds!r})"
+        )
+
+    def __post_init__(self) -> None:
+        """Validate configuration values after dataclass init.
+
+        Raises:
+            WherobotsConfigError: If ``request_timeout_seconds`` is not
+                positive, or if ``base_url`` does not use HTTPS.
+        """
+        if self.request_timeout_seconds <= 0:
+            raise WherobotsConfigError("request_timeout_seconds must be a positive integer")
+
+        # Fail fast on non-HTTPS base URLs. The low-level ``BaseClient``
+        # also rechecks this, but catching it at config-construction
+        # time surfaces misconfiguration before any HTTP work begins.
+        normalized = self.base_url.rstrip("/")
+        if normalized.startswith("http://"):
+            raise WherobotsConfigError(
+                "base_url must use HTTPS. Sending API keys over plaintext "
+                f"HTTP is not allowed. Got: {self.base_url}"
+            )
+        if not normalized.startswith("https://"):
+            raise WherobotsConfigError(f"base_url must be an https:// URL. Got: {self.base_url}")
+
+    @classmethod
+    def from_env(
+        cls,
+        api_key: str | None = None,
+        region: str | None = None,
+        s3_bucket: str | None = None,
+        s3_prefix: str | None = None,
+        base_url: str | None = None,
+        version: str | None = None,
+        request_timeout_seconds: int | None = None,
+    ) -> WherobotsConfig:
+        """Build configuration from environment variables with optional overrides.
+
+        Explicit parameters take priority over environment variables.
+        Empty-string env vars are treated as unset.
+
+        Args:
+            api_key: Override for ``WHEROBOTS_API_KEY``.
+            region: Override for ``WHEROBOTS_REGION``.
+            s3_bucket: Override for ``WHEROBOTS_S3_BUCKET``.
+            s3_prefix: Override for ``WHEROBOTS_S3_PREFIX``.
+            base_url: Override for ``WHEROBOTS_API_BASE_URL``.
+            version: Override for ``WHEROBOTS_VERSION``.
+            request_timeout_seconds: Override for
+                ``WHEROBOTS_REQUEST_TIMEOUT_SECONDS``.
+
+        Returns:
+            A validated ``WherobotsConfig`` instance.
+
+        Raises:
+            WherobotsConfigError: If the timeout env var is not a valid
+                integer, or if validation in ``__post_init__`` fails.
+        """
+
+        def _env(var: str) -> str | None:
+            """Return env var value, treating empty strings as None."""
+            val = os.environ.get(var)
+            return val if val else None
+
+        # Parse timeout with error handling for malformed env var
+        if request_timeout_seconds is not None:
+            timeout = request_timeout_seconds
+        else:
+            raw_timeout = _env("WHEROBOTS_REQUEST_TIMEOUT_SECONDS")
+            if raw_timeout is not None:
+                try:
+                    timeout = int(raw_timeout)
+                except ValueError as exc:
+                    raise WherobotsConfigError(
+                        f"WHEROBOTS_REQUEST_TIMEOUT_SECONDS must be an integer, "
+                        f"got: {raw_timeout!r}"
+                    ) from exc
+            else:
+                timeout = 30
+
+        # Emit deprecation warnings for S3-related env vars that are no
+        # longer used (presigned uploads are the sole upload method).
+        resolved_bucket = s3_bucket or _env("WHEROBOTS_S3_BUCKET")
+        resolved_prefix = s3_prefix or _env("WHEROBOTS_S3_PREFIX")
+
+        if resolved_bucket:
+            warnings.warn(
+                "WHEROBOTS_S3_BUCKET / s3_bucket is deprecated and ignored. "
+                "The SDK now uploads files exclusively via presigned URLs "
+                "(only an API key is needed). This setting will be removed "
+                "in a future release.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if resolved_prefix and resolved_prefix != "wherobots-jobs":
+            warnings.warn(
+                "WHEROBOTS_S3_PREFIX / s3_prefix is deprecated and ignored. "
+                "The SDK now uploads files exclusively via presigned URLs "
+                "(only an API key is needed). This setting will be removed "
+                "in a future release.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        return cls(
+            api_key=api_key or _env("WHEROBOTS_API_KEY"),
+            region=region or _env("WHEROBOTS_REGION"),
+            s3_bucket=s3_bucket or _env("WHEROBOTS_S3_BUCKET"),
+            s3_prefix=s3_prefix or _env("WHEROBOTS_S3_PREFIX") or "wherobots-jobs",
+            base_url=base_url
+            or _env("WHEROBOTS_API_BASE_URL")
+            or "https://api.cloud.wherobots.com",
+            version=version or _env("WHEROBOTS_VERSION") or "latest",
+            request_timeout_seconds=timeout,
+        )

wherobots/enums.py

@@ -0,0 +1,140 @@
+"""Enumeration types for the Wherobots Jobs API."""
+
+from enum import Enum
+
+
+class JobStatus(Enum):
+    """Job run status values (from OpenAPI ``RunStatus``)."""
+
+    PENDING = "PENDING"
+    RUNNING = "RUNNING"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+
+    @property
+    def is_terminal(self) -> bool:
+        """Return ``True`` if this status represents a finished run."""
+        return self in _TERMINAL_STATUSES
+
+
+_TERMINAL_STATUSES = frozenset(
+    {
+        JobStatus.COMPLETED,
+        JobStatus.FAILED,
+        JobStatus.CANCELLED,
+    }
+)
+
+_TERMINAL_STATUS_VALUES = frozenset(s.value for s in _TERMINAL_STATUSES)
+
+
+def is_terminal_status(status: "JobStatus | str | None") -> bool:
+    """Return True if *status* is a known terminal state.
+
+    Accepts a :class:`JobStatus`, a raw string (e.g. an API-added status
+    the SDK doesn't yet know about), or ``None``. Unknown strings are
+    treated as **non-terminal** — conservative so callers keep polling
+    rather than bailing early on a new running/transitional state.
+    """
+    if status is None:
+        return False
+    if isinstance(status, JobStatus):
+        return status in _TERMINAL_STATUSES
+    return status in _TERMINAL_STATUS_VALUES
+
+
+class Runtime(Enum):
+    """Available Wherobots compute runtime sizes.
+
+    The values match the lowercase ``RuntimeId`` strings accepted by the
+    API. This enum is a **convenience subset** — the API also accepts
+    legacy uppercase values (``TINY``, ``SMALL``, ``MEDIUM``, ``LARGE``,
+    ``XLARGE``, ``XXLARGE``) and may add new runtimes at any time. Where
+    the SDK accepts a runtime argument (e.g. ``WherobotsJob(runtime=...)``)
+    it also accepts a plain string, so unknown runtimes are never
+    blocked client-side.
+    """
+
+    MICRO = "micro"
+    TINY = "tiny"
+    SMALL = "small"
+    MEDIUM = "medium"
+    LARGE = "large"
+    X_LARGE = "x-large"
+    DOUBLE_X_LARGE = "2x-large"
+    QUAD_X_LARGE = "4x-large"
+    MEDIUM_HIMEM = "medium-himem"
+    LARGE_HIMEM = "large-himem"
+    X_LARGE_HIMEM = "x-large-himem"
+    DOUBLE_X_LARGE_HIMEM = "2x-large-himem"
+    QUAD_X_LARGE_HIMEM = "4x-large-himem"
+    X_LARGE_HICPU = "x-large-hicpu"
+    DOUBLE_X_LARGE_HICPU = "2x-large-hicpu"
+    X_LARGE_MATCHER = "x-large-matcher"
+    DOUBLE_X_LARGE_MATCHER = "2x-large-matcher"
+    MICRO_A10_GPU = "micro-a10-gpu"
+    TINY_A10_GPU = "tiny-a10-gpu"
+    SMALL_A10_GPU = "small-a10-gpu"
+    MEDIUM_A10_GPU = "medium-a10-gpu"
+    LARGE_A10_GPU = "large-a10-gpu"
+    X_LARGE_A10_GPU = "x-large-a10-gpu"
+
+
+class Region(Enum):
+    """Known AWS regions for Wherobots deployments.
+
+    Region is a **free-form string** in the Wherobots API — this enum
+    lists regions that exist today for convenience, but the API may
+    add new regions at any time. SDK call sites that accept a region
+    (e.g. ``WherobotsJob(region=...)``) always accept a plain string
+    as well, so unknown regions are never blocked client-side.
+    """
+
+    EU_WEST_1 = "aws-eu-west-1"
+    US_WEST_2 = "aws-us-west-2"
+    US_EAST_1 = "aws-us-east-1"
+    AP_SOUTH_1 = "aws-ap-south-1"
+
+
+class DependencyType(Enum):
+    """Dependency source types (OpenAPI ``DependencySourceType``)."""
+
+    PYPI = "PYPI"
+    FILE = "FILE"
+
+
+class DependencyFileType(Enum):
+    """File types for ``FILE`` dependencies (from OpenAPI ``DependencyFileType``)."""
+
+    JAR = "JAR"
+    PYTHON_WHEEL = "PYTHON_WHEEL"
+    ZIP = "ZIP"
+    OTHER = "OTHER"
+
+
+class AppType(Enum):
+    """Kube app types attached to a run (OpenAPI ``AppType``)."""
+
+    JUPYTER = "JUPYTER"
+    SQL_SESSION = "SQL_SESSION"
+    RUN = "RUN"
+
+
+class AppStatus(Enum):
+    """Lifecycle status of the Kube app backing a run (OpenAPI ``AppStatus``)."""
+
+    PENDING = "PENDING"
+    PREPARING = "PREPARING"
+    PREPARE_FAILED = "PREPARE_FAILED"
+    REQUESTED = "REQUESTED"
+    DEPLOYING = "DEPLOYING"
+    DEPLOY_FAILED = "DEPLOY_FAILED"
+    DEPLOYED = "DEPLOYED"
+    INITIALIZING = "INITIALIZING"
+    INIT_FAILED = "INIT_FAILED"
+    READY = "READY"
+    DESTROY_REQUESTED = "DESTROY_REQUESTED"
+    DESTROYING = "DESTROYING"
+    DESTROY_FAILED = "DESTROY_FAILED"
+    DESTROYED = "DESTROYED"

wherobots/exceptions.py

@@ -0,0 +1,47 @@
+"""Custom exceptions for the Wherobots Jobs API client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class WherobotsJobError(Exception):
+    """Base exception for all Wherobots job errors."""
+
+
+class WherobotsAPIError(WherobotsJobError):
+    """Raised when the Wherobots API returns an error response."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response: dict[str, Any] | None = None,
+        request_id: str | None = None,
+    ):
+        self.status_code = status_code
+        self.response = response
+        self.request_id = request_id
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        parts = [super().__str__()]
+        if self.request_id:
+            parts.append(f"[request_id={self.request_id}]")
+        return " ".join(parts)
+
+
+class WherobotsValidationError(WherobotsJobError):
+    """Raised for client-side validation errors before making API calls."""
+
+
+class WherobotsS3Error(WherobotsJobError):
+    """Raised when an S3 upload or access operation fails."""
+
+
+class WherobotsConfigError(WherobotsJobError):
+    """Raised when configuration is missing or invalid."""
+
+
+class WherobotsTimeoutError(WherobotsJobError):
+    """Raised when a job exceeds the specified timeout."""