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

wherobots/__init__.py

@@ -0,0 +1,87 @@
+"""Wherobots Python SDK (Jobs API surface)."""
+
+from wherobots.__version__ import __version__
+from wherobots.client import WherobotsJob
+from wherobots.config import WherobotsConfig
+from wherobots.enums import (
+    AppStatus,
+    AppType,
+    DependencyFileType,
+    DependencyType,
+    JobStatus,
+    Region,
+    Runtime,
+    is_terminal_status,
+)
+from wherobots.exceptions import (
+    WherobotsAPIError,
+    WherobotsConfigError,
+    WherobotsJobError,
+    WherobotsS3Error,
+    WherobotsTimeoutError,
+    WherobotsValidationError,
+)
+from wherobots.models import (
+    CreateRunPayload,
+    FileDependency,
+    KubeAppEvent,
+    LogItem,
+    LogsResponse,
+    OrganizationCustomer,
+    PyPiDependency,
+    RunAppMeta,
+    RunEnvironment,
+    RunEventMeta,
+    RunJarPayload,
+    RunKubeApp,
+    RunListPage,
+    RunMetricsResponse,
+    RunPythonPayload,
+    RunView,
+    StorageIntegration,
+)
+
+# Convenience alias
+Job = WherobotsJob
+
+__all__ = [
+    "__version__",
+    # Client
+    "WherobotsJob",
+    "Job",
+    "WherobotsConfig",
+    # Enums
+    "Runtime",
+    "Region",
+    "JobStatus",
+    "AppStatus",
+    "AppType",
+    "DependencyType",
+    "DependencyFileType",
+    "is_terminal_status",
+    # Exceptions
+    "WherobotsJobError",
+    "WherobotsAPIError",
+    "WherobotsValidationError",
+    "WherobotsS3Error",
+    "WherobotsConfigError",
+    "WherobotsTimeoutError",
+    # Models
+    "CreateRunPayload",
+    "RunView",
+    "RunAppMeta",
+    "RunKubeApp",
+    "KubeAppEvent",
+    "RunEventMeta",
+    "OrganizationCustomer",
+    "RunListPage",
+    "LogsResponse",
+    "LogItem",
+    "RunMetricsResponse",
+    "RunPythonPayload",
+    "RunJarPayload",
+    "RunEnvironment",
+    "PyPiDependency",
+    "FileDependency",
+    "StorageIntegration",
+]

wherobots/__version__.py

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

wherobots/api/__init__.py

@@ -0,0 +1,7 @@
+"""Wherobots API layer — public exports."""
+
+from wherobots.api.base import BaseClient
+from wherobots.api.files import FilesAPI
+from wherobots.api.runs import RunsAPI
+
+__all__ = ["BaseClient", "FilesAPI", "RunsAPI"]

wherobots/api/base.py

