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

wherobots/__init__.py

@@ -1,6 +1,7 @@
-"""Wherobots Python SDK (Jobs API surface)."""
+"""Wherobots Python SDK (Jobs API and Files surfaces)."""
 
 from wherobots.__version__ import __version__
+from wherobots.api.drive import Files, FilesDrive
 from wherobots.api.files import FilesAPI
 from wherobots.client import WherobotsJob
 from wherobots.config import WherobotsConfig
@@ -9,6 +10,7 @@ from wherobots.enums import (
     AppType,
     DependencyFileType,
     DependencyType,
+    Drive,
     JobStatus,
     Region,
     Runtime,
@@ -17,7 +19,10 @@ from wherobots.enums import (
 from wherobots.exceptions import (
     WherobotsAPIError,
     WherobotsConfigError,
+    WherobotsFileNotFoundError,
+    WherobotsFilesNotEnabledError,
     WherobotsJobError,
+    WherobotsNotAuthenticatedError,
     WherobotsS3Error,
     WherobotsTimeoutError,
     WherobotsValidationError,
@@ -25,6 +30,7 @@ from wherobots.exceptions import (
 from wherobots.models import (
     CreateRunPayload,
     FileDependency,
+    FileEntry,
     KubeAppEvent,
     LogItem,
     LogsResponse,
@@ -43,6 +49,7 @@ from wherobots.models import (
     TemporaryAwsCredentials,
     UtilizationStats,
 )
+from wherobots.sdk import Wherobots
 
 # Convenience alias
 Job = WherobotsJob
@@ -50,6 +57,9 @@ Job = WherobotsJob
 __all__ = [
     "__version__",
     # Client
+    "Wherobots",
+    "Files",
+    "FilesDrive",
     "WherobotsJob",
     "Job",
     "FilesAPI",
@@ -57,6 +67,7 @@ __all__ = [
     # Enums
     "Runtime",
     "Region",
+    "Drive",
     "JobStatus",
     "AppStatus",
     "AppType",
@@ -70,6 +81,9 @@ __all__ = [
     "WherobotsS3Error",
     "WherobotsConfigError",
     "WherobotsTimeoutError",
+    "WherobotsNotAuthenticatedError",
+    "WherobotsFilesNotEnabledError",
+    "WherobotsFileNotFoundError",
     # Models
     "CreateRunPayload",
     "RunView",
@@ -90,4 +104,5 @@ __all__ = [
     "StorageIntegration",
     "TemporaryAwsCredentials",
     "UtilizationStats",
+    "FileEntry",
 ]

wherobots/__version__.py

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

wherobots/api/__init__.py

@@ -1,7 +1,8 @@
 """Wherobots API layer — public exports."""
 
 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
 
-__all__ = ["BaseClient", "FilesAPI", "RunsAPI"]
+__all__ = ["BaseClient", "Files", "FilesAPI", "FilesDrive", "RunsAPI"]

wherobots/api/base.py

@@ -2,6 +2,8 @@
 
 ``BaseClient`` wraps a ``requests.Session`` with:
 * Auth header construction (``X-API-Key``).
+* Client attribution via the advisory ``X-Wherobots-Client`` header,
+  set once on the session so every outgoing request carries it.
 * 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
@@ -11,15 +13,16 @@
 from __future__ import annotations
 
 import warnings
-from typing import Any
+from typing import Any  # noqa: TID251
 
 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.config import WherobotsConfig  # noqa: TC001
 from wherobots.exceptions import WherobotsAPIError, WherobotsConfigError
+from wherobots.utils.client_header import CLIENT_HEADER, client_header_value
 from wherobots.utils.logger import get_logger
 
 logger = get_logger("api")
@@ -29,6 +32,7 @@ logger = get_logger("api")
 _DEFAULT_RETRIES = 3
 _DEFAULT_BACKOFF_FACTOR = 0.5
 _RETRIABLE_STATUS_CODES = (429, 502, 503)
+_REDIRECT_STATUS_CODES = frozenset({301, 302, 303, 307, 308})
 
 
 class BaseClient:
@@ -45,7 +49,7 @@ class BaseClient:
             retries.
     """
 
-    def __init__(
+    def __init__(  # noqa: D107
         self,
         config: WherobotsConfig,
         max_retries: int = _DEFAULT_RETRIES,
@@ -94,15 +98,24 @@ class BaseClient:
         # Intentionally not mounting on http:// — API keys must never
         # be transmitted over plaintext HTTP.
 
-        # Common headers
+        # Common headers. ``X-Wherobots-Client`` is set here, on the
+        # session, so it rides along with every request this client makes
+        # instead of having to be threaded through each call site. Auth
+        # headers are merged last so nothing can displace them.
         self._session.headers.update(
             {
                 "Content-Type": "application/json",
                 "User-Agent": f"wherobots-python-sdk/{__version__}",
+                CLIENT_HEADER: client_header_value(config.client_chain),
                 **self._auth_headers(config.api_key),
             }
         )
 
+    @property
+    def timeout(self) -> int:
+        """Per-request timeout in seconds, from ``WherobotsConfig``."""
+        return self._timeout
+
     # --------------------------------------------------------------------- #
     # Auth
     # --------------------------------------------------------------------- #
@@ -154,35 +167,86 @@ class BaseClient:
                 timeout=self._timeout,
             )
             response.raise_for_status()
-            return response
+            return response  # noqa: TRY300
         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 self._api_error(exc) from exc
+        except requests.RequestException as exc:
+            raise WherobotsAPIError(f"Request failed: {exc}") from exc
 
-            raise WherobotsAPIError(
-                message,
-                status_code=status_code,
-                response=error_payload,
-                request_id=request_id,
-            ) from exc
+    @staticmethod
+    def _api_error(exc: requests.HTTPError) -> WherobotsAPIError:
+        """Map an HTTP error response to ``WherobotsAPIError``.
+
+        Args:
+            exc: The ``HTTPError`` raised by ``raise_for_status``.
+
+        Returns:
+            A ``WherobotsAPIError`` carrying the status, parsed body and request id.
+        """
+        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}"
+
+        return WherobotsAPIError(
+            message,
+            status_code=status_code,
+            response=error_payload,
+            request_id=request_id,
+        )
+
+    def get_redirect_target(self, path: str, params: dict[str, str] | None = None) -> str:
+        """Send a GET that must answer with a redirect, and return its target.
+
+        The redirect is not followed, so the API key never travels to the
+        target. Errors are mapped exactly as in ``request``.
+
+        Args:
+            path: API path appended to the base URL.
+            params: Optional query-string parameters.
+
+        Returns:
+            The ``Location`` the API redirected to.
+
+        Raises:
+            WherobotsAPIError: On HTTP or connection failures, or when the
+                API answers without a redirect.
+        """
+        url = f"{self._base_url}{path}"
+        try:
+            response = self._session.request(
+                "GET",
+                url,
+                params=params,
+                timeout=self._timeout,
+                allow_redirects=False,
+            )
+            response.raise_for_status()
+        except requests.HTTPError as exc:
+            raise self._api_error(exc) from exc
         except requests.RequestException as exc:
             raise WherobotsAPIError(f"Request failed: {exc}") from exc
+        location = response.headers.get("Location")
+        if response.status_code not in _REDIRECT_STATUS_CODES or not isinstance(location, str):
+            raise WherobotsAPIError(
+                f"Expected a redirect from GET {path}, got status {response.status_code}",
+                status_code=response.status_code,
+            )
+        return location
 
     # Convenience wrappers
     def get(self, path: str, params: dict[str, Any] | None = None) -> requests.Response:
@@ -224,15 +288,15 @@ class BaseClient:
         self._session.close()
         self._closed = True
 
-    def __enter__(self) -> BaseClient:
+    def __enter__(self) -> BaseClient:  # noqa: PYI034
         """Enter the runtime context (context-manager protocol)."""
         return self
 
-    def __exit__(self, *exc: Any) -> None:
+    def __exit__(self, *exc: object) -> None:
         """Exit the runtime context, closing the session."""
         self.close()
 
-    def __del__(self) -> None:
+    def __del__(self) -> None:  # noqa: D105
         # 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
@@ -242,7 +306,7 @@ class BaseClient:
                 return
             if getattr(self, "_session", None) is None:
                 return
-        except Exception:
+        except Exception:  # noqa: BLE001
             return
         try:
             warnings.warn(
@@ -252,5 +316,5 @@ class BaseClient:
                 stacklevel=2,
             )
             self._session.close()
-        except Exception:
+        except Exception:  # noqa: BLE001, S110
             pass