nerdstack-ark 1.0.0__tar.gz → 1.0.1__tar.gz

{nerdstack_ark-1.0.0 → nerdstack_ark-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nerdstack-ark
-Version: 1.0.0
+Version: 1.0.1
 Summary: Official Python SDK for Ark storage, with sync, async, and S3-compatible access.
 Project-URL: Homepage, https://ark.nerdstackgrp.com
 Project-URL: Documentation, https://github.com/joshhumphrey02/ark-sdk/tree/master/packages/ark-py#readme

{nerdstack_ark-1.0.0 → nerdstack_ark-1.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nerdstack-ark"
-version = "1.0.0"
+version = "1.0.1"
 description = "Official Python SDK for Ark storage, with sync, async, and S3-compatible access."
 readme = "README.md"
 requires-python = ">=3.10"

{nerdstack_ark-1.0.0 → nerdstack_ark-1.0.1}/src/ark_py/__init__.py

@@ -28,4 +28,4 @@ __all__ = [
     "create_s3_client",
 ]
 
-__version__ = "1.0.0"
+__version__ = "1.0.1"

{nerdstack_ark-1.0.0 → nerdstack_ark-1.0.1}/src/ark_py/_shared.py

@@ -180,3 +180,42 @@ def sorted_parts(parts: Iterable[dict[str, object]]) -> list[dict[str, object]]:
         return value
 
     return sorted(parts, key=part_number)
+
+
+def folders_payload(value: Mapping[str, Any]) -> list[Any]:
+    """Read a folder list under either key Ark may return it as.
+
+    The public API documents `folders`, and that is the handler that actually
+    serves `/v2/folders`; the developer-API handler for the same path returns
+    `data`. Reading only `data` meant this call silently returned zero folders
+    against a perfectly valid response -- worse than an error, because nothing
+    surfaced. Both keys are accepted so the SDK works whichever answers.
+    """
+    for key in ("folders", "data"):
+        candidate = value.get(key)
+        if isinstance(candidate, list):
+            return candidate
+    return []
+
+
+MAX_REQUEST_ATTEMPTS = 3
+RETRY_BASE_DELAY_SECONDS = 0.5
+
+
+def is_retryable_status(status: int) -> bool:
+    """Only these are worth retrying; auth and validation failures are not."""
+    return status == 429 or status >= 500
+
+
+def retry_delay_seconds(attempt: int) -> float:
+    """Exponential backoff with full jitter.
+
+    Jitter matters: without it every client that failed at the same moment
+    retries at the same moment and re-creates the overload that caused the
+    failure. Mirrors the TypeScript client so both SDKs behave alike under
+    load.
+    """
+    import random
+
+    ceiling = min(RETRY_BASE_DELAY_SECONDS * (2 ** (attempt - 1)), 30.0)
+    return random.random() * ceiling

{nerdstack_ark-1.0.0 → nerdstack_ark-1.0.1}/src/ark_py/async_client.py

@@ -15,7 +15,11 @@ from ._shared import (
     DEFAULT_BASE_URL,
     DEFAULT_CONTENT_TYPE,
     UploadSource,
+    MAX_REQUEST_ATTEMPTS,
     api_url,
+    folders_payload,
+    is_retryable_status,
+    retry_delay_seconds,
     image_url,
     parse_client_session,
     query_string,
@@ -101,15 +105,28 @@ class AsyncArk:
         *,
         json: Mapping[str, Any] | None = None,
     ) -> dict[str, Any]:
-        try:
-            response = await self._client.request(
-                method,
-                self._url(path),
-                headers={"authorization": f"Bearer {self._token}"},
-                json=dict(json) if json is not None else None,
-            )
-        except httpx.HTTPError as error:
-            raise network_error(error) from error
+        # See the sync client: retried with backoff so a transient failure on a
+        # large upload does not surface as an error the caller must retry.
+        response = None
+        for attempt in range(1, MAX_REQUEST_ATTEMPTS + 1):
+            try:
+                response = await self._client.request(
+                    method,
+                    self._url(path),
+                    headers={"authorization": f"Bearer {self._token}"},
+                    json=dict(json) if json is not None else None,
+                )
+            except httpx.HTTPError as error:
+                if attempt == MAX_REQUEST_ATTEMPTS:
+                    raise network_error(error) from error
+                await asyncio.sleep(retry_delay_seconds(attempt))
+                continue
+            if not is_retryable_status(response.status_code):
+                break
+            if attempt == MAX_REQUEST_ATTEMPTS:
+                break
+            await asyncio.sleep(retry_delay_seconds(attempt))
+        assert response is not None
         if response.is_error:
             raise error_from_response(response)
         if response.status_code == 204:
@@ -363,10 +380,9 @@ class AsyncFolders:
             "GET",
             f"/folders{query_string({'parentId': parent_id})}",
         )
-        raw_data = value.get("data")
         return tuple(
             ArkFolder.from_dict(item)
-            for item in (raw_data if isinstance(raw_data, list) else [])
+            for item in folders_payload(value)
             if isinstance(item, Mapping)
         )
 

{nerdstack_ark-1.0.0 → nerdstack_ark-1.0.1}/src/ark_py/sync.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import builtins
+import time
 from collections.abc import Mapping
 from concurrent.futures import FIRST_COMPLETED, Future, ThreadPoolExecutor, wait
 from contextlib import suppress
@@ -14,7 +15,11 @@ from ._shared import (
     DEFAULT_BASE_URL,
     UploadSource,
     api_url,
+    MAX_REQUEST_ATTEMPTS,
     ensure_stream_complete,
+    folders_payload,
+    is_retryable_status,
+    retry_delay_seconds,
     image_url,
     iter_exact,
     iter_file_range,
@@ -100,15 +105,32 @@ class Ark:
         *,
         json: Mapping[str, Any] | None = None,
     ) -> dict[str, Any]:
-        try:
-            response = self._client.request(
-                method,
-                self._url(path),
-                headers={"authorization": f"Bearer {self._token}"},
-                json=dict(json) if json is not None else None,
-            )
-        except httpx.HTTPError as error:
-            raise network_error(error) from error
+        # Retried with backoff, matching the TypeScript client. A transient
+        # network failure on a multi-megabyte upload otherwise surfaced as a
+        # bare NETWORK_ERROR that succeeded on the caller's own retry -- work
+        # every caller had to reimplement.
+        response = None
+        last_error: Exception | None = None
+        for attempt in range(1, MAX_REQUEST_ATTEMPTS + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    self._url(path),
+                    headers={"authorization": f"Bearer {self._token}"},
+                    json=dict(json) if json is not None else None,
+                )
+            except httpx.HTTPError as error:
+                last_error = error
+                if attempt == MAX_REQUEST_ATTEMPTS:
+                    raise network_error(error) from error
+                time.sleep(retry_delay_seconds(attempt))
+                continue
+            if not is_retryable_status(response.status_code):
+                break
+            if attempt == MAX_REQUEST_ATTEMPTS:
+                break
+            time.sleep(retry_delay_seconds(attempt))
+        assert response is not None
         if response.is_error:
             raise error_from_response(response)
         if response.status_code == 204:
@@ -322,10 +344,9 @@ class Folders:
 
     def list(self, *, parent_id: str | None = None) -> tuple[ArkFolder, ...]:
         value = self._ark._request("GET", f"/folders{query_string({'parentId': parent_id})}")
-        raw_data = value.get("data")
         return tuple(
             ArkFolder.from_dict(item)
-            for item in (raw_data if isinstance(raw_data, list) else [])
+            for item in folders_payload(value)
             if isinstance(item, Mapping)
         )
 

{nerdstack_ark-1.0.0 → nerdstack_ark-1.0.1}/tests/test_sync.py

@@ -237,3 +237,96 @@ def test_non_seekable_stream_requires_size_and_filename() -> None:
     with pytest.raises(ArkError, match="filename is required"):
         ark.files.upload(NonSeekable(b"data"), size=4)
     ark._client.close()
+
+
+def test_folders_list_reads_documented_folders_key() -> None:
+    """The shape production returns.
+
+    Reading only `data` made this return an empty tuple against a perfectly
+    valid response -- silently, which is worse than raising: a caller sees an
+    account with no folders rather than an error they can act on.
+    """
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response(
+            {
+                "folders": [
+                    {"id": "f1", "name": "Products", "parentId": None},
+                    {"id": "f2", "name": "Docs", "parentId": None},
+                ],
+                "pagination": {"page": 1, "limit": 50, "total": 2, "pages": 1},
+            }
+        )
+
+    ark = Ark("token", client=client_for(handler))
+    folders = ark.folders.list()
+    assert len(folders) == 2
+    assert folders[0].name == "Products"
+    assert folders[1].id == "f2"
+
+
+def test_folders_list_still_reads_data_key() -> None:
+    """The developer-API handler for the same path. Both must work."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"data": [{"id": "f9", "name": "Only", "parentId": None}]})
+
+    ark = Ark("token", client=client_for(handler))
+    folders = ark.folders.list()
+    assert len(folders) == 1
+    assert folders[0].id == "f9"
+
+
+def test_folders_list_tolerates_an_unexpected_shape() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"unexpected": True})
+
+    ark = Ark("token", client=client_for(handler))
+    assert ark.folders.list() == ()
+
+
+def test_request_retries_a_transient_server_error() -> None:
+    """A 500 is retried; the caller sees the eventual success.
+
+    A transient network failure on a multi-megabyte upload previously surfaced
+    as a bare NETWORK_ERROR that succeeded on the caller's own retry -- work
+    every caller had to reimplement, and which the TypeScript client already
+    did.
+    """
+    attempts = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        attempts["n"] += 1
+        if attempts["n"] < 3:
+            return json_response({"error": {"message": "boom"}}, 500)
+        return json_response(
+            {
+                "storage": {
+                    "usedBytes": 1,
+                    "pendingBytes": 0,
+                    "limitBytes": 2,
+                    "availableBytes": 1,
+                },
+                "tier": "free",
+                "status": "active",
+            }
+        )
+
+    ark = Ark("token", client=client_for(handler))
+    usage = ark.usage()
+    assert attempts["n"] == 3
+    assert usage.storage.used_bytes == 1
+
+
+def test_request_does_not_retry_a_client_error() -> None:
+    """Auth and validation failures are final: retrying them only wastes time."""
+    attempts = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        attempts["n"] += 1
+        return json_response({"error": {"code": "UNAUTHORIZED"}}, 401)
+
+    ark = Ark("token", client=client_for(handler))
+    with pytest.raises(ArkError):
+        ark.usage()
+    assert attempts["n"] == 1