wherobots-python-sdk 0.4.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.4.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

@@ -32,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:
@@ -110,6 +111,11 @@ class BaseClient:
             }
         )
 
+    @property
+    def timeout(self) -> int:
+        """Per-request timeout in seconds, from ``WherobotsConfig``."""
+        return self._timeout
+
     # --------------------------------------------------------------------- #
     # Auth
     # --------------------------------------------------------------------- #
@@ -163,33 +169,84 @@ class BaseClient:
             response.raise_for_status()
             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:

wherobots/api/drive.py

@@ -0,0 +1,481 @@
+"""Files drives — the caller's file areas, over presigned URLs (ADR-0002).
+
+``Files`` hands out one ``FilesDrive`` per (drive, region). Every drive
+operation is written once on ``FilesDrive``; the only drive-specific code is
+``_storage_id``, which maps a drive and region to the API's storage id.
+
+Bytes never pass through the Wherobots API and never carry the API key:
+uploads PUT to a presigned URL, and downloads read the 307 target without
+following it, then GET that URL with a plain request. No STS credentials are
+ever requested.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import secrets
+from pathlib import Path
+from typing import TYPE_CHECKING
+from urllib.parse import quote
+
+import requests
+
+from wherobots.enums import Drive, Region
+from wherobots.exceptions import (
+    WherobotsAPIError,
+    WherobotsConfigError,
+    WherobotsFileNotFoundError,
+    WherobotsFilesNotEnabledError,
+    WherobotsNotAuthenticatedError,
+    WherobotsS3Error,
+    WherobotsValidationError,
+)
+from wherobots.models import DirectoryPage, FileEntry, FileUploadTarget
+from wherobots.utils.logger import get_logger
+
+if TYPE_CHECKING:
+    from wherobots.api.base import BaseClient
+
+logger = get_logger("api.drive")
+
+# The server accepts 1..1000; 0 (its default) disables cursor paging.
+_LIST_PAGE_LIMIT = 1000
+# The root probe after a 404 only needs to know the drive answers, as in the CLI and TS SDK.
+_PROBE_LIMIT = 1
+_MIB = 1024 * 1024
+# S3 refuses a single PUT above 5 GiB, and uploads here are one PUT each: a ceiling we cannot pass.
+_S3_SINGLE_PUT_MAX_BYTES = 5 * 1024**3
+# Product decision, not a protocol limit: one per-file cap across the CLI, Studio web UI and SDK.
+_FILES_UPLOAD_CAP_BYTES = 500 * _MIB
+_DOWNLOAD_CHUNK_BYTES = 1024 * 1024
+_PARTIAL_MODE = 0o666  # before umask, as open() uses; a download keeps the user's usual mode
+_HTTP_UNAUTHORIZED = 401
+_HTTP_NOT_FOUND = 404
+_HTTP_OK = 200
+_HTTP_MULTIPLE_CHOICES = 300
+
+
+def _storage_id(drive: Drive, region: str) -> str:
+    """Resolve a drive in a region to the API's storage id.
+
+    The one place a new drive type changes, besides ``Drive`` itself.
+    """
+    if drive is Drive.MY_FILES:
+        return f"user_files::{region}"
+    raise WherobotsValidationError(f"Unsupported drive: {drive!r}")
+
+
+def _region_name(region: Region | str | None) -> str | None:
+    """Return the region's public name, or ``None`` when none is given."""
+    if isinstance(region, Region):
+        return region.value
+    if region is None or not region.strip():
+        return None
+    return region.strip()
+
+
+def _segments(path: str, *, directory: bool) -> list[str]:
+    """Split a drive path into its segments, refusing unsafe ones.
+
+    Leading ``/`` are dropped. A directory path may end in one ``/``. Empty
+    levels, ``.`` and ``..`` are refused before any request is sent.
+    """
+    relative = path.lstrip("/")
+    if directory:
+        relative = relative.removesuffix("/")
+    if not relative:
+        return []
+    segments = relative.split("/")
+    if "" in segments:
+        raise WherobotsValidationError(f"Path must not contain an empty level: {path!r}")
+    if any(segment in {".", ".."} for segment in segments):
+        raise WherobotsValidationError(f"Path must not contain '.' or '..' segments: {path!r}")
+    return segments
+
+
+def _encode(segments: list[str]) -> str:
+    """Percent-encode each segment on its own and join with ``/`` (never ``%2F``)."""
+    return "/".join(quote(segment, safe="") for segment in segments)
+
+
+def _json_object(response: requests.Response) -> dict[str, object]:
+    """Parse a JSON object body, or raise ``WherobotsAPIError``."""
+    try:
+        data = response.json()
+    except ValueError as exc:
+        raise WherobotsAPIError(
+            "Files API returned a non-JSON body", status_code=response.status_code
+        ) from exc
+    if not isinstance(data, dict):
+        raise WherobotsAPIError(
+            "Files API returned an unexpected body", status_code=response.status_code
+        )
+    return data
+
+
+class FilesDrive:
+    """One Files drive in one region: list, create folders, transfer, rename, delete.
+
+    Obtain one from ``Files.drive`` or ``Files.my_files``; do not build it directly.
+
+    Args:
+        client: The shared API connection.
+        drive: Which drive this is.
+        region: The region's public name (e.g. ``"aws-us-west-2"``).
+    """
+
+    def __init__(self, client: BaseClient, drive: Drive, region: str) -> None:
+        """Bind the drive to a connection and region; see the class docstring."""
+        self._client = client
+        self._drive = drive
+        self._region = region
+        self._storage_id = _storage_id(drive, region)
+        self._timeout = client.timeout
+
+    def __repr__(self) -> str:
+        """Return a short description naming the drive and region."""
+        return f"FilesDrive(drive={self._drive.value!r}, region={self._region!r})"
+
+    @property
+    def drive(self) -> Drive:
+        """The drive this object addresses."""
+        return self._drive
+
+    @property
+    def region(self) -> str:
+        """The region this drive lives in."""
+        return self._region
+
+    @property
+    def storage_id(self) -> str:
+        """The API storage id this drive resolves to."""
+        return self._storage_id
+
+    # ------------------------------------------------------------------ #
+    # Operations
+    # ------------------------------------------------------------------ #
+
+    def list_directory(self, path: str = "") -> list[FileEntry]:
+        """List a folder, following the cursor through every page.
+
+        Args:
+            path: Folder path inside the drive; ``""`` (the default) is the root.
+
+        Returns:
+            Every file and folder directly inside ``path``.
+        """
+        route_segments = _segments(path, directory=True)
+        route = self._route("directories", route_segments)
+        entries: list[FileEntry] = []
+        cursor: str | None = None
+        seen: set[str] = set()
+        while True:
+            params: dict[str, str | int] = {"limit": _LIST_PAGE_LIMIT}
+            if cursor is not None:
+                params["cursor"] = cursor
+            response = self._call("GET", route, params=params, root_listing=not route_segments)
+            page = DirectoryPage.from_dict(_json_object(response))
+            entries.extend(page.entries)
+            # Any cursor seen before means the server is cycling; stop rather than loop forever.
+            if page.next_cursor is None or page.next_cursor in seen:
+                return entries
+            seen.add(page.next_cursor)
+            cursor = page.next_cursor
+
+    def make_directory(self, path: str) -> None:
+        """Create a folder and every missing folder above it, one level at a time.
+
+        Each level is created explicitly so it is a real folder that stays
+        writable from a notebook. If a level fails, the ones above it stay.
+
+        Args:
+            path: Folder path inside the drive, e.g. ``"a/b/c"``.
+        """
+        segments = self._required(path, directory=True)
+        for depth in range(1, len(segments) + 1):
+            self._call("PUT", self._route("directories", segments[:depth]))
+
+    def upload_file(self, local_path: str | os.PathLike[str], path: str) -> str:
+        """Upload one local file to ``path`` in the drive.
+
+        Args:
+            local_path: The file to send.
+            path: Destination file path inside the drive, e.g. ``"data/a.csv"``.
+
+        Returns:
+            The storage location the file was written to.
+
+        Raises:
+            WherobotsValidationError: If the local file is missing or over 500 MiB,
+                or ``path`` is not a valid file path.
+            WherobotsS3Error: If the transfer to storage fails, storage answers
+                other than 2xx (redirects are not followed), or the file cannot be read.
+        """
+        source = Path(local_path)
+        if not source.is_file():
+            raise WherobotsValidationError(f"Not a file: {source}")
+        size = source.stat().st_size
+        limit = min(_FILES_UPLOAD_CAP_BYTES, _S3_SINGLE_PUT_MAX_BYTES)
+        if size > limit:
+            # Round up to 0.1 MiB so a file just over the limit never reads as equal to it.
+            size_mib = math.ceil(size * 10 / _MIB) / 10
+            raise WherobotsValidationError(
+                f"{source} is {size_mib:.1f} MiB; Files uploads are limited to "
+                f"{limit // _MIB} MiB per file"
+            )
+        segments = self._required(path, directory=False)
+        response = self._call("POST", self._route("file-upload-url", segments))
+        try:
+            target = FileUploadTarget.from_dict(_json_object(response))
+        except ValueError as exc:
+            raise WherobotsAPIError(str(exc), status_code=response.status_code) from exc
+        if not target.upload_url.startswith("https://"):
+            raise WherobotsS3Error("Refusing an upload URL that is not https://")
+        logger.debug("Uploading %s to %s", source, target.destination)
+        try:
+            with source.open("rb") as body:
+                upload = requests.put(
+                    target.upload_url, data=body, timeout=self._timeout, allow_redirects=False
+                )
+        # RequestException subclasses OSError, so this one clause also covers local read failures.
+        except OSError as exc:
+            raise WherobotsS3Error(f"Upload of {source} failed: {type(exc).__name__}") from exc
+        if not _HTTP_OK <= upload.status_code < _HTTP_MULTIPLE_CHOICES:
+            raise WherobotsS3Error(
+                f"Upload of {source} failed: storage answered {upload.status_code}"
+            )
+        return target.destination
+
+    def download_file(self, path: str, local_path: str | os.PathLike[str]) -> Path:
+        """Download one file from the drive.
+
+        Args:
+            path: File path inside the drive.
+            local_path: Where to write it. An existing folder receives the file
+                under its drive name.
+
+        Returns:
+            The local file written.
+
+        Raises:
+            WherobotsValidationError: If the folder ``local_path`` names does not exist.
+            WherobotsFileNotFoundError: If the drive has no file at ``path``.
+            WherobotsS3Error: If the transfer from storage or the local write fails.
+        """
+        segments = self._required(path, directory=False)
+        destination = Path(local_path)
+        if destination.is_dir():
+            destination /= segments[-1]
+        if not destination.parent.is_dir():
+            raise WherobotsValidationError(f"Not a folder: {destination.parent}")
+        route = self._route("files", segments)
+        try:
+            url = self._client.get_redirect_target(route)
+        except WherobotsAPIError as err:
+            raise self._translate(err) from err
+        if not url.startswith("https://"):
+            raise WherobotsS3Error("Refusing a download URL that is not https://")
+        self._fetch(url, path, destination)
+        return destination
+
+    def rename_file(self, path: str, new_name: str) -> None:
+        """Rename a file in place.
+
+        Args:
+            path: Current file path inside the drive.
+            new_name: The new name — one path segment, not a path.
+        """
+        if not new_name or "/" in new_name or new_name in {".", ".."}:
+            raise WherobotsValidationError(
+                f"New name must be a single path segment without '/': {new_name!r}"
+            )
+        segments = self._required(path, directory=False)
+        self._call("POST", self._route("file-rename", segments), params={"new_name": new_name})
+
+    def delete_file(self, path: str) -> None:
+        """Delete exactly one file.
+
+        Args:
+            path: File path inside the drive.
+        """
+        self._call("DELETE", self._route("files", self._required(path, directory=False)))
+
+    def delete_directory(self, path: str) -> None:
+        """Delete a folder and everything in it.
+
+        Args:
+            path: Folder path inside the drive (not the root).
+        """
+        self._call("DELETE", self._route("directories", self._required(path, directory=True)))
+
+    # ------------------------------------------------------------------ #
+    # Helpers
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _required(path: str, *, directory: bool) -> list[str]:
+        """Segments of a path that must name something below the root."""
+        segments = _segments(path, directory=directory)
+        if not segments:
+            raise WherobotsValidationError("Path must name a file or folder inside the drive")
+        return segments
+
+    def _route(self, kind: str, segments: list[str]) -> str:
+        """Build ``/storage/{storage_id}/{kind}/{path}`` with every part encoded."""
+        storage = quote(self._storage_id, safe="")
+        return f"/storage/{storage}/{kind}/{_encode(segments)}"
+
+    def _call(
+        self,
+        method: str,
+        route: str,
+        params: dict[str, str | int] | None = None,
+        *,
+        root_listing: bool = False,
+    ) -> requests.Response:
+        """Send one API request, translating Files-specific failures."""
+        try:
+            return self._client.request(method, route, params=params)
+        except WherobotsAPIError as err:
+            raise self._translate(err, root_listing=root_listing) from err
+
+    def _translate(
+        self, err: WherobotsAPIError, *, root_listing: bool = False
+    ) -> WherobotsAPIError:
+        """Map 401 and the two kinds of 404 onto their own errors.
+
+        A 404 is "not enabled" when the drive root is missing too: known already
+        for a root listing, otherwise asked with one ``_root_missing`` probe.
+        """
+        if err.status_code == _HTTP_UNAUTHORIZED:
+            return WherobotsNotAuthenticatedError(
+                "The Wherobots API key was not accepted (HTTP 401)",
+                status_code=err.status_code,
+                response=err.response,
+                request_id=err.request_id,
+            )
+        if err.status_code == _HTTP_NOT_FOUND:
+            if root_listing or self._root_missing():
+                return WherobotsFilesNotEnabledError(self._drive.value, self._region, err)
+            return WherobotsFileNotFoundError(
+                f"No such file or folder in {self._drive.value!r}: {err}",
+                status_code=err.status_code,
+                response=err.response,
+                request_id=err.request_id,
+            )
+        return err
+
+    def _root_missing(self) -> bool:
+        """List the drive root once; only a 404 counts as missing.
+
+        Calls the client directly, never ``_call``, so the probe's own 404 cannot probe again.
+        """
+        route = self._route("directories", [])
+        try:
+            self._client.request("GET", route, params={"limit": _PROBE_LIMIT})
+        except WherobotsAPIError as err:
+            return err.status_code == _HTTP_NOT_FOUND
+        return False
+
+    def _check_download(self, response: requests.Response, path: str) -> None:
+        """Raise unless storage answered the presigned GET with success."""
+        if response.status_code == _HTTP_NOT_FOUND:
+            raise WherobotsFileNotFoundError(
+                f"No such file in {self._drive.value!r}: {path}",
+                status_code=response.status_code,
+            )
+        if not _HTTP_OK <= response.status_code < _HTTP_MULTIPLE_CHOICES:
+            raise WherobotsS3Error(
+                f"Download of {path} failed: storage answered {response.status_code}"
+            )
+
+    def _fetch(self, url: str, path: str, destination: Path) -> None:
+        """Stream a presigned URL to ``destination`` via a fresh temporary ``.part`` file.
+
+        A plain request: no session, so no Wherobots headers reach storage.
+        Only the temporary file this call created is ever removed.
+        """
+        partial: Path | None = None
+        try:
+            with requests.get(
+                url, stream=True, timeout=self._timeout, allow_redirects=False
+            ) as response:
+                self._check_download(response, path)
+                partial, fd = _create_partial(destination)
+                with os.fdopen(fd, "wb") as out:
+                    for chunk in response.iter_content(chunk_size=_DOWNLOAD_CHUNK_BYTES):
+                        out.write(chunk)
+                partial.replace(destination)
+        # RequestException subclasses OSError, so this also covers local write failures.
+        except OSError as exc:
+            _discard(partial)
+            raise WherobotsS3Error(f"Download of {path} failed: {type(exc).__name__}") from exc
+        except BaseException:
+            _discard(partial)
+            raise
+
+
+def _create_partial(destination: Path) -> tuple[Path, int]:
+    """Create a fresh ``.part`` file beside ``destination``; return its path and open fd.
+
+    Mode 0o666 is filtered by the umask, so the renamed file gets the user's usual permissions.
+    """
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
+    while True:
+        candidate = destination.parent / f".{destination.name}.{secrets.token_hex(8)}.part"
+        try:
+            fd = os.open(candidate, flags, _PARTIAL_MODE)
+        except FileExistsError:
+            continue
+        return candidate, fd
+
+
+def _discard(partial: Path | None) -> None:
+    """Remove a temporary file this download created, if it created one."""
+    if partial is not None:
+        partial.unlink(missing_ok=True)
+
+
+class Files:
+    """The Files surface: hands out drives, defaulting to the configured region.
+
+    Args:
+        client: The shared API connection.
+        region: Default region for drives; ``None`` requires one per ``drive`` call.
+    """
+
+    def __init__(self, client: BaseClient, region: Region | str | None = None) -> None:
+        """Bind to a connection and default region; see the class docstring."""
+        self._client = client
+        self._region = _region_name(region)
+        self._drives: dict[tuple[Drive, str], FilesDrive] = {}
+
+    def drive(self, drive: Drive, region: Region | str | None = None) -> FilesDrive:
+        """Return the drive object for ``drive`` in ``region``.
+
+        Args:
+            drive: Which drive, e.g. ``Drive.MY_FILES``.
+            region: Region override; defaults to the configured region.
+
+        Returns:
+            The same ``FilesDrive`` for the same drive and region on every call.
+
+        Raises:
+            WherobotsConfigError: If no region is passed or configured.
+        """
+        resolved = _region_name(region) or self._region
+        if resolved is None:
+            raise WherobotsConfigError(
+                "Files needs a region: set WHEROBOTS_REGION or pass region= "
+                "(e.g. region='aws-us-west-2')."
+            )
+        key = (drive, resolved)
+        if key not in self._drives:
+            self._drives[key] = FilesDrive(self._client, drive, resolved)
+        return self._drives[key]
+
+    @property
+    def my_files(self) -> FilesDrive:
+        """Your personal file area in the default region (``Drive.MY_FILES``)."""
+        return self.drive(Drive.MY_FILES)