@@ -0,0 +1,256 @@
+"""Low-level HTTP client for the Wherobots REST API.
+
+``BaseClient`` wraps a ``requests.Session`` with:
+* Auth header construction (``X-API-Key``).
+* Automatic retry with exponential back-off for transient errors
+  (429 Too Many Requests, 503 Service Unavailable, connection errors).
+* Unified error handling that maps HTTP failures into
+  ``WherobotsAPIError``.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from wherobots.__version__ import __version__
+from wherobots.config import WherobotsConfig
+from wherobots.exceptions import WherobotsAPIError, WherobotsConfigError
+from wherobots.utils.logger import get_logger
+
+logger = get_logger("api")
+
+# Default retry policy: 3 retries with back-off on 429 / 502 / 503 and
+# connection-level failures.
+_DEFAULT_RETRIES = 3
+_DEFAULT_BACKOFF_FACTOR = 0.5
+_RETRIABLE_STATUS_CODES = (429, 502, 503)
+
+
+class BaseClient:
+    """Thin HTTP wrapper around ``requests.Session``.
+
+    Provides auth header injection, automatic retries with exponential
+    back-off, and unified error mapping to ``WherobotsAPIError``.
+
+    Args:
+        config: A populated ``WherobotsConfig``.  Must contain at least
+            ``api_key`` and ``base_url``.
+        max_retries: Maximum number of retries for transient failures.
+        backoff_factor: Multiplier for exponential back-off between
+            retries.
+    """
+
+    def __init__(
+        self,
+        config: WherobotsConfig,
+        max_retries: int = _DEFAULT_RETRIES,
+        backoff_factor: float = _DEFAULT_BACKOFF_FACTOR,
+    ) -> None:
+        # Set early so __del__ never blows up on a partially-initialized
+        # instance. ``_session`` is populated below once the request
+        # session is built.
+        self._closed = False
+
+        if not config.api_key or not config.api_key.strip():
+            raise WherobotsConfigError(
+                "API key required. Provide via api_key parameter or "
+                "WHEROBOTS_API_KEY environment variable."
+            )
+
+        self._config = config
+        self._base_url = config.base_url.rstrip("/")
+        self._timeout = config.request_timeout_seconds
+
+        # Validate URL scheme
+        if not (self._base_url.startswith("https://") or self._base_url.startswith("http://")):
+            raise WherobotsConfigError(f"base_url must use https://. Got: {self._base_url}")
+
+        if self._base_url.startswith("http://"):
+            raise WherobotsConfigError(
+                "base_url must use HTTPS. Sending API keys over plaintext "
+                "HTTP is not allowed. Got: " + self._base_url
+            )
+
+        # Build a session with retry adapter
+        self._session = requests.Session()
+
+        # Disable redirect following to prevent auth header leaks
+        self._session.max_redirects = 0
+
+        retry = Retry(
+            total=max_retries,
+            backoff_factor=backoff_factor,
+            status_forcelist=list(_RETRIABLE_STATUS_CODES),
+            allowed_methods=["GET"],
+            raise_on_status=False,
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        self._session.mount("https://", adapter)
+        # Intentionally not mounting on http:// — API keys must never
+        # be transmitted over plaintext HTTP.
+
+        # Common headers
+        self._session.headers.update(
+            {
+                "Content-Type": "application/json",
+                "User-Agent": f"wherobots-python-sdk/{__version__}",
+                **self._auth_headers(config.api_key),
+            }
+        )
+
+    # --------------------------------------------------------------------- #
+    # Auth
+    # --------------------------------------------------------------------- #
+
+    @staticmethod
+    def _auth_headers(api_key: str) -> dict[str, str]:
+        """Build the authentication header dictionary.
+
+        Args:
+            api_key: The Wherobots API key.
+
+        Returns:
+            A single-entry dict with the ``X-API-Key`` header.
+        """
+        return {"X-API-Key": api_key.strip()}
+
+    # --------------------------------------------------------------------- #
+    # Core request
+    # --------------------------------------------------------------------- #
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+    ) -> requests.Response:
+        """Send an HTTP request and return the response.
+
+        Args:
+            method: HTTP method (e.g. ``"GET"``, ``"POST"``).
+            path: API path appended to the base URL (e.g. ``"/runs"``).
+            params: Optional query-string parameters.
+            json_body: Optional JSON-serializable request body.
+
+        Returns:
+            The successful ``requests.Response``.
+
+        Raises:
+            WherobotsAPIError: On HTTP or connection failures.
+        """
+        url = f"{self._base_url}{path}"
+        try:
+            response = self._session.request(
+                method,
+                url,
+                params=params,
+                json=json_body,
+                timeout=self._timeout,
+            )
+            response.raise_for_status()
+            return response
+        except requests.HTTPError as exc:
+            response = exc.response
+            status_code = response.status_code if response is not None else None
+            error_payload = None
+            detail = None
+            request_id = None
+            if response is not None:
+                request_id = response.headers.get("X-Request-Id")
+                try:
+                    error_payload = response.json()
+                    detail = error_payload.get("message", error_payload)
+                except ValueError:
+                    detail = response.text
+
+            message = "API request failed"
+            if status_code:
+                message = f"{message} (status {status_code})"
+            if detail:
+                message = f"{message}: {detail}"
+
+            raise WherobotsAPIError(
+                message,
+                status_code=status_code,
+                response=error_payload,
+                request_id=request_id,
+            ) from exc
+        except requests.RequestException as exc:
+            raise WherobotsAPIError(f"Request failed: {exc}") from exc
+
+    # Convenience wrappers
+    def get(self, path: str, params: dict[str, Any] | None = None) -> requests.Response:
+        """Send a GET request.
+
+        Args:
+            path: API path appended to the base URL.
+            params: Optional query-string parameters.
+
+        Returns:
+            The ``requests.Response`` from the API.
+        """
+        return self.request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+    ) -> requests.Response:
+        """Send a POST request.
+
+        Args:
+            path: API path appended to the base URL.
+            params: Optional query-string parameters.
+            json_body: Optional JSON-serializable request body.
+
+        Returns:
+            The ``requests.Response`` from the API.
+        """
+        return self.request("POST", path, params=params, json_body=json_body)
+
+    # --------------------------------------------------------------------- #
+    # Lifecycle
+    # --------------------------------------------------------------------- #
+
+    def close(self) -> None:
+        """Close the underlying session."""
+        self._session.close()
+        self._closed = True
+
+    def __enter__(self) -> BaseClient:
+        """Enter the runtime context (context-manager protocol)."""
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        """Exit the runtime context, closing the session."""
+        self.close()
+
+    def __del__(self) -> None:
+        # Mirror ``open()``/``socket``: warn callers who let the client
+        # get GC'd without closing it, so connection pools don't leak
+        # silently. Guarded against partial __init__ failure and
+        # interpreter shutdown quirks.
+        try:
+            if getattr(self, "_closed", False):
+                return
+            if getattr(self, "_session", None) is None:
+                return
+        except Exception:
+            return
+        try:
+            warnings.warn(
+                f"Unclosed {type(self).__name__} — call close() or use "
+                "the object as a context manager to release the HTTP session.",
+                ResourceWarning,
+                stacklevel=2,
+            )
+            self._session.close()
+        except Exception:
+            pass