nerdstack-ark 1.0.4__tar.gz → 1.0.5__tar.gz

nerdstack_ark-1.0.5/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 1.0.5
+
+### Fixed
+
+- `folders.list()` and `AsyncFolders.list()` returned an empty tuple against
+  every real workspace. `GET /api/v2/folders` returns the array under
+  `folders`, but the SDK read `data` — the key `/api/v2/files` uses. The
+  missing key was silently coerced to an empty list, so callers that resolve a
+  folder by name saw "no such folder", called `create()`, and got back
+  "A folder with this name already exists here". Nesting was unusable for the
+  same reason, since resolving `a/b/c` lists children at each level.
+
+  Both envelopes are now accepted, so an older deployment keeps working.
+
+- A folder-list body the SDK cannot parse now raises `ArkError` with code
+  `INVALID_RESPONSE` instead of being reported as an empty list. The silent
+  empty result is what made the bug above expensive to diagnose: `list()` and
+  `create()` reported opposite things and neither raised.
+
+- `ArkError` now exposes `message`. It was documented and passed to
+  `Exception.__init__`, but never stored, so `error.message` raised
+  `AttributeError` inside callers' own error handlers. `str(error)` was the
+  only thing that worked.
+
+- `ark_py.__version__` read `1.0.0` while the package was on 1.0.4. It is now
+  read from the installed distribution metadata, so it cannot drift again.
+
+### Internal
+
+- Folder parsing moved to `_shared.parse_folder_list`. The identical code was
+  duplicated in the sync and async clients, which is why one bug needed fixing
+  in two places, and why the async client had no folder test at all.

{nerdstack_ark-1.0.4 → nerdstack_ark-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nerdstack-ark
-Version: 1.0.4
+Version: 1.0.5
 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.4 → nerdstack_ark-1.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nerdstack-ark"
-version = "1.0.4"
+version = "1.0.5"
 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.4 → nerdstack_ark-1.0.5}/src/ark_py/__init__.py

@@ -1,5 +1,8 @@
 """Official Python SDK for Ark storage."""
 
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
 from .async_client import AsyncArk
 from .errors import ArkError
 from .models import (
@@ -38,4 +41,10 @@ __all__ = [
     "create_s3_client",
 ]
 
-__version__ = "1.0.0"
+# Read from the installed distribution rather than hard-coded. This said
+# "1.0.0" while pyproject.toml said 1.0.4, so anyone reporting a bug with
+# ark_py.__version__ quoted a version that had not shipped in months.
+try:  # pragma: no cover - depends on install state, not on logic
+    __version__ = _version("nerdstack-ark")
+except PackageNotFoundError:  # running from a source tree, not installed
+    __version__ = "0.0.0.dev0"

{nerdstack_ark-1.0.4 → nerdstack_ark-1.0.5}/src/ark_py/_shared.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from typing import Any, BinaryIO
 from urllib.parse import quote, urlencode
 
-from .errors import invalid_argument
+from .errors import invalid_argument, invalid_response
 from .models import ClientSession, ImageOptions
 
 DEFAULT_BASE_URL = "https://ark.nerdstackgrp.com"
@@ -42,6 +42,34 @@ def image_url(base_url: str, version: str, asset_id: str, options: ImageOptions)
     return api_url(base_url, version, f"/assets/{segment(asset_id)}/image{suffix}")
 
 
+def parse_folder_list(value: Mapping[str, Any]) -> list[Mapping[str, Any]]:
+    """Pull the folder array out of a GET /folders body.
+
+    The two list endpoints do not share an envelope: /files returns
+    ``{"data": [...], "nextCursor": ...}`` while /folders returns
+    ``{"folders": [...], "pagination": {...}}``. The SDK read ``data`` for
+    both, so folders.list() returned nothing against every real workspace --
+    silently, because a missing key was coerced to an empty list.
+
+    Both keys are accepted so an older deployment keeps working, and anything
+    else raises rather than reporting an empty folder list that the caller
+    cannot distinguish from a real one.
+
+    Lives here rather than in each client because the identical parsing was
+    duplicated in sync.py and async_client.py -- which is why one bug needed
+    fixing in two places.
+    """
+    for key in ("folders", "data"):
+        raw = value.get(key)
+        if isinstance(raw, list):
+            return [item for item in raw if isinstance(item, Mapping)]
+
+    raise invalid_response(
+        "The folder list response was not in a recognised format. "
+        f"Expected a 'folders' array, got keys: {sorted(map(str, value.keys())) or 'none'}."
+    )
+
+
 def parse_client_session(value: Mapping[str, Any]) -> ClientSession:
     raw_scopes = value.get("scopes")
     scopes = tuple(str(scope) for scope in raw_scopes) if isinstance(raw_scopes, list) else ()

{nerdstack_ark-1.0.4 → nerdstack_ark-1.0.5}/src/ark_py/async_client.py

@@ -21,6 +21,7 @@ from ._shared import (
     api_url,
     image_url,
     parse_client_session,
+    parse_folder_list,
     query_string,
     read_exact,
     resolve_upload_source,
@@ -381,12 +382,7 @@ 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 [])
-            if isinstance(item, Mapping)
-        )
+        return tuple(ArkFolder.from_dict(item) for item in parse_folder_list(value))
 
     async def create(self, name: str, *, parent_id: str | None = None) -> ArkFolder:
         payload: dict[str, Any] = {"name": name}

