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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.4.0
+Version: 0.5.1
 Summary: Python SDK for Wherobots (currently covers the Jobs REST API)
 Author-email: Wherobots <support@wherobots.com>
 License-Expression: Apache-2.0
@@ -21,8 +21,8 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: requests>=2.33.0
-Requires-Dist: boto3>=1.34.0
+Requires-Dist: requests>=2.34.2
+Requires-Dist: boto3>=1.43.108
 Dynamic: license-file
 
 # Wherobots Python SDK
@@ -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.1}/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.1}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=45", "wheel"]
+requires = ["setuptools>=83.0.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -25,8 +25,8 @@ classifiers = [
 ]
 keywords = ["wherobots", "spark", "sedona", "geospatial", "jobs", "sdk", "rest-api"]
 dependencies = [
-    "requests>=2.33.0",
-    "boto3>=1.34.0",
+    "requests>=2.34.2",
+    "boto3>=1.43.108",
 ]
 
 [project.urls]
@@ -38,17 +38,17 @@ Documentation = "https://docs.wherobots.com"
 # PEP 735 dev dependencies — installed with `uv sync --group dev`.
 [dependency-groups]
 dev = [
-    "pytest>=8.0",
-    "pytest-cov>=4.1.0",
-    "pytest-mock>=3.11.1",
-    "ruff>=0.15,<0.17",
-    "pyrefly>=0.16",
-    "import-linter>=2.1",
-    "pre-commit>=3.8",
-    "hypothesis>=6.100",
-    "cosmic-ray>=8.4",
-    "ast-grep-cli>=0.39",
-    "types-requests>=2.31",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.16.0",
+    "ruff>=0.16.10,<0.17",
+    "pyrefly>=1.3.2",
+    "import-linter>=2.15",
+    "pre-commit>=4.6.2",
+    "hypothesis>=6.168.4",
+    "cosmic-ray>=8.7.0",
+    "ast-grep-cli>=0.45.3",
+    "types-requests>=2.33.0.20260906",
 ]
 
 [tool.setuptools.packages.find]

{wherobots_python_sdk-0.4.0 → wherobots_python_sdk-0.5.1}/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.1}/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):