unitlab 3.0.3__tar.gz → 3.0.4__tar.gz

{unitlab-3.0.3 → unitlab-3.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitlab
-Version: 3.0.3
+Version: 3.0.4
 Summary: Python SDK for the Unitlab.ai data annotation platform
 Project-URL: Homepage, https://unitlab.ai
 Project-URL: Documentation, https://docs.unitlab.ai
@@ -393,6 +393,18 @@ annotation_path = release.download(split="train", dest="./release-annotations")
 files_folder = release.download_files(dest="./release-files")
 ```
 
+`client.releases.create()` waits until the Release is ready. To return immediately
+and wait later:
+
+```python
+release = client.releases.create(project, wait=False)
+release.wait(timeout=7200)  # Wait before downloading.
+```
+
+Check progress with `release.refresh()`, then read `release.status` and
+`release.progress`. Lists show ready Releases; use `client.releases.get(release_id)`
+to check one still being prepared.
+
 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.
@@ -454,8 +466,9 @@ unitlab dataset unpublished-changes DATASET_ID
 unitlab dataset publish DATASET_ID --title "Initial snapshot"
 unitlab dataset versions DATASET_ID
 
-# Releases
+# Releases (create returns immediately; add --wait to wait until ready)
 unitlab release create PROJECT_ID --format UUEF --splits train=100
+unitlab release wait RELEASE_ID --timeout 7200
 unitlab release list
 unitlab release detail RELEASE_ID
 unitlab release download RELEASE_ID --split-type train --dest ./release-annotations

{unitlab-3.0.3 → unitlab-3.0.4}/README.md

@@ -360,6 +360,18 @@ annotation_path = release.download(split="train", dest="./release-annotations")
 files_folder = release.download_files(dest="./release-files")
 ```
 
+`client.releases.create()` waits until the Release is ready. To return immediately
+and wait later:
+
+```python
+release = client.releases.create(project, wait=False)
+release.wait(timeout=7200)  # Wait before downloading.
+```
+
+Check progress with `release.refresh()`, then read `release.status` and
+`release.progress`. Lists show ready Releases; use `client.releases.get(release_id)`
+to check one still being prepared.
+
 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.
@@ -421,8 +433,9 @@ unitlab dataset unpublished-changes DATASET_ID
 unitlab dataset publish DATASET_ID --title "Initial snapshot"
 unitlab dataset versions DATASET_ID
 
-# Releases
+# Releases (create returns immediately; add --wait to wait until ready)
 unitlab release create PROJECT_ID --format UUEF --splits train=100
+unitlab release wait RELEASE_ID --timeout 7200
 unitlab release list
 unitlab release detail RELEASE_ID
 unitlab release download RELEASE_ID --split-type train --dest ./release-annotations

{unitlab-3.0.3 → unitlab-3.0.4}/pyproject.toml

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

{unitlab-3.0.3 → unitlab-3.0.4}/src/unitlab/__init__.py

@@ -5,6 +5,7 @@ from .client import UnitlabClient
 from .exceptions import (
     AmbiguousUploadCompletionError,
     AuthenticationError,
+    ConflictError,
     NetworkError,
     NotFoundError,
     PermissionDeniedError,
@@ -67,6 +68,7 @@ __all__ = [
     "ChecklistAttribute",
     "CloudEntry",
     "CloudStorage",
+    "ConflictError",
     "DataUnit",
     "Dataset",
     "DatasetItem",

{unitlab-3.0.3 → unitlab-3.0.4}/src/unitlab/_http.py

@@ -7,6 +7,7 @@ import httpx
 
 from .exceptions import (
     AuthenticationError,
+    ConflictError,
     NetworkError,
     NotFoundError,
     PermissionDeniedError,
@@ -65,6 +66,10 @@ def raise_for_response(response: httpx.Response) -> None:
         if code == "permission_denied":
             raise PermissionDeniedError(message or "Forbidden", error, code)
         raise SubscriptionError(message or "Forbidden", error, code)
+    # Must stay above the message-based NotFound fallback below: a 409 detail
+    # can mention "not found" and still has to surface as a conflict.
+    if response.status_code == 409:
+        raise ConflictError(message, error, code)
     if response.status_code == 404 or "not found" in message.lower():
         raise NotFoundError(message, error, code)
     raise NetworkError(message, error, code)

{unitlab-3.0.3 → unitlab-3.0.4}/src/unitlab/_uploader.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import asyncio
 import json
 import uuid
+from collections.abc import Awaitable, Callable
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import suppress
 from pathlib import Path
@@ -198,16 +199,21 @@ async def _put_tiled_part(
     url: str,
     start: int,
     size: int,
+    get_url: Callable[[str | None], Awaitable[str]] | None = None,
 ) -> str:
     last_error: Exception | None = None
+    rejected_url = None
     for attempt in range(TILED_PART_MAX_ATTEMPTS):
         try:
             async with semaphore:
+                if get_url is not None:
+                    url = await get_url(rejected_url)
                 response = await client.put(
                     url,
                     content=_FilePartStream(path, start, size),
                     headers={"Content-Length": str(size)},
                 )
+                rejected_url = url if response.status_code == 403 else None
             response.raise_for_status()
             etag = response.headers.get("etag")
             if not etag:
@@ -272,6 +278,55 @@ async def _upload_tiled_file(
             not part.get("url") for part in part_urls
         ):
             raise ValueError("invalid multipart part URLs")
+        loop = asyncio.get_running_loop()
+        expires_in = float(initiated.get("expires_in", 43200))
+        renew_at = loop.time() + expires_in * 0.75
+        renewal_lock = asyncio.Lock()
+        urls = {int(part["part_number"]): str(part["url"]) for part in part_urls}
+
+        async def get_url(number: int, rejected_url: str | None = None) -> str:
+            nonlocal upload_token, renew_at
+            async with renewal_lock:
+                if loop.time() >= renew_at or (
+                    rejected_url is not None and urls[number] == rejected_url
+                ):
+                    try:
+                        response = await api_client.post(
+                            f"{endpoint}/refresh/",
+                            json={
+                                "upload_token": upload_token,
+                                "part_numbers": list(urls),
+                            },
+                        )
+                        response.raise_for_status()
+                        fresh = _response_json(response)
+                        new_urls = {
+                            int(part["part_number"]): str(part["url"])
+                            for part in fresh["part_urls"]
+                        }
+                        if new_urls.keys() != urls.keys() or not fresh["upload_token"]:
+                            raise ValueError("missing refreshed multipart fields")
+                        urls.update(new_urls)
+                        upload_token = str(fresh["upload_token"])
+                        renew_at = loop.time() + float(fresh["expires_in"]) * 0.75
+                    except (httpx.HTTPError, KeyError, TypeError, ValueError) as exc:
+                        raise NetworkError("Multipart URL renewal failed", exc) from exc
+                return urls[number]
+
+        async def keep_upload_active():
+            # A single slow PUT can outlive the token. Renew independently of
+            # part completion; transient failures retry at the next interval.
+            event = asyncio.Event()
+            while True:
+                try:
+                    await asyncio.wait_for(
+                        event.wait(), timeout=max(1, min(3600, expires_in / 4))
+                    )
+                except asyncio.TimeoutError:
+                    with suppress(NetworkError):
+                        await get_url(1)
+
+        renewal_task = asyncio.create_task(keep_upload_active())
         part_tasks = [
             asyncio.create_task(
                 _put_tiled_part(
@@ -279,6 +334,9 @@ async def _upload_tiled_file(
                     part_semaphore,
                     path,
                     url=str(part["url"]),
+                    get_url=lambda rejected, number=int(part["part_number"]): get_url(
+                        number, rejected
+                    ),
                     start=(int(part["part_number"]) - 1) * part_size,
                     size=min(
                         part_size,
@@ -290,11 +348,16 @@ async def _upload_tiled_file(
         ]
         try:
             parts = await asyncio.gather(*part_tasks)
+            await get_url(1)
         except Exception:
             for task in part_tasks:
                 task.cancel()
             await asyncio.gather(*part_tasks, return_exceptions=True)
             raise
+        finally:
+            renewal_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await renewal_task
     except (KeyError, TypeError, ValueError, NetworkError) as exc:
         if upload_token:
             await _abort_tiled_upload(api_client, endpoint, upload_token)
@@ -406,7 +469,7 @@ def _project_files(
     } or known_extensions()
     files = collect_files(source, accepted)
     max_sizes = {
-        str(key): int(value)
+        str(key): None if value is None else int(value)
         for key, value in (upload_info.get("max_file_sizes") or {}).items()
     }
     project_type = upload_info.get("generic_type")
@@ -418,7 +481,7 @@ def _project_files(
             generic_type or detect_generic_type(path.name) or project_type
         )
         max_size = max_sizes.get(file_generic_type)
-        if max_size is None and project_type and fallback is not None:
+        if file_generic_type not in max_sizes and project_type and fallback is not None:
             max_size = int(fallback)
         if max_size is None or path.stat().st_size <= max_size:
             result.append(path)

{unitlab-3.0.3 → unitlab-3.0.4}/src/unitlab/cli.py

@@ -195,6 +195,7 @@ SUMMARY_FIELDS = (
     "title",
     "file_name",
     "kind",
+    "task_kind",
     "type",
     "version",
     "status",
@@ -1249,6 +1250,17 @@ def release_create(
         ),
     ),
     license_id: UUID | None = typer.Option(None, "--license"),
+    # Unlike the Python API, the CLI does not wait by default: a Release can
+    # take a long time to prepare and a shell command should not hang on it.
+    wait: bool = typer.Option(
+        False,
+        "--wait/--no-wait",
+        help=(
+            "Wait until the Release is ready. Without it the command returns "
+            "the pending Release; follow it with `unitlab release wait`."
+        ),
+    ),
+    timeout: float = typer.Option(7200, help="Seconds to wait with --wait."),
     api_key: API_KEY = None,
     json_output: JSON_OUTPUT = False,
 ):
@@ -1269,10 +1281,23 @@ def release_create(
         data_types=data_type,
         include_download_tokens=include_download_tokens,
         license_id=str(license_id) if license_id else None,
+        wait=wait,
+        timeout=timeout,
     )
     emit(release, json_output)
 
 
+@release_app.command(name="wait", help="Wait until a Release is ready")
+def release_wait(
+    release_id: UUID,
+    timeout: float = typer.Option(7200),
+    api_key: API_KEY = None,
+    json_output: JSON_OUTPUT = False,
+):
+    release = get_client(api_key).releases.get(str(release_id))
+    emit(release.wait(timeout=timeout), json_output)
+
+
 @ontology_app.command(name="list", help="List Ontologies")
 def ontology_list(
     title_eq: str | None = typer.Option(None, "--title-eq"),

{unitlab-3.0.3 → unitlab-3.0.4}/src/unitlab/exceptions.py

@@ -32,6 +32,16 @@ class NotFoundError(NetworkError):
     """Raised when the requested resource is not found."""
 
 
+class ConflictError(NetworkError):
+    """Raised when the API answers 409 because the resource is in a conflicting state.
+
+    Subclasses NetworkError so callers that already catch NetworkError keep
+    working; ``code`` tells the cases apart (``release_in_progress`` for a
+    second create while one is being prepared, ``release_not_ready`` for a
+    download before the Release is ready).
+    """
+
+
 class SubscriptionError(NetworkError):
     """Raised when a subscription error occurs."""
 

{unitlab-3.0.3 → unitlab-3.0.4}/src/unitlab/resources/releases.py

@@ -1,11 +1,14 @@
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from .. import _downloader
-from ..types import _data_type_name
+from .._waiter import wait_for_status
+from ..exceptions import UnitlabError
+from ..types import ProcessingStatus, _data_type_name
 from ._base import Namespace, identifier
 
 if TYPE_CHECKING:
@@ -32,9 +35,20 @@ class ReleasesNamespace(Namespace):
         data_types=None,
         bundle_formats: dict[str, str] | None = None,
         license_id: str | None = None,
+        wait: bool = True,
+        timeout: float = 7200,
     ) -> Release:
         """Create an annotation Release from a Project snapshot.
 
+        The backend prepares a Release in the background and answers at once
+        with a pending one. Waiting is the default so scripts that create and
+        then download keep working unchanged; pass ``wait=False`` to get the
+        pending Release back and call ``release.wait()`` later.
+
+        A second create while one is still being prepared raises
+        ``ConflictError`` (code ``release_in_progress``). It is deliberately not
+        attached to the in-flight Release, whose format or splits may differ.
+
         Args:
             project: Project handle or ID.
             export_type: Primary annotation export format.
@@ -47,9 +61,11 @@ class ReleasesNamespace(Namespace):
                 includes every available concrete type.
             bundle_formats: Per-concrete-data-type formats for multimodal bundles.
             license_id: Optional Dataset license ID.
+            wait: Block until the Release is ready or has failed.
+            timeout: Seconds to wait for preparation when ``wait`` is true.
 
         Returns:
-            The created Release.
+            The created Release; ready when ``wait`` is true.
         """
         payload: dict[str, Any] = {
             "export_type": export_type,
@@ -82,12 +98,15 @@ class ReleasesNamespace(Namespace):
             }
         if license_id is not None:
             payload["license"] = identifier(license_id)
+        # The long request timeout stays: a backend that predates background
+        # preparation still builds the whole Release inside this POST.
         raw = self._api.post(
             f"/api/sdk/projects/{identifier(project)}/releases/",
             json=payload,
             timeout=600.0,
         )
-        return Release._from_raw(self._client, raw)
+        release = Release._from_raw(self._client, raw)
+        return release.wait(timeout=timeout) if wait else release
 
 
 @dataclass
@@ -100,6 +119,11 @@ class Release:
     _client: UnitlabClient = field(repr=False, compare=False)
     data_type: str = ""
     is_public: bool = False
+    # "pending" | "exporting" | "ready" | "failed". None means the backend
+    # predates background preparation, where every returned Release is ready.
+    status: str | None = None
+    progress: int | None = None
+    status_error: str | None = None
 
     @classmethod
     def _from_raw(cls, client: UnitlabClient, raw: dict[str, Any]) -> Release:
@@ -107,13 +131,58 @@ class Release:
             id=str(raw["pk"]),
             name=str(raw.get("name", "")),
             version=str(raw.get("version", "")),
+            # number_of_data is null until the Release has been frozen.
             data_item_count=int(raw.get("number_of_data") or 0),
             raw=raw,
             _client=client,
             data_type=_data_type_name(raw.get("generic_type")),
             is_public=bool(raw.get("is_public", False)),
+            status=raw.get("status"),
+            progress=raw.get("progress"),
+            status_error=raw.get("status_error"),
         )
 
+    def refresh(self) -> Release:
+        """Re-read this Release from the API and update it in place."""
+        # Copying every field keeps handles the caller already holds current,
+        # including data_item_count, which is only known once frozen.
+        vars(self).update(vars(self._client.releases.get(self.id)))
+        return self
+
+    def wait(
+        self,
+        *,
+        timeout: float = 7200,
+        on_progress: Callable[[ProcessingStatus], None] | None = None,
+        show_progress: bool = True,
+    ) -> Release:
+        """Block until this Release is ready.
+
+        Raises:
+            UnitlabError: With code ``release_failed`` when preparation failed.
+            ProcessingTimeoutError: When it is still running after ``timeout``.
+        """
+        # Only poll a Release the backend reported as unfinished: a backend
+        # without background preparation sends no status and has no /status/
+        # route, so polling it would turn a finished Release into a 404.
+        if self.status in ("pending", "exporting"):
+            wait_for_status(
+                self._client._api,
+                f"/api/sdk/releases/{self.id}/status/",
+                resource_name=f"Release {self.id}",
+                timeout=timeout,
+                on_progress=on_progress,
+                show_progress=show_progress,
+            )
+            self.refresh()
+        # wait_for_status returns on failure too, so failure is judged here.
+        if self.status == "failed":
+            raise UnitlabError(
+                f"Release {self.id} failed: {self.status_error or 'unknown error'}",
+                code="release_failed",
+            )
+        return self
+
     def download(
         self,
         split: str | None = None,

{unitlab-3.0.3 → unitlab-3.0.4}/src/unitlab/resources/workflow.py

@@ -162,6 +162,10 @@ class WorkflowTask:
     data_type: str = ""
     available_actions: list[str] = field(default_factory=list)
     move_targets: list[dict[str, Any]] = field(default_factory=list)
+    task_kind: str = "item_state"
+    parent_item_id: str | None = None
+    assignment_id: str | None = None
+    consensus_summary: dict[str, Any] | None = None
 
     @classmethod
     def _from_queue(
@@ -170,8 +174,13 @@ class WorkflowTask:
         project_id: str,
         raw: dict[str, Any],
     ) -> WorkflowTask:
+        consensus_summary = (
+            raw["consensus_summary"]
+            if "consensus_summary" in raw
+            else raw.get("consensus")
+        )
         return cls(
-            id=str(raw["item_id"]),
+            id=str(raw.get("task_id") or raw["item_id"]),
             project_id=project_id,
             stage_id=str(raw.get("stage_id", "")),
             stage_type=str(raw.get("stage_type", "")),
@@ -193,6 +202,14 @@ class WorkflowTask:
                 else None
             ),
             data_type=_data_type_name(raw.get("generic_type")),
+            task_kind=str(raw.get("task_kind") or "item_state"),
+            parent_item_id=(
+                str(raw["parent_item_id"]) if raw.get("parent_item_id") else None
+            ),
+            assignment_id=(
+                str(raw["assignment_id"]) if raw.get("assignment_id") else None
+            ),
+            consensus_summary=consensus_summary,
         )
 
     @classmethod
@@ -206,8 +223,15 @@ class WorkflowTask:
         task = raw.get("task", raw)
         queue = raw.get("queue") or {}
         current_stage = task.get("current_stage") or {}
+        # Consensus task details retain the parent resource; the queue identifies
+        # the private branch. Explicit null also matters when an assignee is cleared.
+        datasource_id = queue.get("datasource_id", task.get("datasource_id"))
+        assigned_to_id = queue.get("assigned_to_id", task.get("assigned_to_id"))
+        consensus_summary = raw.get("consensus_summary")
+        if consensus_summary is None:
+            consensus_summary = task.get("consensus_summary")
         return cls(
-            id=str(task["uuid"]),
+            id=str(task.get("task_id") or task["uuid"]),
             project_id=str(task.get("project_id") or project_id),
             stage_id=str(current_stage.get("id", "")),
             stage_type=str(current_stage.get("type", "")),
@@ -217,12 +241,8 @@ class WorkflowTask:
             raw=raw,
             _client=client,
             name=str(queue.get("name", "")),
-            assigned_to_id=(
-                str(task["assigned_to_id"]) if task.get("assigned_to_id") else None
-            ),
-            datasource_id=(
-                str(task["datasource_id"]) if task.get("datasource_id") else None
-            ),
+            assigned_to_id=str(assigned_to_id) if assigned_to_id else None,
+            datasource_id=str(datasource_id) if datasource_id else None,
             data_group_id=(
                 str(task.get("project_data_group_id") or task.get("data_group_id"))
                 if task.get("project_data_group_id") or task.get("data_group_id")
@@ -233,6 +253,14 @@ class WorkflowTask:
                 str(value) for value in raw.get("available_actions", [])
             ],
             move_targets=list(raw.get("move_targets", [])),
+            task_kind=str(task.get("task_kind") or "item_state"),
+            parent_item_id=(
+                str(task["parent_item_id"]) if task.get("parent_item_id") else None
+            ),
+            assignment_id=(
+                str(task["assignment_id"]) if task.get("assignment_id") else None
+            ),
+            consensus_summary=consensus_summary,
         )
 
     @classmethod
@@ -272,6 +300,44 @@ class WorkflowTask:
             )
         )
 
+    def get_consensus_comparison(self) -> dict[str, Any]:
+        return self._client._api.get(
+            f"/api/sdk/workflow-tasks/{self.id}/consensus-comparison/"
+        )
+
+    def copy_consensus_component(
+        self,
+        *,
+        source_assignment_id: str,
+        component_kind: str,
+        component_locator: dict[str, Any],
+        operation: str = "add",
+        panel_id: str | None = None,
+        replacement_locator: dict[str, Any] | None = None,
+    ) -> WorkflowTask:
+        if operation not in {"add", "replace"}:
+            raise ValueError("operation must be 'add' or 'replace'")
+
+        payload: dict[str, Any] = {
+            "source_assignment_id": source_assignment_id,
+            "component_kind": component_kind,
+            "component_locator": component_locator,
+            "operation": operation,
+            "idempotency_key": str(uuid4()),
+        }
+        if panel_id is not None:
+            payload["panel_id"] = panel_id
+        if replacement_locator is not None:
+            payload["replacement_locator"] = replacement_locator
+        if self.stage_id:
+            payload["expected_stage_id"] = self.stage_id
+        return self._replace(
+            self._client._api.post(
+                f"/api/sdk/workflow-tasks/{self.id}/consensus-selections/",
+                json=payload,
+            )
+        )
+
     def _perform(
         self,
         action: str,
@@ -315,6 +381,36 @@ class WorkflowTask:
     def skip(self) -> WorkflowTask:
         return self._perform("skip")
 
+    def complete_model_run(
+        self,
+        run_id: str,
+        result: dict[str, Any] | list[dict[str, Any]],
+        *,
+        model_version: str = "",
+    ) -> WorkflowTask:
+        """Upload one or more final GeoJSON results for a Model-stage run."""
+        result_key = "results" if isinstance(result, list) else "result"
+        return self._replace(
+            self._client._api.post(
+                f"/api/sdk/workflow-tasks/{self.id}/model-result/",
+                json={
+                    "run_id": str(run_id),
+                    "status": "complete",
+                    result_key: result,
+                    "model_version": model_version,
+                },
+            )
+        )
+
+    def fail_model_run(self, run_id: str, error: str) -> WorkflowTask:
+        """Report a failed asynchronous Model-stage run without advancing it."""
+        return self._replace(
+            self._client._api.post(
+                f"/api/sdk/workflow-tasks/{self.id}/model-result/",
+                json={"run_id": str(run_id), "status": "failed", "error": error},
+            )
+        )
+
     def move(self, destination_stage, *, reason: str = "") -> WorkflowTask:
         """Move this task directly, bypassing normal Workflow edges.