{nerdstack_ark-1.0.4 → nerdstack_ark-1.0.5}/src/ark_py/errors.py

@@ -19,6 +19,11 @@ class ArkError(Exception):
     ) -> None:
         super().__init__(message)
         self.code = code
+        # Kept as an attribute, not just handed to Exception. The README
+        # documents `error.message`, and only `str(error)` actually worked --
+        # so every caller following the docs hit an AttributeError inside
+        # their own error handler, which is the worst possible place for one.
+        self.message = message
         self.status = status
         self.request_id = request_id
         self.details = details
@@ -83,5 +88,17 @@ def invalid_argument(message: str) -> ArkError:
     return ArkError("INVALID_ARGUMENT", message)
 
 
+def invalid_response(message: str) -> ArkError:
+    """A 2xx body the SDK could not make sense of.
+
+    Coercing an unrecognised shape to an empty list is what turned a one-line
+    parsing bug into a workflow that could never succeed: `list()` reported no
+    folders, `create()` then refused because the folder was already there, and
+    nothing anywhere raised. Failing loudly here means the next such mismatch
+    is a stack trace pointing at the response, not a silent wrong answer.
+    """
+    return ArkError("INVALID_RESPONSE", message)
+
+
 def _optional_string(value: object) -> str | None:
     return value if isinstance(value, str) else None

{nerdstack_ark-1.0.4 → nerdstack_ark-1.0.5}/src/ark_py/sync.py

@@ -21,6 +21,7 @@ from ._shared import (
     iter_exact,
     iter_file_range,
     parse_client_session,
+    parse_folder_list,
     query_string,
     read_exact,
     resolve_upload_source,
@@ -339,12 +340,7 @@ 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 [])
-            if isinstance(item, Mapping)
-        )
+        return tuple(ArkFolder.from_dict(item) for item in parse_folder_list(value))
 
     def create(self, name: str, *, parent_id: str | None = None) -> ArkFolder:
         payload: dict[str, Any] = {"name": name}

{nerdstack_ark-1.0.4 → nerdstack_ark-1.0.5}/tests/test_async.py

@@ -199,3 +199,68 @@ async def test_async_upload_requires_stream_metadata() -> None:
     with pytest.raises(ArkError, match="filename is required"):
         await ark.files.upload(source(), size=4)
     await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_async_folders_list_reads_the_api_envelope() -> None:
+    """The async client had no folder coverage at all, which is why it carried
+    the same 'data' vs 'folders' bug as the sync client and nothing caught it.
+    """
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response(
+            {
+                "folders": [
+                    {"id": "folder-1", "name": "Media", "parentId": None},
+                    {"id": "folder-2", "name": "Docs", "parentId": "folder-1"},
+                ],
+                "pagination": {"page": 1, "limit": 50, "total": 2, "pages": 1},
+            }
+        )
+
+    client = async_client_for(handler)
+    ark = AsyncArk("token", client=client)
+    folders = await ark.folders.list()
+    assert [folder.name for folder in folders] == ["Media", "Docs"]
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_async_folders_list_still_accepts_a_data_envelope() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"data": [{"id": "f1", "name": "Legacy", "parentId": None}]})
+
+    client = async_client_for(handler)
+    ark = AsyncArk("token", client=client)
+    assert [folder.name for folder in await ark.folders.list()] == ["Legacy"]
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_async_folders_list_rejects_an_unrecognised_body() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"unexpected": []})
+
+    client = async_client_for(handler)
+    ark = AsyncArk("token", client=client)
+    with pytest.raises(ArkError) as caught:
+        await ark.folders.list()
+    assert caught.value.code == "INVALID_RESPONSE"
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_async_folders_list_passes_parent_id_through() -> None:
+    """Nested resolution walks children level by level, so parentId has to
+    reach the query string for anything below the root to be listable."""
+    urls: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        urls.append(str(request.url))
+        return json_response({"folders": [], "pagination": {"total": 0}})
+
+    client = async_client_for(handler)
+    ark = AsyncArk("token", client=client)
+    await ark.folders.list(parent_id="folder-1")
+    assert "parentId=folder-1" in urls[0]
+    await client.aclose()

