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

wherobots/__version__.py

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

wherobots/api/base.py

@@ -1,7 +1,8 @@
 """Low-level HTTP client for the Wherobots REST API.
 
 ``BaseClient`` wraps a ``requests.Session`` with:
-* Auth header construction (``X-API-Key``).
+* Auth: ``X-API-Key`` when an API key is configured, otherwise the
+  workload-identity token mounted in Wherobots notebook and job pods.
 * 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
@@ -20,6 +21,7 @@ from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
 from wherobots.__version__ import __version__
+from wherobots.api.workload_auth import shared_workload_identity_auth
 from wherobots.config import WherobotsConfig  # noqa: TC001
 from wherobots.exceptions import WherobotsAPIError, WherobotsConfigError
 from wherobots.utils.client_header import CLIENT_HEADER, client_header_value
@@ -57,8 +59,8 @@ class BaseClient:
     back-off, and unified error mapping to ``WherobotsAPIError``.
 
     Args:
-        config: A populated ``WherobotsConfig``.  Must contain at least
-            ``api_key`` and ``base_url``.
+        config: A populated ``WherobotsConfig``.  Must contain ``base_url``
+            and either ``api_key`` or ``id_token_path``.
         max_retries: Maximum number of retries for transient failures.
         backoff_factor: Multiplier for exponential back-off between
             retries.
@@ -75,10 +77,11 @@ class BaseClient:
         # session is built.
         self._closed = False
 
-        if not config.api_key or not config.api_key.strip():
+        api_key = (config.api_key or "").strip()
+        if not api_key and not config.id_token_path:
             raise WherobotsConfigError(
-                "API key required. Provide via api_key parameter or "
-                "WHEROBOTS_API_KEY environment variable."
+                "No Wherobots credentials found. Provide the api_key parameter, set "
+                "WHEROBOTS_API_KEY, or run inside a Wherobots notebook or job."
             )
 
         self._config = config
@@ -122,9 +125,14 @@ class BaseClient:
                 "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),
             }
         )
+        if api_key:
+            self._session.headers.update(self._auth_headers(api_key))
+        elif config.id_token_path:
+            self._session.auth = shared_workload_identity_auth(
+                self._base_url, config.id_token_path, self._timeout
+            )
 
     @property
     def timeout(self) -> int:

wherobots/api/drive.py

@@ -336,7 +336,7 @@ class FilesDrive:
         """
         if err.status_code == _HTTP_UNAUTHORIZED:
             return WherobotsNotAuthenticatedError(
-                "The Wherobots API key was not accepted (HTTP 401)",
+                "The Wherobots API did not accept the credentials (HTTP 401)",
                 status_code=err.status_code,
                 response=err.response,
                 request_id=err.request_id,

wherobots/api/files.py

@@ -29,7 +29,11 @@ from botocore.session import Session as BotocoreSession
 
 from wherobots.api.base import BaseClient
 from wherobots.config import WherobotsConfig  # noqa: TC001
-from wherobots.exceptions import WherobotsAPIError, WherobotsValidationError
+from wherobots.exceptions import (
+    WherobotsAPIError,
+    WherobotsNotAuthenticatedError,
+    WherobotsValidationError,
+)
 from wherobots.models import StorageIntegration, TemporaryAwsCredentials
 from wherobots.utils.logger import get_logger
 
@@ -110,6 +114,9 @@ class FilesAPI:
                 "/storage/credentials",
                 json_body={"path": path, "access_mode": access_mode},
             )
+        except WherobotsNotAuthenticatedError:
+            # The workload token exchange failed before this request was sent (ADR-0003).
+            raise
         except WherobotsAPIError as exc:
             # Scrub: never let the credentials endpoint's error
             # response body bubble out — it could contain partial

wherobots/api/workload_auth.py

