unitlab 3.0.2__tar.gz → 3.0.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitlab
-Version: 3.0.2
+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.2 → 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.2 → unitlab-3.0.4}/pyproject.toml

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

{unitlab-3.0.2 → 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.2 → 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.2 → 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
@@ -56,10 +57,12 @@ TILED_EXTENSIONS = (
 EXTENSIONS_BY_GENERIC_TYPE: dict[str, set[str]] = {
     "img": {"jpg", "png", "jpeg", "webp", "gif", "bmp", "ico", "svg"},
     "text": {"txt"},
+    "html": {"html", "htm"},
     "video": {"mp4", "avi", "mov", "webm", "mkv", "m4v", "wmv", "flv"},
     "audio": {"mp3", "wav", "ogg", "aac", "flac", "m4a"},
     "medical": {"dcm", "nii", "nii.gz", "nrrd"},
     "document": {"pdf"},
+    "timeseries": {"csv"},
     "geospatial": AMBIGUOUS_TIFF_EXTENSIONS | GEOSPATIAL_TILED_EXTENSIONS,
     "pathology": PATHOLOGY_TILED_EXTENSIONS,
 }
@@ -196,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:
@@ -270,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(
@@ -277,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,
@@ -288,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)
@@ -396,6 +461,7 @@ async def _finalize_medical_upload(client, endpoint: str, batch_queue_id: str) -
 def _project_files(
     source: str | Path,
     upload_info: dict[str, Any],
+    generic_type: str | None = None,
 ) -> tuple[list[Path], list[UploadFailure]]:
     accepted = {
         str(value).lower().lstrip(".")
@@ -403,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")
@@ -411,9 +477,11 @@ def _project_files(
     result = []
     failures = []
     for path in files:
-        generic_type = detect_generic_type(path.name) or project_type
-        max_size = max_sizes.get(generic_type)
-        if max_size is None and project_type and fallback is not None:
+        file_generic_type = (
+            generic_type or detect_generic_type(path.name) or project_type
+        )
+        max_size = max_sizes.get(file_generic_type)
+        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)
@@ -435,6 +503,8 @@ async def _upload_project_async(
     *,
     session_id: str,
     fps: float,
+    generic_type: str | None,
+    primary_column: str | None,
     batch_size: int,
     show_progress: bool,
 ) -> UploadResult:
@@ -455,11 +525,15 @@ async def _upload_project_async(
                 tasks = []
                 generic_types = []
                 for path in chunk:
-                    generic_type = detect_generic_type(path.name)
-                    generic_types.append(generic_type)
+                    file_generic_type = generic_type or detect_generic_type(path.name)
+                    generic_types.append(file_generic_type)
                     fields = {"session_id": session_id}
-                    if generic_type == "video":
+                    if file_generic_type == "video":
                         fields["fps"] = str(fps)
+                    if generic_type is not None:
+                        fields["generic_type"] = generic_type
+                    if primary_column is not None:
+                        fields["primary_column"] = primary_column
                     tasks.append(
                         _upload_file(
                             client,
@@ -533,13 +607,15 @@ def upload_project(
     source: str | Path,
     *,
     fps: float = 1.0,
+    generic_type: str | None = None,
+    primary_column: str | None = None,
     batch_size: int = 100,
     show_progress: bool = True,
 ) -> tuple[UploadResult, str]:
     if batch_size < 1:
         raise ValueError("batch_size must be at least 1")
     upload_info = api.get(f"/api/sdk/projects/{project_id}/upload-info/")
-    files, preflight_failures = _project_files(source, upload_info)
+    files, preflight_failures = _project_files(source, upload_info, generic_type)
     if not files and not preflight_failures:
         accepted = upload_info.get("accepted_formats") or sorted(known_extensions())
         raise ValueError(
@@ -560,6 +636,8 @@ def upload_project(
             files,
             session_id=session_id,
             fps=fps,
+            generic_type=generic_type,
+            primary_column=primary_column,
             batch_size=batch_size,
             show_progress=show_progress,
         )
@@ -576,6 +654,9 @@ def _asset_form_data(
     path: str | None,
     tags: list[str] | None,
     custom_metadata: dict[str, Any] | None,
+    defer_timeseries_configuration: bool,
+    generic_type: str | None,
+    primary_column: str | None,
 ) -> dict[str, str | list[str]]:
     fields: dict[str, str | list[str]] = {}
     if folder:
@@ -592,6 +673,12 @@ def _asset_form_data(
             ensure_ascii=False,
             separators=(",", ":"),
         )
+    if defer_timeseries_configuration:
+        fields["defer_timeseries_configuration"] = "true"
+    if generic_type is not None:
+        fields["generic_type"] = generic_type
+    if primary_column is not None:
+        fields["primary_column"] = primary_column
     return fields
 
 
@@ -640,6 +727,9 @@ async def _upload_assets_async(
     path: str | None,
     tags: list[str] | None,
     custom_metadata: dict[str, Any] | None,
+    defer_timeseries_configuration: bool,
+    generic_type: str | None,
+    primary_column: str | None,
     show_progress: bool,
 ) -> tuple[UploadResult, str, str]:
     failures: list[UploadFailure] = []
@@ -668,6 +758,9 @@ async def _upload_assets_async(
                         path=path,
                         tags=tags,
                         custom_metadata=custom_metadata,
+                        defer_timeseries_configuration=defer_timeseries_configuration,
+                        generic_type=generic_type,
+                        primary_column=primary_column,
                     ),
                     tiled_endpoint="/api/sdk/data-assets/tiled-uploads",
                     complete_fields=_asset_complete_data(
@@ -708,6 +801,9 @@ async def _upload_assets_async(
                                 path=path,
                                 tags=tags,
                                 custom_metadata=custom_metadata,
+                                defer_timeseries_configuration=defer_timeseries_configuration,
+                                generic_type=generic_type,
+                                primary_column=primary_column,
                             ),
                             tiled_endpoint="/api/sdk/data-assets/tiled-uploads",
                             complete_fields=_asset_complete_data(
@@ -756,6 +852,9 @@ def upload_assets(
     path: str | None = None,
     tags: list[str] | None = None,
     custom_metadata: dict[str, Any] | None = None,
+    defer_timeseries_configuration: bool = False,
+    generic_type: str | None = None,
+    primary_column: str | None = None,
     show_progress: bool = True,
 ) -> tuple[UploadResult, str, str]:
     if folder and folder_id:
@@ -774,6 +873,9 @@ def upload_assets(
             path=path,
             tags=tags,
             custom_metadata=custom_metadata,
+            defer_timeseries_configuration=defer_timeseries_configuration,
+            generic_type=generic_type,
+            primary_column=primary_column,
             show_progress=show_progress,
         )
     )

{unitlab-3.0.2 → 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.2 → 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.2 → unitlab-3.0.4}/src/unitlab/ontology.py

@@ -15,6 +15,8 @@ class Shape(str, Enum):
     CUBOID = "cuboid"
     TIME_RANGE = "time_range"
     TEXT = "text"
+    INTERVAL = "interval"
+    INSTANT = "instant"
 
 
 class OntologyClassificationLevel(str, Enum):

{unitlab-3.0.2 → unitlab-3.0.4}/src/unitlab/resources/assets.py

@@ -26,6 +26,9 @@ class AssetsNamespace(Namespace):
         path: str | None = None,
         tags: list[str] | None = None,
         custom_metadata: dict[str, Any] | None = None,
+        defer_timeseries_configuration: bool = False,
+        generic_type: str | None = None,
+        primary_column: str | None = None,
     ) -> AssetUploadResult:
         """Upload local files into workspace Assets.
 
@@ -36,6 +39,12 @@ class AssetsNamespace(Namespace):
             path: Logical path created below the destination folder.
             tags: Tags applied to uploaded Assets.
             custom_metadata: User-owned JSON metadata applied to every upload.
+            defer_timeseries_configuration: Keep the legacy deferred chart flow
+                when ``generic_type="timeseries"`` is explicitly selected.
+            generic_type: Explicit upload family, such as ``tabular`` for CSV
+                row mode. Omitted CSV Assets remain family-neutral until they
+                are attached to a project.
+            primary_column: Preferred row-mode CSV text column.
 
         Returns:
             Successful Assets and per-file failures without discarding partial
@@ -49,6 +58,9 @@ class AssetsNamespace(Namespace):
             path=path,
             tags=tags,
             custom_metadata=custom_metadata,
+            defer_timeseries_configuration=defer_timeseries_configuration,
+            generic_type=generic_type,
+            primary_column=primary_column,
             show_progress=sys.stderr.isatty(),
         )
         assets = [
@@ -269,9 +281,7 @@ class Asset:
         )
 
     def status(self) -> ProcessingStatus:
-        raw = self._client._api.get(
-            f"/api/sdk/data-assets/assets/{self.id}/tiled-status/"
-        )
+        raw = self._client._api.get(f"/api/sdk/data-assets/assets/{self.id}/status/")
         self.upload_status = str(raw.get("upload_status", self.upload_status))
         return ProcessingStatus._from_raw(raw)
 
@@ -284,7 +294,7 @@ class Asset:
     ) -> ProcessingStatus:
         status = wait_for_status(
             self._client._api,
-            f"/api/sdk/data-assets/assets/{self.id}/tiled-status/",
+            f"/api/sdk/data-assets/assets/{self.id}/status/",
             resource_name=f"Asset {self.id}",
             timeout=timeout,
             on_progress=on_progress,
@@ -302,6 +312,19 @@ class Asset:
         self.upload_status = str(raw.get("status", "processing"))
         return raw
 
+    def configure_timeseries(
+        self,
+        *,
+        x_column: str,
+        channels: list[str],
+    ) -> dict[str, Any]:
+        raw = self._client._api.post(
+            f"/api/sdk/data-assets/assets/{self.id}/timeseries-configuration/",
+            json={"x_column": x_column, "channels": channels},
+        )
+        self.upload_status = str(raw.get("upload_status", self.upload_status))
+        return raw
+
     def update_custom_metadata(
         self,
         custom_metadata: dict[str, Any] | None,

{unitlab-3.0.2 → unitlab-3.0.4}/src/unitlab/resources/projects.py

@@ -256,6 +256,8 @@ class Project:
         source: str | Path,
         *,
         fps: float = 1.0,
+        generic_type: str | None = None,
+        primary_column: str | None = None,
         batch_size: int = 100,
     ) -> UploadBatch:
         """Upload local files into this Project.
@@ -263,17 +265,25 @@ class Project:
         Args:
             source: File or directory to upload.
             fps: Frame rate used for uploaded video.
+            generic_type: Explicit upload family, such as ``tabular`` for CSV
+                row mode. Omitted CSV uploads remain pending until configured
+                in the target project.
+            primary_column: Preferred row-mode CSV text column.
             batch_size: Files scheduled per local upload batch.
 
         Returns:
             Local upload results and the server-side Batch Queue ID. Server
-            processing may still be running.
+            processing may still be running. Declared ``tabular`` uploads are
+            accepted asynchronously and their datasource IDs are returned
+            immediately.
         """
         result, session_id = _uploader.upload_project(
             self._client._api,
             self.id,
             source,
             fps=fps,
+            generic_type=generic_type,
+            primary_column=primary_column,
             batch_size=batch_size,
             show_progress=sys.stderr.isatty(),
         )