{nerdstack_ark-1.0.4 → nerdstack_ark-1.0.5}/tests/test_sync.py

@@ -55,7 +55,16 @@ def test_resources_models_images_and_errors() -> None:
         if request.url.path.endswith("/files"):
             return json_response({"data": [file_response(4)], "nextCursor": "next"})
         if request.url.path.endswith("/folders"):
-            return json_response({"data": [{"id": "folder-1", "name": "Media", "parentId": None}]})
+            # The envelope the API actually sends. This mock previously
+            # returned {"data": ...}, matching the SDK's mistaken expectation
+            # rather than the server, so it passed while every real call
+            # returned nothing.
+            return json_response(
+                {
+                    "folders": [{"id": "folder-1", "name": "Media", "parentId": None}],
+                    "pagination": {"page": 1, "limit": 50, "total": 1, "pages": 1},
+                }
+            )
         if request.url.path.endswith("/usage"):
             return json_response(
                 {
@@ -284,3 +293,82 @@ 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_the_shape_the_api_actually_returns() -> None:
+    """GET /v2/folders returns {"folders": [...], "pagination": {...}}.
+
+    The SDK read "data" -- the key /v2/files uses -- so this returned an empty
+    tuple against every real workspace. Nothing raised: the parser's
+    isinstance guard turned the missing key into [], so callers that resolve a
+    folder by name saw "no such folder", called create(), and got back "a
+    folder with this name already exists". That contradiction is what made the
+    bug expensive to diagnose, and it shipped because the test mock returned
+    the same wrong shape the code expected.
+    """
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response(
+            {
+                "folders": [
+                    {"id": "folder-1", "name": "Media", "parentId": None},
+                    {"id": "folder-2", "name": "Docs", "parentId": None},
+                ],
+                "pagination": {"page": 1, "limit": 50, "total": 2, "pages": 1},
+            }
+        )
+
+    client = client_for(handler)
+    ark = Ark("token", client=client)
+    folders = ark.folders.list()
+    assert [folder.name for folder in folders] == ["Media", "Docs"]
+    client.close()
+
+
+def test_folders_list_still_accepts_a_data_envelope() -> None:
+    """A deployment that has not been updated must keep working."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"data": [{"id": "f1", "name": "Legacy", "parentId": None}]})
+
+    client = client_for(handler)
+    ark = Ark("token", client=client)
+    assert [folder.name for folder in ark.folders.list()] == ["Legacy"]
+    client.close()
+
+
+def test_folders_list_rejects_a_body_it_does_not_understand() -> None:
+    """An unrecognised body must not be silently reported as "no folders".
+
+    Returning () for a response the SDK failed to parse is what turned a
+    parsing bug into a workflow that could never succeed.
+    """
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"unexpected": []})
+
+    client = client_for(handler)
+    ark = Ark("token", client=client)
+    with pytest.raises(ArkError) as caught:
+        ark.folders.list()
+    assert caught.value.code == "INVALID_RESPONSE"
+    client.close()
+
+
+def test_folders_list_distinguishes_empty_from_unparseable() -> None:
+    """An genuinely empty folder list is still an empty tuple, not an error."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"folders": [], "pagination": {"total": 0}})
+
+    client = client_for(handler)
+    ark = Ark("token", client=client)
+    assert ark.folders.list() == ()
+    client.close()
+
+
+def test_ark_error_exposes_message() -> None:
+    """The README documents `message`; only `str(error)` actually worked."""
+    error = ArkError("NOT_FOUND", "missing", status=404)
+    assert error.message == "missing"
+    assert str(error) == "missing"