@@ -0,0 +1,116 @@
+"""Workload-identity auth for code running inside Wherobots (ADR-0003).
+
+Wherobots notebook and job pods mount a workload-identity token and set
+``WHEROBOTS_ID_TOKEN_PATH`` to it. The API accepts that token as an OAuth
+refresh token at ``/ste/oauth2/token`` and returns a short-lived bearer token
+that acts as the user who launched the workload.
+"""
+
+from __future__ import annotations
+
+import functools
+import threading
+import time
+from pathlib import Path
+
+import requests
+from requests.auth import AuthBase
+
+from wherobots.exceptions import WherobotsConfigError, WherobotsNotAuthenticatedError
+
+_EXCHANGE_PATH = "/ste/oauth2/token"
+# Descriptive only: the API does not enforce scope on these tokens.
+_SCOPE = "api"
+_REFRESH_MARGIN_SECONDS = 60
+
+
+class WorkloadIdentityAuth(AuthBase):
+    """Sets ``Authorization: Bearer`` from the mounted workload-identity token.
+
+    The bearer token is cached and swapped for a new one shortly before it
+    expires, so long-running jobs keep working past its one-hour lifetime.
+
+    Args:
+        base_url: Wherobots API base URL (already validated as HTTPS).
+        id_token_path: Path to the mounted workload-identity token.
+        timeout: Timeout in seconds for the token exchange request.
+    """
+
+    def __init__(self, base_url: str, id_token_path: str, timeout: int) -> None:
+        """Build the auth; see the class docstring."""
+        self._token_url = f"{base_url}{_EXCHANGE_PATH}"
+        self._id_token_path = Path(id_token_path)
+        self._timeout = timeout
+        self._lock = threading.Lock()
+        self._access_token: str | None = None
+        self._refresh_at = 0.0
+
+    def __call__(self, request: requests.PreparedRequest) -> requests.PreparedRequest:
+        """Attach the current bearer token to *request*."""
+        request.headers["Authorization"] = f"Bearer {self._current_token()}"
+        return request
+
+    def _current_token(self) -> str:
+        with self._lock:
+            if self._access_token is None or time.monotonic() >= self._refresh_at:
+                token, expires_in = self._exchange()
+                self._access_token = token
+                self._refresh_at = time.monotonic() + max(0, expires_in - _REFRESH_MARGIN_SECONDS)
+            return self._access_token
+
+    def _exchange(self) -> tuple[str, int]:
+        try:
+            id_token = self._id_token_path.read_text(encoding="utf-8").strip()
+        except (OSError, UnicodeDecodeError) as exc:
+            raise WherobotsConfigError(
+                f"Cannot read the workload identity token at {self._id_token_path}: {exc}"
+            ) from exc
+        if not id_token:
+            raise WherobotsConfigError(
+                f"The workload identity token at {self._id_token_path} is empty"
+            )
+        # Errors carry no status_code: it would read as the status of the caller's own request.
+        try:
+            response = requests.post(
+                self._token_url,
+                data={"grant_type": "refresh_token", "refresh_token": id_token, "scope": _SCOPE},
+                timeout=self._timeout,
+                allow_redirects=False,
+            )
+            response.raise_for_status()
+            payload = response.json()
+        except requests.HTTPError as exc:
+            raise WherobotsNotAuthenticatedError(_rejection_message(exc.response)) from exc
+        except (requests.RequestException, ValueError) as exc:
+            raise WherobotsNotAuthenticatedError(
+                f"Workload identity token exchange failed: {exc}"
+            ) from exc
+
+        token = payload.get("access_token") if isinstance(payload, dict) else None
+        expires_in = payload.get("expires_in") if isinstance(payload, dict) else None
+        if not isinstance(token, str) or not isinstance(expires_in, int):
+            raise WherobotsNotAuthenticatedError(
+                "Workload identity token exchange returned an unexpected body"
+            )
+        return token, expires_in
+
+
+@functools.cache
+def shared_workload_identity_auth(
+    base_url: str, id_token_path: str, timeout: int
+) -> WorkloadIdentityAuth:
+    """Return one auth per process and token, so every client reuses one bearer token."""
+    return WorkloadIdentityAuth(base_url, id_token_path, timeout)
+
+
+def _rejection_message(response: requests.Response | None) -> str:
+    message = "Workload identity token exchange was rejected"
+    if response is None:
+        return message
+    message = f"{message} (status {response.status_code})"
+    try:
+        body = response.json()
+    except ValueError:
+        return message
+    reason = body.get("message") if isinstance(body, dict) else None
+    return f"{message}: {reason}" if isinstance(reason, str) else message

wherobots/config.py

@@ -25,6 +25,9 @@ class WherobotsConfig:
             embed this SDK (e.g. the Airflow provider). The SDK appends its
             own hop to the right of it, so the origin client stays leftmost.
             Advisory only — it never affects authentication.