wherobots/enums.py

@@ -138,3 +138,13 @@ class AppStatus(Enum):
     DESTROYING = "DESTROYING"
     DESTROY_FAILED = "DESTROY_FAILED"
     DESTROYED = "DESTROYED"
+
+
+class Drive(Enum):
+    """Files drives a caller can address through ``Wherobots().files``.
+
+    ``MY_FILES`` is the caller's personal file area in one region. A shared
+    drive would be a new member here plus one branch in the drive resolver.
+    """
+
+    MY_FILES = "my_files"

wherobots/exceptions.py

@@ -45,3 +45,37 @@ class WherobotsConfigError(WherobotsJobError):
 
 class WherobotsTimeoutError(WherobotsJobError):
     """Raised when a job exceeds the specified timeout."""
+
+
+class WherobotsNotAuthenticatedError(WherobotsAPIError):
+    """Raised when the Wherobots API does not accept the API key (HTTP 401)."""
+
+
+class WherobotsFileNotFoundError(WherobotsAPIError):
+    """Raised when a Files drive has no file or folder at the requested path."""
+
+
+class WherobotsFilesNotEnabledError(WherobotsAPIError):
+    """Raised when Files is not enabled for a drive in a region.
+
+    Attributes:
+        drive: The drive that was addressed (e.g. ``"my_files"``).
+        region: The region the drive was addressed in (e.g. ``"aws-us-west-2"``).
+    """
+
+    def __init__(self, drive: str, region: str, cause: WherobotsAPIError) -> None:
+        """Build the error from an API 404 on a drive whose root also answers 404.
+
+        Args:
+            drive: The drive that was addressed.
+            region: The region the drive was addressed in.
+            cause: The underlying 404 from the API.
+        """
+        self.drive = drive
+        self.region = region
+        super().__init__(
+            f"Files is not enabled for drive {drive!r} in region {region!r}",
+            status_code=cause.status_code,
+            response=cause.response,
+            request_id=cause.request_id,
+        )

