unitlab 3.0.0__tar.gz → 3.0.1__tar.gz

{unitlab-3.0.0 → unitlab-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitlab
-Version: 3.0.0
+Version: 3.0.1
 Summary: Python SDK for the Unitlab.ai data annotation platform
 Project-URL: Homepage, https://unitlab.ai
 Project-URL: Documentation, https://docs.unitlab.ai
@@ -377,10 +377,14 @@ release = client.releases.create(
 releases = client.releases.list()
 release = client.releases.get(release.id)
 
-annotation_path = release.download(split="train")
+annotation_path = release.download(split="train", dest="./release-annotations")
 files_folder = release.download_files(dest="./release-files")
 ```
 
+Release item download tokens are persistent Unitlab URLs. For files stored in
+customer cloud storage, the URL redirects to a signed target URL; only that target
+URL is temporary.
+
 ## CLI quick reference
 
 ```bash
@@ -440,7 +444,7 @@ unitlab dataset versions DATASET_ID
 unitlab release create PROJECT_ID --format UUEF --splits train=100
 unitlab release list
 unitlab release detail RELEASE_ID
-unitlab release download RELEASE_ID --split-type train
+unitlab release download RELEASE_ID --split-type train --dest ./release-annotations
 
 # Ontologies
 unitlab ontology list

{unitlab-3.0.0 → unitlab-3.0.1}/README.md

@@ -344,10 +344,14 @@ release = client.releases.create(
 releases = client.releases.list()
 release = client.releases.get(release.id)
 
-annotation_path = release.download(split="train")
+annotation_path = release.download(split="train", dest="./release-annotations")
 files_folder = release.download_files(dest="./release-files")
 ```
 
+Release item download tokens are persistent Unitlab URLs. For files stored in
+customer cloud storage, the URL redirects to a signed target URL; only that target
+URL is temporary.
+
 ## CLI quick reference
 
 ```bash
@@ -407,7 +411,7 @@ unitlab dataset versions DATASET_ID
 unitlab release create PROJECT_ID --format UUEF --splits train=100
 unitlab release list
 unitlab release detail RELEASE_ID
-unitlab release download RELEASE_ID --split-type train
+unitlab release download RELEASE_ID --split-type train --dest ./release-annotations
 
 # Ontologies
 unitlab ontology list

{unitlab-3.0.0 → unitlab-3.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "unitlab"
-version = "3.0.0"
+version = "3.0.1"
 description = "Python SDK for the Unitlab.ai data annotation platform"
 readme = "README.md"
 license = "MIT"

{unitlab-3.0.0 → unitlab-3.0.1}/src/unitlab/_downloader.py

@@ -15,32 +15,45 @@ from .exceptions import NetworkError
 DOWNLOAD_CONCURRENCY = 50
 
 
-def download_annotation(api, release_id: str, split: str | None = None) -> str:
+def download_annotation(
+    api,
+    release_id: str,
+    split: str | None = None,
+    dest: str | Path | None = None,
+) -> str:
     payload = {"download_type": "annotation"}
     if split is not None:
         payload["split_type"] = split
-    response = api.post(f"/api/sdk/releases/{release_id}/", json=payload)
+    response = api.post(
+        f"/api/sdk/releases/{release_id}/",
+        json=payload,
+        timeout=600.0,
+    )
     file_url = response["file"]
     filename = os.path.basename(urlparse(file_url).path) or f"{release_id}.zip"
-    partial = f"{filename}.part"
+    destination = Path(dest) if dest is not None else Path()
+    target = destination / filename
+    partial = target.with_name(f"{target.name}.part")
     try:
+        destination.mkdir(parents=True, exist_ok=True)
         with httpx.stream("GET", file_url, timeout=300.0) as stream:
             stream.raise_for_status()
-            with open(partial, "wb") as handle:
+            with partial.open("wb") as handle:
                 for chunk in stream.iter_bytes():
                     handle.write(chunk)
-        os.replace(partial, filename)
+        os.replace(partial, target)
     except (httpx.HTTPError, OSError) as exc:
-        if os.path.exists(partial):
-            os.remove(partial)
+        if partial.exists():
+            partial.unlink()
         raise NetworkError(f"Failed to download release: {exc}", exc) from exc
-    return os.path.abspath(filename)
+    return str(target.resolve())
 
 
 def download_files(api, release_id: str, dest: str | Path | None = None) -> str:
     response = api.post(
         f"/api/sdk/releases/{release_id}/",
         json={"download_type": "files"},
+        timeout=600.0,
     )
     base_folder = str(Path(dest) if dest is not None else Path(release_id))
     os.makedirs(base_folder, exist_ok=True)

{unitlab-3.0.0 → unitlab-3.0.1}/src/unitlab/cli.py

@@ -1210,12 +1210,15 @@ def release_download(
     pk: UUID,
     download_type: DownloadType = typer.Option(DownloadType.annotation),
     split_type: str | None = typer.Option(None),
-    dest: Path | None = typer.Option(None),
+    dest: Path | None = typer.Option(
+        None,
+        help="Destination directory for annotations or source files.",
+    ),
     api_key: API_KEY = None,
 ):
     release = get_client(api_key).releases.get(str(pk))
     result = (
-        release.download(split_type)
+        release.download(split_type, dest=dest)
         if download_type == DownloadType.annotation
         else release.download_files(dest=dest)
     )
@@ -1237,7 +1240,13 @@ def release_create(
     export_type: str = typer.Option("UUEF", "--format"),
     splits: str = typer.Option("train=100"),
     data_type: list[str] | None = typer.Option(None, "--data-type"),
-    include_download_tokens: bool = typer.Option(False),
+    include_download_tokens: bool = typer.Option(
+        False,
+        help=(
+            "Include persistent Unitlab item download tokens; only a "
+            "customer-cloud signed target URL is temporary."
+        ),
+    ),
     license_id: UUID | None = typer.Option(None, "--license"),
     api_key: API_KEY = None,
     json_output: JSON_OUTPUT = False,

{unitlab-3.0.0 → unitlab-3.0.1}/src/unitlab/resources/releases.py

@@ -39,7 +39,9 @@ class ReleasesNamespace(Namespace):
             project: Project handle or ID.
             export_type: Primary annotation export format.
             split_ratios: Percentage assigned to each output split.
-            include_download_tokens: Include temporary download tokens.
+            include_download_tokens: Include persistent Unitlab item download tokens.
+                The Unitlab token URL remains valid; a customer-cloud signed
+                target URL returned by it is temporary.
             upload_sessions: Optional Batch Queue handles or IDs to include.
             data_types: Optional public data types to include. ``multimodal``
                 includes every available concrete type.
@@ -83,6 +85,7 @@ class ReleasesNamespace(Namespace):
         raw = self._api.post(
             f"/api/sdk/projects/{identifier(project)}/releases/",
             json=payload,
+            timeout=600.0,
         )
         return Release._from_raw(self._client, raw)
 
@@ -116,16 +119,27 @@ class Release:
             is_public=bool(raw.get("is_public", False)),
         )
 
-    def download(self, split: str | None = None) -> str:
+    def download(
+        self,
+        split: str | None = None,
+        *,
+        dest: str | Path | None = None,
+    ) -> str:
         """Download annotations for one split or the combined Release.
 
         Args:
             split: Optional split name such as ``train`` or ``test``.
+            dest: Destination directory; defaults to the current directory.
 
         Returns:
             Absolute path to the downloaded archive.
         """
-        return _downloader.download_annotation(self._client._api, self.id, split)
+        return _downloader.download_annotation(
+            self._client._api,
+            self.id,
+            split,
+            dest,
+        )
 
     def download_files(self, dest: str | Path | None = None) -> str:
         """Download the source files represented by this Release.

{unitlab-3.0.0 → unitlab-3.0.1}/tests/test_cli.py

@@ -546,6 +546,41 @@ def test_folder_list_defaults_to_all_and_parent_scopes(monkeypatch):
     assert "folder" not in assets_help.stdout.lower()
 
 
+def test_release_annotation_download_passes_destination(monkeypatch, tmp_path):
+    calls = []
+
+    class Release:
+        @staticmethod
+        def download(split, *, dest):
+            calls.append((split, dest))
+            return str(dest / "release.zip")
+
+    releases = SimpleNamespace(get=lambda _release_id: Release())
+    monkeypatch.setattr(
+        "unitlab.cli.get_client",
+        lambda _api_key: SimpleNamespace(releases=releases),
+    )
+    release_id = "00000000-0000-0000-0000-000000000001"
+    destination = tmp_path / "annotations"
+
+    result = runner.invoke(
+        app,
+        [
+            "release",
+            "download",
+            release_id,
+            "--split-type",
+            "train",
+            "--dest",
+            str(destination),
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert calls == [("train", destination)]
+    assert result.stdout.strip() == str(destination / "release.zip")
+
+
 def test_console_entrypoint_prints_concise_sdk_errors(monkeypatch, capsys):
     def fail():
         raise UnitlabError("Actionable failure")

{unitlab-3.0.0 → unitlab-3.0.1}/tests/test_client.py

@@ -278,14 +278,15 @@ def test_release_detail_parses_and_downloads(monkeypatch):
 
     monkeypatch.setattr(
         "unitlab.resources.releases._downloader.download_annotation",
-        lambda api, release_id, split: f"{release_id}-{split}.zip",
+        lambda api, release_id, split, dest: f"{dest}/{release_id}-{split}.zip",
     )
-    assert release.download("train") == "r1-train.zip"
+    assert release.download("train", dest="exports") == "exports/r1-train.zip"
     client.close()
 
 
 def test_multimodal_release_uses_all_available_types():
     def handler(request):
+        assert set(request.extensions["timeout"].values()) == {600.0}
         payload = json.loads(request.content)
         assert "generic_types" not in payload
         return httpx.Response(

{unitlab-3.0.0 → unitlab-3.0.1}/tests/test_downloader.py

@@ -1,10 +1,11 @@
 import asyncio
+from contextlib import contextmanager
 
 import httpx
 import pytest
 
 from unitlab import NetworkError
-from unitlab._downloader import download_files
+from unitlab._downloader import download_annotation, download_files
 
 
 class BrokenStream(httpx.AsyncByteStream):
@@ -13,13 +14,68 @@ class BrokenStream(httpx.AsyncByteStream):
         raise httpx.ReadError("connection lost")
 
 
+def test_annotation_download_uses_destination_and_long_manifest_timeout(
+    monkeypatch,
+    tmp_path,
+):
+    posts = []
+    streams = []
+    file_url = "https://files.test/release-train.zip?signature=temporary"
+
+    class Api:
+        @staticmethod
+        def post(*args, **kwargs):
+            posts.append((args, kwargs))
+            return {"file": file_url}
+
+    response = httpx.Response(
+        200,
+        content=b"archive",
+        request=httpx.Request("GET", file_url),
+    )
+
+    @contextmanager
+    def stream(*args, **kwargs):
+        streams.append((args, kwargs))
+        yield response
+
+    monkeypatch.setattr(
+        "unitlab._downloader.httpx.stream",
+        stream,
+    )
+    destination = tmp_path / "annotations"
+
+    result = download_annotation(Api(), "release-1", "train", destination)
+
+    final = destination / "release-train.zip"
+    assert result == str(final.resolve())
+    assert final.read_bytes() == b"archive"
+    assert not (destination / "release-train.zip.part").exists()
+    assert streams == [(("GET", file_url), {"timeout": 300.0})]
+    assert posts == [
+        (
+            ("/api/sdk/releases/release-1/",),
+            {
+                "json": {
+                    "download_type": "annotation",
+                    "split_type": "train",
+                },
+                "timeout": 600.0,
+            },
+        )
+    ]
+
+
 def test_failed_download_does_not_leave_a_file_that_next_run_skips(
     monkeypatch,
     tmp_path,
 ):
+    posts = []
+
     class Api:
         @staticmethod
-        def post(*_args, **_kwargs):
+        def post(*args, **kwargs):
+            posts.append((args, kwargs))
             return [
                 {
                     "file_name": "images/scan.png",
@@ -56,6 +112,7 @@ def test_failed_download_does_not_leave_a_file_that_next_run_skips(
 
     download_files(Api(), "release-1", destination)
     assert final.read_bytes() == b"complete"
+    assert all(kwargs["timeout"] == 600.0 for _args, kwargs in posts)
 
 
 def test_download_files_works_inside_a_running_event_loop(monkeypatch, tmp_path):

{unitlab-3.0.0 → unitlab-3.0.1}/tests/test_http.py

@@ -53,17 +53,21 @@ def test_forbidden_responses_distinguish_permission_and_subscription_errors():
     assert exc.value.code == ""
 
 
-def test_commercial_error_code_is_preserved():
+@pytest.mark.parametrize(
+    "code",
+    ["workspace_read_only", "workspace_license_required"],
+)
+def test_commercial_error_code_is_preserved(code):
     response = httpx.Response(
         403,
         request=httpx.Request("POST", "http://testserver/action"),
         json={
             "detail": "Workspace is read-only.",
-            "code": "workspace_read_only",
+            "code": code,
         },
     )
 
     with pytest.raises(SubscriptionError) as exc:
         raise_for_response(response)
 
-    assert exc.value.code == "workspace_read_only"
+    assert exc.value.code == code