+        id_token_path: Workload-identity token mounted in Wherobots notebook
+            and job pods. Used for auth only when no ``api_key`` is set
+            (ADR-0003).
     """
 
     api_key: str | None = None
@@ -35,6 +38,7 @@ class WherobotsConfig:
     version: str = "latest"
     request_timeout_seconds: int = 30
     client_chain: str | None = None
+    id_token_path: str | None = None
 
     def __repr__(self) -> str:
         """Return a string representation with the API key masked."""
@@ -54,7 +58,8 @@ class WherobotsConfig:
             f"base_url={self.base_url!r}, "
             f"version={self.version!r}, "
             f"request_timeout_seconds={self.request_timeout_seconds!r}, "
-            f"client_chain={self.client_chain!r})"
+            f"client_chain={self.client_chain!r}, "
+            f"id_token_path={self.id_token_path!r})"
         )
 
     def __post_init__(self) -> None:
@@ -90,6 +95,7 @@ class WherobotsConfig:
         version: str | None = None,
         request_timeout_seconds: int | None = None,
         client_chain: str | None = None,
+        id_token_path: str | None = None,
     ) -> WherobotsConfig:
         """Build configuration from environment variables with optional overrides.
 
@@ -108,6 +114,8 @@ class WherobotsConfig:
             client_chain: Override for ``WHEROBOTS_CLIENT_CHAIN`` — the
                 upstream ``X-Wherobots-Client`` chain this SDK appends its
                 own hop to.
+            id_token_path: Override for ``WHEROBOTS_ID_TOKEN_PATH``, which
+                Wherobots notebook and job pods set.
 
         Returns:
             A validated ``WherobotsConfig`` instance.
@@ -163,7 +171,8 @@ class WherobotsConfig:
             )
 
         return cls(
-            api_key=api_key or _env("WHEROBOTS_API_KEY"),
+            # A blank key must not hide WHEROBOTS_API_KEY behind workload identity.
+            api_key=(api_key or "").strip() 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",
@@ -173,4 +182,5 @@ class WherobotsConfig:
             version=version or _env("WHEROBOTS_VERSION") or "latest",
             request_timeout_seconds=timeout,
             client_chain=client_chain or _env("WHEROBOTS_CLIENT_CHAIN"),
+            id_token_path=id_token_path or _env("WHEROBOTS_ID_TOKEN_PATH"),
         )

wherobots/exceptions.py

@@ -48,7 +48,7 @@ class WherobotsTimeoutError(WherobotsJobError):
 
 
 class WherobotsNotAuthenticatedError(WherobotsAPIError):
-    """Raised when the Wherobots API does not accept the API key (HTTP 401)."""
+    """Raised when the Wherobots API does not accept the credentials."""
 
 
 class WherobotsFileNotFoundError(WherobotsAPIError):

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.6.0
+Version: 0.7.0
 Summary: Python SDK for Wherobots (currently covers the Jobs REST API)
 Author-email: Wherobots <support@wherobots.com>
 License-Expression: Apache-2.0
@@ -21,7 +21,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.34.2
-Requires-Dist: boto3>=1.43.108
+Requires-Dist: boto3>=1.34.0
 Dynamic: license-file
 
 # Wherobots Python SDK