wherobots/models.py

@@ -1351,3 +1351,133 @@ class TemporaryAwsCredentials:
             expiration=expiration,
             region=data["region"],
         )
+
+
+# ---------------------------------------------------------------------------
+# Files drive models
+# ---------------------------------------------------------------------------
+
+
+def _optional_str(data: dict[str, object], key: str) -> str | None:
+    """Return ``data[key]`` when it is a non-empty string, else ``None``."""
+    value = data.get(key)
+    return value if isinstance(value, str) and value else None
+
+
+def _parse_timestamp(value: object) -> datetime | None:
+    """Parse an ISO-8601 timestamp (trailing ``Z`` accepted); ``None`` if absent or bad."""
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=timezone.utc)
+
+
+@dataclass(frozen=True)
+class FileEntry:
+    """One file or folder in a Files drive listing.
+
+    Attributes:
+        name: The entry's own name, without a trailing ``/``.
+        path: The entry's path as the API reports it.
+        is_dir: ``True`` for a folder.
+        size: Size in bytes (``0`` for folders).
+        last_modified: Last modification time, when the API reports one.
+    """
+
+    name: str
+    path: str
+    is_dir: bool
+    size: int = 0
+    last_modified: datetime | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> FileEntry:
+        """Deserialize one ``FileEntry`` from the API's listing JSON.
+
+        Args:
+            data: One item of ``DirectoryListingResult.items``.
+
+        Returns:
+            A new ``FileEntry``.
+        """
+        entry_type = data.get("type")
+        is_dir = isinstance(entry_type, str) and entry_type.upper() == "FOLDER"
+        size = data.get("size")
+        name = _optional_str(data, "name") or ""
+        return cls(
+            name=name.rstrip("/") if is_dir else name,
+            path=_optional_str(data, "path") or "",
+            is_dir=is_dir,
+            size=size if isinstance(size, int) and not isinstance(size, bool) else 0,
+            last_modified=_parse_timestamp(data.get("lastModified")),
+        )
+
+
+@dataclass(frozen=True)
+class DirectoryPage:
+    """One page of a Files drive listing.
+
+    Attributes:
+        entries: The files and folders on this page.
+        next_cursor: Cursor for the next page, or ``None`` on the last page.
+    """
+
+    entries: list[FileEntry] = field(default_factory=list)
+    next_cursor: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> DirectoryPage:
+        """Deserialize a ``DirectoryListingResult`` page.
+
+        Args:
+            data: The listing response body (``items`` + snake_case ``next_page``).
+
+        Returns:
+            A new ``DirectoryPage``.
+        """
+        items = data.get("items")
+        entries = (
+            [FileEntry.from_dict(item) for item in items if isinstance(item, dict)]
+            if isinstance(items, list)
+            else []
+        )
+        return cls(entries=entries, next_cursor=_optional_str(data, "next_page"))
+
+
+@dataclass(frozen=True, repr=False)
+class FileUploadTarget:
+    """Where a Files upload lands, and the presigned URL to send it to.
+
+    Attributes:
+        destination: The storage location the file will be written to.
+        upload_url: Presigned PUT URL. It is a bearer credential, so ``repr`` hides it.
+    """
+
+    destination: str
+    upload_url: str
+
+    def __repr__(self) -> str:
+        """Return a representation that never shows the presigned URL."""
+        return f"FileUploadTarget(destination={self.destination!r}, upload_url='***')"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> FileUploadTarget:
+        """Deserialize the ``createFileUploadUrl`` response.
+
+        Args:
+            data: Response body with ``destination`` and ``uploadUrl``.
+
+        Returns:
+            A new ``FileUploadTarget``.
+
+        Raises:
+            ValueError: If either field is missing or empty.
+        """
+        destination = _optional_str(data, "destination")
+        upload_url = _optional_str(data, "uploadUrl")
+        if destination is None or upload_url is None:
+            raise ValueError("Upload URL response is missing 'destination' or 'uploadUrl'")
+        return cls(destination=destination, upload_url=upload_url)

