unitlab 3.0.0__tar.gz → 3.0.2__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: unitlab
-Version: 3.0.0
+Version: 3.0.2
 Summary: Python SDK for the Unitlab.ai data annotation platform
 Project-URL: Homepage, https://unitlab.ai
 Project-URL: Documentation, https://docs.unitlab.ai
@@ -214,6 +214,7 @@ project = client.projects.get("PROJECT_ID")
 project = client.projects.create("Road scenes")
 
 batch = project.upload("./data", fps=2.0)
+tiled_batch = project.upload("./maps")
 
 status = batch.status()
 status = batch.wait(timeout=1800)
@@ -228,6 +229,11 @@ status = queue.wait()
 Completion means `processing == 0`; a completed Batch Queue may still report
 individual failures.
 
+GeoTIFF and whole-slide files are detected automatically. Large tiled files
+upload directly to storage in bounded parts. Tiled processing can take hours,
+so use a longer timeout such as `batch.wait(timeout=25200)` when the next
+operation depends on the generated COG/DZI derivative.
+
 ### Data Units and project lifecycle
 
 ```python
@@ -257,12 +263,18 @@ items = folder.list_items()
 result = client.assets.upload("./images", folder_id=folder.id, tags=["train"])
 asset = result.assets[0]
 
+tiled = client.assets.upload(
+    "./slides",
+    folder_id=folder.id,
+)
+tiled.assets[0].wait()
+
 cloud_folder = client.assets.create_cloud_folder(
     "Incoming",
     "CLOUD_STORAGE_ID",
     prefix="incoming/",
 )
-cloud_folder.sync_cloud()
+cloud_folder.sync_cloud()  # Tiled files are registered as processing Assets.
 ```
 
 ### Datasets and published versions
@@ -377,10 +389,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
@@ -394,6 +410,7 @@ unitlab project data-unit PROJECT_ID DATA_UNIT_ID
 unitlab project sources PROJECT_ID
 unitlab project detach-source PROJECT_ID SOURCE_LINK_ID --preview
 unitlab project upload PROJECT_ID --source ./data
+unitlab project upload PROJECT_ID --source ./maps
 unitlab batch-queue list PROJECT_ID
 unitlab batch-queue detail PROJECT_ID BATCH_QUEUE_ID
 unitlab batch-queue status PROJECT_ID BATCH_QUEUE_ID
@@ -408,6 +425,7 @@ unitlab project attach PROJECT_ID --dataset-version DATASET_ID:2
 
 # Assets
 unitlab assets upload ./data --folder "Raw data" --tag incoming
+unitlab assets upload ./slides --folder "Slides"
 
 # Folders
 unitlab folders create "Raw data"
@@ -440,7 +458,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.2}/README.md

@@ -181,6 +181,7 @@ project = client.projects.get("PROJECT_ID")
 project = client.projects.create("Road scenes")
 
 batch = project.upload("./data", fps=2.0)
+tiled_batch = project.upload("./maps")
 
 status = batch.status()
 status = batch.wait(timeout=1800)
@@ -195,6 +196,11 @@ status = queue.wait()
 Completion means `processing == 0`; a completed Batch Queue may still report
 individual failures.
 
+GeoTIFF and whole-slide files are detected automatically. Large tiled files
+upload directly to storage in bounded parts. Tiled processing can take hours,
+so use a longer timeout such as `batch.wait(timeout=25200)` when the next
+operation depends on the generated COG/DZI derivative.
+
 ### Data Units and project lifecycle
 
 ```python
@@ -224,12 +230,18 @@ items = folder.list_items()
 result = client.assets.upload("./images", folder_id=folder.id, tags=["train"])
 asset = result.assets[0]
 
+tiled = client.assets.upload(
+    "./slides",
+    folder_id=folder.id,
+)
+tiled.assets[0].wait()
+
 cloud_folder = client.assets.create_cloud_folder(
     "Incoming",
     "CLOUD_STORAGE_ID",
     prefix="incoming/",
 )
-cloud_folder.sync_cloud()
+cloud_folder.sync_cloud()  # Tiled files are registered as processing Assets.
 ```
 
 ### Datasets and published versions
@@ -344,10 +356,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
@@ -361,6 +377,7 @@ unitlab project data-unit PROJECT_ID DATA_UNIT_ID
 unitlab project sources PROJECT_ID
 unitlab project detach-source PROJECT_ID SOURCE_LINK_ID --preview
 unitlab project upload PROJECT_ID --source ./data
+unitlab project upload PROJECT_ID --source ./maps
 unitlab batch-queue list PROJECT_ID
 unitlab batch-queue detail PROJECT_ID BATCH_QUEUE_ID
 unitlab batch-queue status PROJECT_ID BATCH_QUEUE_ID
@@ -375,6 +392,7 @@ unitlab project attach PROJECT_ID --dataset-version DATASET_ID:2
 
 # Assets
 unitlab assets upload ./data --folder "Raw data" --tag incoming
+unitlab assets upload ./slides --folder "Slides"
 
 # Folders
 unitlab folders create "Raw data"
@@ -407,7 +425,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.2}/pyproject.toml

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

{unitlab-3.0.0 → unitlab-3.0.2}/src/unitlab/__init__.py

@@ -3,6 +3,7 @@ from importlib.metadata import version
 from ._grouping import tiles_from_template
 from .client import UnitlabClient
 from .exceptions import (
+    AmbiguousUploadCompletionError,
     AuthenticationError,
     NetworkError,
     NotFoundError,
@@ -55,6 +56,7 @@ from .types import (
 __version__ = version("unitlab")
 
 __all__ = [
+    "AmbiguousUploadCompletionError",
     "Asset",
     "AssetUploadResult",
     "AttachPreview",

{unitlab-3.0.0 → unitlab-3.0.2}/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)