@@ -118,18 +118,27 @@ job = WherobotsJob(
 
 The API key can also be set via the `WHEROBOTS_API_KEY` environment variable.
 
+Inside a Wherobots notebook or job, no API key is needed. The SDK authenticates as the user who
+launched the workload, using the token Wherobots mounts in the pod. An API key, when set, takes
+precedence.
+
+```python
+job = WherobotsJob(script="s3://bucket/script.py", name="my-job-001")
+```
+
 ## Configuration
 
 ### Environment Variables
 
 | Variable                           | Description                     | Default                              |
 |------------------------------------|---------------------------------|--------------------------------------|
-| `WHEROBOTS_API_KEY`                | API key                         | *(required)*                         |
+| `WHEROBOTS_API_KEY`                | API key                         | *(required outside Wherobots)*       |
 | `WHEROBOTS_REGION`                 | Region override (else org default) | *(none — org default)*            |
 | `WHEROBOTS_API_BASE_URL`          | API base URL                    | `https://api.cloud.wherobots.com`    |
 | `WHEROBOTS_VERSION`               | Wherobots version               | `latest`                             |
 | `WHEROBOTS_REQUEST_TIMEOUT_SECONDS`| HTTP request timeout (seconds) | `30`                                 |
 | `WHEROBOTS_CLIENT_CHAIN`           | Upstream client-attribution chain (see below) | *(none)*              |
+| `WHEROBOTS_ID_TOKEN_PATH`          | Workload identity token, set by Wherobots notebooks and jobs | *(none)* |
 
 ### WherobotsConfig
 
@@ -456,7 +465,7 @@ with wherobots.Wherobots() as wb:
 | Failure | Raised as |
 |---|---|
 | Files is not enabled for this drive in this region | `WherobotsFilesNotEnabledError` (`.drive`, `.region`) |
-| The API key was not accepted | `WherobotsNotAuthenticatedError` |
+| The credentials were not accepted | `WherobotsNotAuthenticatedError` |
 | No such file or folder | `WherobotsFileNotFoundError` |
 | Transfer to or from storage failed | `WherobotsS3Error` |
 
@@ -673,7 +682,7 @@ All exceptions inherit from `WherobotsJobError`.
 | `WherobotsS3Error`         | A transfer to or from storage failed, including Files presigned uploads and downloads. |
 | `WherobotsConfigError`     | Configuration is missing or invalid.                 |
 | `WherobotsTimeoutError`    | Job exceeded the specified timeout.                  |
-| `WherobotsNotAuthenticatedError` | Files: the API key was not accepted (HTTP 401). Subclass of `WherobotsAPIError`. |
+| `WherobotsNotAuthenticatedError` | Files: the credentials were not accepted (HTTP 401). In a Wherobots pod: the workload identity token exchange failed. Subclass of `WherobotsAPIError`. |
 | `WherobotsFilesNotEnabledError` | Files is not enabled for a drive in a region. Has `drive`, `region`. Subclass of `WherobotsAPIError`. |
 | `WherobotsFileNotFoundError` | Files: no such file or folder. Subclass of `WherobotsAPIError`. |
 

{wherobots_python_sdk-0.6.0.dist-info → wherobots_python_sdk-0.7.0.dist-info}/RECORD

@@ -1,24 +1,25 @@
 wherobots/__init__.py,sha256=MUFjzOBaVW2lzPw35F5SBlTChJBKl1n0-p16qUnIO9k,2759
-wherobots/__version__.py,sha256=WRvsZqweFyYGBAqr3rBDrYgY5bSG3iA5gCa_nhBsI1U,111
+wherobots/__version__.py,sha256=fIE1uN53hY31LBi8pDljwzsVPIy2DxhD_1aN1rJ34iw,111
 wherobots/client.py,sha256=mFShTtxXfCg9GLVMykM7jC1SvuDCZ_sY9JnHIOlOwxQ,37797
-wherobots/config.py,sha256=d1QePrl7V0ooSlv_Ut0GJ5o0ShMBDH1k9yqgQ1cnxmE,7376
+wherobots/config.py,sha256=53BCZxXathnEjEJqwti07MxTmqNyYNP3b40qmri1blE,7986
 wherobots/enums.py,sha256=T_x0QzDCmrZZTfYuEjkdjT_tbt0DDP5S-Kr5HnC8j2o,5218
-wherobots/exceptions.py,sha256=JnqMghCANt9Ci6IPmYssbysovqvxxfbB1QMV8xJ3uGY,2565
+wherobots/exceptions.py,sha256=lBzjRNtWRGyh0PgnIKAQr4x2liEhFvWoLn-Ndf91nCQ,2558
 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/base.py,sha256=y9rCRBDX5II3gLD1muhjlYtAA_X3IC78w6wqzKke8RY,12479
+wherobots/api/drive.py,sha256=X-HmUN3Z2aw3H56kd0AcfxC_44pZE7Fh5SIC7Q16rQo,18809
+wherobots/api/files.py,sha256=a_OteB6rQRF7PHvIeazAoh7NeAfg7UNq-GheZzSal_k,23498
 wherobots/api/runs.py,sha256=y0yF_h74S4ScebgCxHjT07kBlj8aIHlfYN6iBaBktgs,8654
 wherobots/api/tasks.py,sha256=9knNtwU0Kb2NYkuabaaNkhiOyZjscec-JT8rkZZbIiY,9144
+wherobots/api/workload_auth.py,sha256=zhJXROeYV47HJvEqzGAbd4oaqkuqXQGHZQRCHeDIYuE,4725
 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.7.0.dist-info/licenses/LICENSE,sha256=U1EH466XmvxbqaWOY0cax49w0R87_6w6yJLyV14v4bc,10767
+wherobots_python_sdk-0.7.0.dist-info/METADATA,sha256=eyfrSSkWK3vTgWCla5BSrDusKgW3XJrs4Aw-RfTzWiE,33310
+wherobots_python_sdk-0.7.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+wherobots_python_sdk-0.7.0.dist-info/top_level.txt,sha256=oL-n-9GIG0rmUeukuytUqdN6yfROIsVh8bNrgZsOdxw,10
+wherobots_python_sdk-0.7.0.dist-info/RECORD,,