wherobots/sdk.py

@@ -0,0 +1,91 @@
+"""``Wherobots`` — the SDK's top-level client (ADR-0002).
+
+One object, one API connection, one config::
+
+    import wherobots
+
+    with wherobots.Wherobots() as wb:
+        wb.files.my_files.list_directory()
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import TYPE_CHECKING, final
+
+from wherobots.api.base import BaseClient
+from wherobots.api.drive import Files
+from wherobots.config import WherobotsConfig
+from wherobots.enums import Region
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+
+@final
+class Wherobots:
+    """Top-level Wherobots client.
+
+    Built from ``WherobotsConfig`` (or the environment), it owns one API
+    connection shared by every surface it exposes. Close it, or use it as a
+    context manager, to release that connection.
+
+    Args:
+        config: Configuration to use; ``None`` reads it from the environment.
+        api_key: Overrides the configured API key.
+        region: Overrides the configured region (a ``Region`` or its name).
+    """
+
+    def __init__(
+        self,
+        config: WherobotsConfig | None = None,
+        *,
+        api_key: str | None = None,
+        region: Region | str | None = None,
+    ) -> None:
+        """Build the client; see the class docstring."""
+        region_name = region.value if isinstance(region, Region) else region
+        if config is None:
+            config = WherobotsConfig.from_env(api_key=api_key, region=region_name)
+        elif api_key or region_name:
+            config = dataclasses.replace(
+                config,
+                api_key=api_key or config.api_key,
+                region=region_name or config.region,
+            )
+        self._config = config
+        self._client = BaseClient(config)
+        self._files: Files | None = None
+
+    def __repr__(self) -> str:
+        """Return a representation whose config masks the API key."""
+        return f"Wherobots(config={self._config!r})"
+
+    @property
+    def config(self) -> WherobotsConfig:
+        """The configuration this client was built from."""
+        return self._config
+
+    @property
+    def files(self) -> Files:
+        """The Files surface (``wb.files.my_files``, ``wb.files.drive(...)``)."""
+        if self._files is None:
+            self._files = Files(self._client, self._config.region)
+        return self._files
+
+    def close(self) -> None:
+        """Close the API connection."""
+        self._client.close()
+
+    def __enter__(self) -> Wherobots:
+        """Enter the runtime context (context-manager protocol)."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Exit the runtime context, closing the API connection."""
+        self.close()

