wherobots-python-sdk 0.4.0__tar.gz → 0.5.0__tar.gz

{wherobots_python_sdk-0.4.0 → wherobots_python_sdk-0.5.0}/PKG-INFO

@@ -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.4.0 → wherobots_python_sdk-0.5.0}/README.md

@@ -18,6 +18,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
 
@@ -391,6 +392,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
@@ -558,9 +602,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.4.0 → wherobots_python_sdk-0.5.0}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=45", "wheel"]
+requires = ["setuptools>=83.0.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]

{wherobots_python_sdk-0.4.0 → wherobots_python_sdk-0.5.0}/tests/test_base_client.py

@@ -233,6 +233,108 @@ class TestRequestErrorWrapping:
         assert "Internal Server Error" in str(exc_info.value)
 
 
+# ---------------------------------------------------------------------------
+# Redirect-returning GET
+# ---------------------------------------------------------------------------
+
+
+def _mock_session(MockSession):
+    session = MockSession.return_value
+    session.headers = {}
+    session.mount = MagicMock()
+    return session
+
+
+class TestGetRedirectTarget:
+    @patch("wherobots.api.base.requests.Session")
+    def test_returns_location_of_307_without_following(self, MockSession, config):
+        session = _mock_session(MockSession)
+        response = MagicMock()
+        response.status_code = 307
+        response.headers = {"Location": "https://s3.example.com/obj?sig=1"}
+        response.raise_for_status.return_value = None
+        session.request.return_value = response
+
+        client = BaseClient(config)
+        target = client.get_redirect_target("/storage/x/files/a", params={"q": "1"})
+
+        assert target == "https://s3.example.com/obj?sig=1"
+        call = session.request.call_args
+        assert call.args == ("GET", "https://api.test.wherobots.com/storage/x/files/a")
+        assert call.kwargs["allow_redirects"] is False
+        assert call.kwargs["params"] == {"q": "1"}
+        assert call.kwargs["timeout"] == 30
+
+    @patch("wherobots.api.base.requests.Session")
+    def test_non_redirect_answer_is_api_error(self, MockSession, config):
+        session = _mock_session(MockSession)
+        response = MagicMock()
+        response.status_code = 200
+        response.headers = {"Location": "https://s3.example.com/obj"}
+        response.raise_for_status.return_value = None
+        session.request.return_value = response
+
+        with pytest.raises(WherobotsAPIError, match="Expected a redirect") as exc_info:
+            BaseClient(config).get_redirect_target("/storage/x/files/a")
+        assert exc_info.value.status_code == 200
+
+    @patch("wherobots.api.base.requests.Session")
+    def test_redirect_without_location_is_api_error(self, MockSession, config):
+        session = _mock_session(MockSession)
+        response = MagicMock()
+        response.status_code = 307
+        response.headers = {}
+        response.raise_for_status.return_value = None
+        session.request.return_value = response
+
+        with pytest.raises(WherobotsAPIError, match="Expected a redirect"):
+            BaseClient(config).get_redirect_target("/storage/x/files/a")
+
+    @patch("wherobots.api.base.requests.Session")
+    def test_http_error_mapped_like_request(self, MockSession, config):
+        session = _mock_session(MockSession)
+        response = MagicMock()
+        response.status_code = 404
+        response.headers = {"X-Request-Id": "req-xyz"}
+        response.json.return_value = {"message": "nope"}
+        response.raise_for_status.side_effect = requests.HTTPError(response=response)
+        session.request.return_value = response
+
+        with pytest.raises(WherobotsAPIError) as exc_info:
+            BaseClient(config).get_redirect_target("/storage/x/files/a")
+        err = exc_info.value
+        assert err.status_code == 404
+        assert err.request_id == "req-xyz"
+        assert err.response == {"message": "nope"}
+        assert "nope" in str(err)
+
+    @patch("wherobots.api.base.requests.Session")
+    def test_connection_error_wrapped(self, MockSession, config):
+        session = _mock_session(MockSession)
+        session.request.side_effect = requests.ConnectionError("DNS failed")
+
+        with pytest.raises(WherobotsAPIError, match="Request failed"):
+            BaseClient(config).get_redirect_target("/storage/x/files/a")
+
+    @patch("wherobots.api.base.requests.Session")
+    def test_other_calls_still_refuse_redirects(self, MockSession, config):
+        session = _mock_session(MockSession)
+        session.request.return_value = MagicMock()
+
+        client = BaseClient(config)
+        client.get("/runs")
+        client.post("/runs", json_body={})
+
+        assert session.max_redirects == 0
+        for call in session.request.call_args_list:
+            assert "allow_redirects" not in call.kwargs
+
+    @patch("wherobots.api.base.requests.Session")
+    def test_timeout_property(self, MockSession, config):
+        _mock_session(MockSession)
+        assert BaseClient(config).timeout == 30
+
+
 # ---------------------------------------------------------------------------
 # Convenience wrappers
 # ---------------------------------------------------------------------------

{wherobots_python_sdk-0.4.0 → wherobots_python_sdk-0.5.0}/tests/test_client_header.py

@@ -116,13 +116,13 @@ class TestClientHeaderValue:
 
     def test_multi_hop_upstream_chain_is_preserved_in_order(self):
         value = client_header_value(
-            "client=claude_web, client=mcp;ver=0.9",
+            "client=claude-web, client=mcp;ver=0.9",
             hop="client=python-sdk;ver=0.3.0",
         )
-        assert value == "client=claude_web, client=mcp;ver=0.9, client=python-sdk;ver=0.3.0"
+        assert value == "client=claude-web, client=mcp;ver=0.9, client=python-sdk;ver=0.3.0"
         # Leftmost stays the origin, rightmost is this SDK.
         hops = [hop.strip() for hop in value.split(",")]
-        assert hops[0] == "client=claude_web"
+        assert hops[0] == "client=claude-web"
         assert hops[-1] == "client=python-sdk;ver=0.3.0"
 
     def test_upstream_whitespace_is_normalized(self):