{wherobots_python_sdk-0.4.0.dist-info → wherobots_python_sdk-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.4.0
+Version: 0.5.0
 Summary: Python SDK for Wherobots (currently covers the Jobs REST API)
 Author-email: Wherobots <support@wherobots.com>
 License-Expression: Apache-2.0
@@ -45,6 +45,7 @@ Additional Wherobots surfaces will be added over time.
 - List runs with status, name, and date filters
 - Typed dataclass models for all API responses (no pydantic dependency)
 - Environment-based configuration
+- Files: list, create folders, upload, download, rename and delete in your Wherobots file area
 
 ## Installation
 
@@ -418,6 +419,49 @@ job = WherobotsJob(
 )
 ```
 
+## Files
+
+`Files` is your Wherobots file area ("My Files" in Studio) from Python. Start from a
+`Wherobots` client; it reads `WHEROBOTS_API_KEY` and `WHEROBOTS_REGION`, or takes `api_key=` /
+`region=` overrides, and closes its connection as a context manager.
+
+```python
+import wherobots
+from wherobots import Drive, Region
+
+with wherobots.Wherobots() as wb:
+    drive = wb.files.my_files  # same object as wb.files.drive(Drive.MY_FILES)
+    eu = wb.files.drive(Drive.MY_FILES, region=Region.EU_WEST_1)  # another region
+
+    drive.make_directory("projects/2026/q3")  # creates projects, then projects/2026, then .../q3
+    drive.upload_file("report.csv", "projects/2026/q3/report.csv")
+    for entry in drive.list_directory("projects/2026/q3"):  # "" lists the root
+        print(entry.name, entry.is_dir, entry.size, entry.last_modified)
+    drive.download_file("projects/2026/q3/report.csv", "local-copy.csv")
+    drive.rename_file("projects/2026/q3/report.csv", "final.csv")
+    drive.delete_file("projects/2026/q3/final.csv")
+    drive.delete_directory("projects")
+```
+
+- Each path segment is encoded on its own; empty levels, `.` and `..` are refused before any
+  request.
+- Uploads and downloads go straight to storage through short-lived presigned URLs. The API key
+  is never sent to storage, and no storage credentials are requested.
+- Uploads are capped at 500 MiB per file, matching the CLI and the Studio web UI; a larger file
+  is refused before any request is sent.
+- Listing follows the server's pages until the end and returns every entry.
+- A region is required: with none passed or configured, `wb.files.my_files` raises
+  `WherobotsConfigError`.
+
+| Failure | Raised as |
+|---|---|
+| Files is not enabled for this drive in this region | `WherobotsFilesNotEnabledError` (`.drive`, `.region`) |
+| The API key was not accepted | `WherobotsNotAuthenticatedError` |
+| No such file or folder | `WherobotsFileNotFoundError` |
+| Transfer to or from storage failed | `WherobotsS3Error` |
+
+The three `Wherobots*Error` classes above subclass `WherobotsAPIError`.
+
 ## Enums
 
 ### JobStatus
@@ -585,9 +629,12 @@ All exceptions inherit from `WherobotsJobError`.
 | `WherobotsJobError`        | Base exception for all SDK errors.                   |
 | `WherobotsAPIError`        | API returned an error response. Has `status_code`, `response`, `request_id` attributes. |
 | `WherobotsValidationError` | Client-side validation failed (e.g., invalid name).  |
-| `WherobotsS3Error`         | S3 upload or access operation failed. Deprecated — presigned uploads raise `WherobotsAPIError` instead. |
+| `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`. |
+| `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`. |
 
 ```python
 from wherobots import WherobotsAPIError, WherobotsJobError

wherobots_python_sdk-0.5.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+wherobots/__init__.py,sha256=851lY2cWlkalilGZ2pvjCBOJIRdixrXRkHOuIkgRMTw,2330
+wherobots/__version__.py,sha256=Jb0N0VuH9FWKfWZpo_RdVUCfOylgV7rwlsHL5uwLslo,111
+wherobots/client.py,sha256=mFShTtxXfCg9GLVMykM7jC1SvuDCZ_sY9JnHIOlOwxQ,37797
+wherobots/config.py,sha256=d1QePrl7V0ooSlv_Ut0GJ5o0ShMBDH1k9yqgQ1cnxmE,7376
+wherobots/enums.py,sha256=0Wdw50bwWrZbslL6eb6pV8ebzWNPV6ouBjVX6PizbsY,4435
+wherobots/exceptions.py,sha256=JnqMghCANt9Ci6IPmYssbysovqvxxfbB1QMV8xJ3uGY,2565
+wherobots/models.py,sha256=iUeSxARQFlKGz8xtkweordFMsPwMavPGsLmSrEwIqbE,50926
+wherobots/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wherobots/sdk.py,sha256=Cvp2a1I_Wvvk5Bp_qsawGfOqQ3DiMcS6JKhyrHtM6ds,2804
+wherobots/api/__init__.py,sha256=KbpcEzKbQ0Z35_hwHsm63Zmn7hfqSApDcRb8u5Y-Af0,291
+wherobots/api/base.py,sha256=EeMq2ESZ50oTf5Wpv50cqC6ljPlXXScg3SU8xfWMero,11471
+wherobots/api/drive.py,sha256=qdhOgL8d34noxE0SwEbqpI3Ql6u53pgLU0cePRwHEmM,19281
+wherobots/api/files.py,sha256=_v89I8tJ_ANnxaTZd4AxtxrkZfZc0BDbL2jpmPBwvWw,23294
+wherobots/api/runs.py,sha256=y0yF_h74S4ScebgCxHjT07kBlj8aIHlfYN6iBaBktgs,8654
+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.5.0.dist-info/licenses/LICENSE,sha256=U1EH466XmvxbqaWOY0cax49w0R87_6w6yJLyV14v4bc,10767
+wherobots_python_sdk-0.5.0.dist-info/METADATA,sha256=CWI2ckQPnC8dvVleWq2yVHClzodf7rImM1ELiay7KTk,30682
+wherobots_python_sdk-0.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+wherobots_python_sdk-0.5.0.dist-info/top_level.txt,sha256=oL-n-9GIG0rmUeukuytUqdN6yfROIsVh8bNrgZsOdxw,10
+wherobots_python_sdk-0.5.0.dist-info/RECORD,,

wherobots_python_sdk-0.4.0.dist-info/RECORD

@@ -1,21 +0,0 @@
-wherobots/__init__.py,sha256=TENVmuGg882ujMs7zj4bSKYHF3SOPXOfiqwLQEPggXE,1917
-wherobots/__version__.py,sha256=k6ZfWdXQCuI__hhJ5rdjMmRn4JkT3w2Isev99qNJH5M,111
-wherobots/client.py,sha256=mFShTtxXfCg9GLVMykM7jC1SvuDCZ_sY9JnHIOlOwxQ,37797
-wherobots/config.py,sha256=d1QePrl7V0ooSlv_Ut0GJ5o0ShMBDH1k9yqgQ1cnxmE,7376
-wherobots/enums.py,sha256=YsxXN3ZcY99aoEsUtjYs4otHDevsSPizAgCp-vShds8,4154
-wherobots/exceptions.py,sha256=pwof-CAvDwXnQpSz6YiTptjNHvtWgBe1PproBbaz0lw,1348
-wherobots/models.py,sha256=aZmEO1Kg0LPZf-F52hW13qmMArwQ3PhEODNgVlAXam8,46573
-wherobots/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-wherobots/api/__init__.py,sha256=jUb587jazP_FA-sH_6yCYfvGxsNiUOyIYAPb3CHOYtQ,218
-wherobots/api/base.py,sha256=-VZ7LkrjlpMdtFfG3Y6IM3dEdg0sYkjZviza7mboInM,9438
-wherobots/api/files.py,sha256=_v89I8tJ_ANnxaTZd4AxtxrkZfZc0BDbL2jpmPBwvWw,23294
-wherobots/api/runs.py,sha256=y0yF_h74S4ScebgCxHjT07kBlj8aIHlfYN6iBaBktgs,8654
-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.4.0.dist-info/licenses/LICENSE,sha256=U1EH466XmvxbqaWOY0cax49w0R87_6w6yJLyV14v4bc,10767
-wherobots_python_sdk-0.4.0.dist-info/METADATA,sha256=u3yXE1-I_-iD9tyXok-z4c06ebgxLqv8_OJchNDxj5E,28176
-wherobots_python_sdk-0.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-wherobots_python_sdk-0.4.0.dist-info/top_level.txt,sha256=oL-n-9GIG0rmUeukuytUqdN6yfROIsVh8bNrgZsOdxw,10
-wherobots_python_sdk-0.4.0.dist-info/RECORD,,