unitlab 3.0.5__tar.gz → 3.1.0__tar.gz

{unitlab-3.0.5 → unitlab-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitlab
-Version: 3.0.5
+Version: 3.1.0
 Summary: Python SDK for the Unitlab.ai data annotation platform
 Project-URL: Homepage, https://unitlab.ai
 Project-URL: Documentation, https://docs.unitlab.ai
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.10
-Requires-Dist: httpx>=0.27
+Requires-Dist: httpx[socks]>=0.27
 Requires-Dist: tqdm>=4.60
 Requires-Dist: typer>=0.9
 Provides-Extra: dev
@@ -416,6 +416,72 @@ batch = project.import_cloud(
 status = batch.wait()
 ```
 
+### Import annotation JSON
+
+Media can come from S3 while the annotation JSON stays on your computer:
+
+```python
+project = client.projects.get("PROJECT_ID")
+media = project.import_cloud("CLOUD_STORAGE_ID", ["images/"])
+status = media.wait()
+if status.failed:
+    raise RuntimeError("Some media failed processing; inspect the Batch Queue.")
+
+batch = project.annotation_imports.create(
+    "./predictions.json",
+    source_name="my-model",  # Reuse this namespace for the same prediction source.
+)
+print(batch.preview["counts"], batch.preview["issues"])
+# Inspect the preview before saving labels. Approval is a separate review step.
+report = batch.commit()
+print(report)
+```
+
+Supported inputs are COCO JSON, Unitlab exports (UUEF item JSON, Audio JSON and
+GeoJSON, as `.json` or `.geojson`), `unitlab-image/1` and `unitlab-video/1`. They
+cover image, video, medical, document, audio, time series, text, HTML, geospatial
+and pathology items. A UUEF file holds one item: import each file as its own batch.
+Each JSON file is limited to 600 MiB. The backend matches original media paths/IDs,
+with a unique-filename fallback; ambiguous names require an explicit mapping.
+YOLO text/ZIP files and other tools' project files are not accepted by this importer.
+
+For COCO video, pass `frame_mapping_file="./frames.json"` in
+`unitlab-frame-map/1` format. Use `track_profile="attributes.track_id"` only for
+COCO exports with that explicit track-ID convention. Import video media at its
+original frame rate; annotations for frames omitted by sampling are rejected.
+
+`project.annotation_imports.sources()` lists saved prediction sources, and
+`project.annotation_imports.media(search="road.jpg")` finds media IDs for mappings.
+Pass `source_id=` instead of `source_name=` to reuse a source by ID. Set
+`options={"stable_ids": True}` only when your exporter keeps annotation IDs stable
+between prediction runs. Otherwise the default protects existing objects from
+unconfirmed ID reuse.
+
+After processing completes or you supply mappings, call `batch.refresh()` to
+rebuild the preview. `batch.refresh(options={...})` replaces all import options;
+omitting `options` preserves them. Supported options are `stable_ids`,
+`media_mapping`, `class_mapping`, `object_mapping`, and `review_mapping`.
+
+`batch.commit()` preserves conflicts and human deletions by default. To resolve
+a specific preview annotation, pass `decisions={annotation_key: "keep"}` (or
+`"incoming"` / `"skip"`). Invalid records prevent the whole commit unless you
+explicitly choose `allow_partial=True`. The report includes created, updated,
+kept, unchanged and skipped counts when applicable. A stale preview raises
+`ConflictError`; inspect a refreshed preview before committing again. If a
+commit response is lost, repeat the same batch's `commit()` with the same
+decisions; the server returns the saved report without duplicating labels.
+
+For annotations already in connected storage, omit the local file and pass
+`cloud_storage=storage`, `annotation_key="labels/predictions.json"`, and optionally
+`frame_mapping_key="labels/frames.json"`. Keys are relative to that connection's
+prefix. Media and annotations must resolve within the API key's workspace and
+the selected project.
+
+This requires a backend with the `/api/sdk/projects/{id}/annotation-imports/`
+routes and the annotation-import database migration installed. Commit requires
+a user-created API key so saved labels have an audit author. Legacy keys without
+a creator can preview but receive `PermissionDeniedError` when committing.
+
 ### Data Groups
 
 Let Unitlab suggest a filename pattern:

{unitlab-3.0.5 → unitlab-3.1.0}/README.md

@@ -383,6 +383,72 @@ batch = project.import_cloud(
 status = batch.wait()
 ```
 
+### Import annotation JSON
+
+Media can come from S3 while the annotation JSON stays on your computer:
+
+```python
+project = client.projects.get("PROJECT_ID")
+media = project.import_cloud("CLOUD_STORAGE_ID", ["images/"])
+status = media.wait()
+if status.failed:
+    raise RuntimeError("Some media failed processing; inspect the Batch Queue.")
+
+batch = project.annotation_imports.create(
+    "./predictions.json",
+    source_name="my-model",  # Reuse this namespace for the same prediction source.
+)
+print(batch.preview["counts"], batch.preview["issues"])
+# Inspect the preview before saving labels. Approval is a separate review step.
+report = batch.commit()
+print(report)
+```
+
+Supported inputs are COCO JSON, Unitlab exports (UUEF item JSON, Audio JSON and
+GeoJSON, as `.json` or `.geojson`), `unitlab-image/1` and `unitlab-video/1`. They
+cover image, video, medical, document, audio, time series, text, HTML, geospatial
+and pathology items. A UUEF file holds one item: import each file as its own batch.
+Each JSON file is limited to 600 MiB. The backend matches original media paths/IDs,
+with a unique-filename fallback; ambiguous names require an explicit mapping.
+YOLO text/ZIP files and other tools' project files are not accepted by this importer.
+
+For COCO video, pass `frame_mapping_file="./frames.json"` in
+`unitlab-frame-map/1` format. Use `track_profile="attributes.track_id"` only for
+COCO exports with that explicit track-ID convention. Import video media at its
+original frame rate; annotations for frames omitted by sampling are rejected.
+
+`project.annotation_imports.sources()` lists saved prediction sources, and
+`project.annotation_imports.media(search="road.jpg")` finds media IDs for mappings.
+Pass `source_id=` instead of `source_name=` to reuse a source by ID. Set
+`options={"stable_ids": True}` only when your exporter keeps annotation IDs stable
+between prediction runs. Otherwise the default protects existing objects from
+unconfirmed ID reuse.
+
+After processing completes or you supply mappings, call `batch.refresh()` to
+rebuild the preview. `batch.refresh(options={...})` replaces all import options;
+omitting `options` preserves them. Supported options are `stable_ids`,
+`media_mapping`, `class_mapping`, `object_mapping`, and `review_mapping`.
+
+`batch.commit()` preserves conflicts and human deletions by default. To resolve
+a specific preview annotation, pass `decisions={annotation_key: "keep"}` (or
+`"incoming"` / `"skip"`). Invalid records prevent the whole commit unless you
+explicitly choose `allow_partial=True`. The report includes created, updated,
+kept, unchanged and skipped counts when applicable. A stale preview raises
+`ConflictError`; inspect a refreshed preview before committing again. If a
+commit response is lost, repeat the same batch's `commit()` with the same
+decisions; the server returns the saved report without duplicating labels.
+
+For annotations already in connected storage, omit the local file and pass
+`cloud_storage=storage`, `annotation_key="labels/predictions.json"`, and optionally
+`frame_mapping_key="labels/frames.json"`. Keys are relative to that connection's
+prefix. Media and annotations must resolve within the API key's workspace and
+the selected project.
+
+This requires a backend with the `/api/sdk/projects/{id}/annotation-imports/`
+routes and the annotation-import database migration installed. Commit requires
+a user-created API key so saved labels have an audit author. Legacy keys without
+a creator can preview but receive `PermissionDeniedError` when committing.
+
 ### Data Groups
 
 Let Unitlab suggest a filename pattern:

{unitlab-3.0.5 → unitlab-3.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "unitlab"
-version = "3.0.5"
+version = "3.1.0"
 description = "Python SDK for the Unitlab.ai data annotation platform"
 readme = "README.md"
 license = "MIT"
@@ -23,7 +23,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
 dependencies = [
-    "httpx>=0.27",
+    "httpx[socks]>=0.27",
     "tqdm>=4.60",
     "typer>=0.9",
 ]

{unitlab-3.0.5 → unitlab-3.1.0}/src/unitlab/__init__.py

@@ -27,6 +27,7 @@ from .ontology import (
     TextAttribute,
 )
 from .resources import (
+    AnnotationImport,
     Asset,
     AttachedSource,
     BatchQueue,
@@ -59,6 +60,7 @@ __version__ = version("unitlab")
 
 __all__ = [
     "AmbiguousUploadCompletionError",
+    "AnnotationImport",
     "Asset",
     "AssetUploadResult",
     "AttachPreview",

{unitlab-3.0.5 → unitlab-3.1.0}/src/unitlab/_http.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import time
 from typing import Any
 
 import httpx
@@ -16,6 +17,11 @@ from .exceptions import (
     ValidationError,
 )
 
+# Match HTTPTransport(retries=3): one initial attempt, then three retries for
+# connection failures only. Leave transport construction to HTTPX so that its
+# standard HTTP_PROXY/HTTPS_PROXY/ALL_PROXY and NO_PROXY handling stays active.
+_CONNECT_RETRY_DELAYS = (0.0, 0.5, 1.0)
+
 
 def _extract_error_message(response: httpx.Response) -> str:
     try:
@@ -90,7 +96,6 @@ class HttpApi:
         self.client = httpx.Client(
             base_url=api_url,
             headers={"Authorization": f"Api-Key {api_key}"},
-            transport=httpx.HTTPTransport(retries=3),
             timeout=60.0,
         )
 
@@ -124,7 +129,14 @@ class HttpApi:
             }
             if timeout is not None:
                 kwargs["timeout"] = timeout
-            response = self.client.request(method, endpoint, **kwargs)
+            for attempt in range(len(_CONNECT_RETRY_DELAYS) + 1):
+                try:
+                    response = self.client.request(method, endpoint, **kwargs)
+                    break
+                except (httpx.ConnectError, httpx.ConnectTimeout):
+                    if attempt == len(_CONNECT_RETRY_DELAYS):
+                        raise
+                    time.sleep(_CONNECT_RETRY_DELAYS[attempt])
         except httpx.TimeoutException as exc:
             raise RequestTimeoutError(str(exc), exc) from exc
         except httpx.HTTPError as exc:

{unitlab-3.0.5 → unitlab-3.1.0}/src/unitlab/resources/__init__.py

@@ -1,3 +1,4 @@
+from .annotation_imports import AnnotationImport
 from .assets import Asset, Folder, GroupingResult
 from .cloud import CloudStorage
 from .datasets import Dataset, DatasetItem, DatasetVersion
@@ -8,6 +9,7 @@ from .releases import Release
 from .workflow import Workflow, WorkflowStage, WorkflowTask
 
 __all__ = [
+    "AnnotationImport",
     "Asset",
     "AttachedSource",
     "BatchQueue",

unitlab-3.1.0/src/unitlab/resources/annotation_imports.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import json
+from contextlib import ExitStack
+from copy import deepcopy
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from ._base import Namespace, identifier
+
+if TYPE_CHECKING:
+    from unitlab.client import UnitlabClient
+
+MAX_FILE_BYTES = 600 * 1024 * 1024
+
+
+class AnnotationImports(Namespace):
+    """Preview and commit labels for media already linked to a Project."""
+
+    def __init__(self, client: UnitlabClient, project_id: str):
+        super().__init__(client)
+        self.project_id = project_id
+
+    @property
+    def _endpoint(self) -> str:
+        return f"/api/sdk/projects/{self.project_id}/annotation-imports/"
+
+    def sources(self) -> list[dict[str, Any]]:
+        return self._api.get(f"{self._endpoint}sources/")["sources"]
+
+    def media(self, search: str = "") -> list[dict[str, Any]]:
+        """Find up to 50 candidates for explicit media mappings."""
+        return self._api.get(f"{self._endpoint}media/", params={"search": search})[
+            "media"
+        ]
+
+    def create(
+        self,
+        annotation_file: str | Path | None = None,
+        *,
+        source_name: str | None = None,
+        source_id: str | None = None,
+        frame_mapping_file: str | Path | None = None,
+        cloud_storage=None,
+        annotation_key: str | None = None,
+        frame_mapping_key: str | None = None,
+        track_profile: Literal["none", "attributes.track_id"] = "none",
+        options: dict[str, Any] | None = None,
+    ) -> AnnotationImport:
+        """Upload COCO, Unitlab export or native JSON and return a label preview.
+
+        Supply a local ``annotation_file`` or a saved ``cloud_storage`` handle/ID
+        and ``annotation_key``. JSON files are limited to 600 MiB each. Media must
+        already belong to this project; use ``UploadBatch.wait()`` after upload.
+
+        Exactly one prediction namespace, ``source_name`` or ``source_id``, is
+        required. Reuse it for subsequent predictions from the same model.
+        ``options`` accepts media/class/object/review mappings and ``stable_ids``
+        (false by default). Enable stable IDs only if the exporter preserves them.
+        COCO video requires an explicit frame mapping file or storage key.
+        """
+        local = annotation_file is not None
+        cloud = cloud_storage is not None and bool(annotation_key)
+        if local == cloud or (
+            not cloud
+            and any(
+                value is not None
+                for value in (cloud_storage, annotation_key, frame_mapping_key)
+            )
+        ):
+            raise ValueError(
+                "Supply a local JSON file or a cloud storage and JSON key."
+            )
+        if bool(source_name) == bool(source_id):
+            raise ValueError("Supply exactly one of source_name or source_id.")
+        if frame_mapping_file is not None and frame_mapping_key is not None:
+            raise ValueError("Supply one frame mapping file or storage key.")
+        if track_profile not in ("none", "attributes.track_id"):
+            raise ValueError("Unknown track_profile.")
+
+        import_options = deepcopy(options or {})
+        data: dict[str, Any] = {
+            "track_profile": track_profile,
+            "options": import_options,
+        }
+        if source_id:
+            data["source_id"] = identifier(source_id)
+        else:
+            data["source_name"] = source_name
+        if cloud:
+            data.update(
+                cloud_storage_id=identifier(cloud_storage),
+                annotation_key=annotation_key,
+            )
+        if frame_mapping_key is not None:
+            data["frame_mapping_key"] = frame_mapping_key
+
+        with ExitStack() as stack:
+            files = {}
+            for name, value in (
+                ("annotation_file", annotation_file),
+                ("frame_mapping_file", frame_mapping_file),
+            ):
+                if value is None:
+                    continue
+                path = Path(value)
+                # GeoJSON exports keep their own extension; frame maps are .json.
+                suffixes = (
+                    (".json", ".geojson") if name == "annotation_file" else (".json",)
+                )
+                if not path.is_file() or path.suffix.lower() not in suffixes:
+                    raise ValueError(f"{name} must be a JSON file: {path}")
+                stream = stack.enter_context(path.open("rb"))
+                stream.seek(0, 2)
+                if stream.tell() > MAX_FILE_BYTES:
+                    raise ValueError(f"{name} must be 600 MiB or smaller.")
+                stream.seek(0)
+                files[name] = (path.name, stream, "application/json")
+            if files:
+                data["options"] = json.dumps(import_options, allow_nan=False)
+                raw = self._api.post(self._endpoint, data=data, files=files)
+            else:
+                raw = self._api.post(self._endpoint, json=data)
+
+        return AnnotationImport(
+            id=str(raw["batch_id"]),
+            project_id=self.project_id,
+            source_id=str(raw["source_id"]),
+            preview=raw,
+            _client=self._client,
+            _options=import_options,
+        )
+
+
+@dataclass
+class AnnotationImport:
+    id: str
+    project_id: str
+    source_id: str
+    preview: dict[str, Any] = field(repr=False)
+    _client: UnitlabClient = field(repr=False, compare=False)
+    _options: dict[str, Any] = field(repr=False)
+
+    @property
+    def _endpoint(self) -> str:
+        return f"/api/sdk/projects/{self.project_id}/annotation-imports/{self.id}/"
+
+    def refresh(self, *, options: dict[str, Any] | None = None) -> AnnotationImport:
+        """Re-preview after media processing or mapping changes.
+
+        Omit ``options`` to preserve them; supply a dict to replace them entirely.
+        Examine the new preview before committing it. Committed batches cannot
+        be refreshed; create another batch with the same source for reimports.
+        """
+        value = deepcopy(self._options if options is None else options)
+        preview = self._client._api.post(f"{self._endpoint}preview/", json=value)
+        self.preview = preview
+        self._options = value
+        return self
+
+    def commit(
+        self,
+        *,
+        decisions: dict[str, Literal["keep", "incoming", "skip"]] | None = None,
+        allow_partial: bool = False,
+    ) -> dict[str, Any]:
+        """Save this preview as labels; approval remains a separate review step.
+
+        Conflicts and human deletions default to ``keep``. Blocked records reject
+        the entire commit unless ``allow_partial=True``. A stale preview raises
+        ConflictError without refreshing or overwriting human work. Repeating a
+        successful commit returns its original report without duplicating labels.
+        """
+        return self._client._api.post(
+            f"{self._endpoint}commit/",
+            json={
+                "token": self.preview["token"],
+                "decisions": decisions or {},
+                "allow_partial": allow_partial,
+            },
+        )

{unitlab-3.0.5 → unitlab-3.1.0}/src/unitlab/resources/projects.py

@@ -20,6 +20,7 @@ from ._base import Namespace, identifier
 if TYPE_CHECKING:
     from unitlab.client import UnitlabClient
 
+    from .annotation_imports import AnnotationImports
     from .workflow import Workflow
 
 
@@ -167,6 +168,12 @@ class Project:
     data_item_count: int = 0
     ontology_hash: str | None = None
 
+    @property
+    def annotation_imports(self) -> AnnotationImports:
+        from .annotation_imports import AnnotationImports
+
+        return AnnotationImports(self._client, self.id)
+
     @property
     def workflow(self) -> Workflow:
         from .workflow import Workflow

unitlab-3.1.0/tests/test_annotation_imports.py

@@ -0,0 +1,326 @@
+import json
+from email import policy
+from email.parser import BytesParser
+from types import SimpleNamespace
+
+import httpx
+import pytest
+
+from unitlab import (
+    AnnotationImport,
+    ConflictError,
+    PermissionDeniedError,
+    RequestTimeoutError,
+    UnitlabClient,
+)
+from unitlab.resources.projects import Project
+
+BASE = "/api/sdk/projects/p1/annotation-imports/"
+PREVIEW = {
+    "batch_id": "b1",
+    "source_id": "s1",
+    "token": "reviewed-token",
+    "counts": {"create": 1},
+    "media": [{"status": "matched"}],
+    "classes": [],
+    "annotations": [],
+    "issues": [],
+}
+
+
+@pytest.fixture
+def labels(tmp_path):
+    path = tmp_path / "labels.json"
+    path.write_text(json.dumps({"images": [], "annotations": [], "categories": []}))
+    return path
+
+
+@pytest.fixture
+def project_factory():
+    clients = []
+
+    def make(handler):
+        client = UnitlabClient(api_key="key", api_url="http://testserver")
+        client._api.client.close()
+        client._api.client = httpx.Client(
+            base_url="http://testserver",
+            headers={"Authorization": "Api-Key key"},
+            transport=httpx.MockTransport(handler),
+        )
+        clients.append(client)
+        return Project("p1", "Project", {"pk": "p1"}, client)
+
+    yield make
+    for client in clients:
+        client.close()
+
+
+def multipart(request):
+    message = BytesParser(policy=policy.default).parsebytes(
+        f"Content-Type: {request.headers['content-type']}\r\n\r\n".encode()
+        + request.content
+    )
+    return {
+        part.get_param("name", header="content-disposition"): part.get_payload(
+            decode=True
+        )
+        for part in message.iter_parts()
+    }
+
+
+def test_s3_media_then_local_json_uses_preview_and_explicit_commit(
+    project_factory, labels
+):
+    calls = []
+
+    def handler(request):
+        calls.append(request.url.path)
+        assert request.headers["Authorization"] == "Api-Key key"
+        assert "Company" not in request.headers
+        if request.url.path.endswith("/cloud-storages/storage1/import/"):
+            assert json.loads(request.content) == {"server_files": ["images/"]}
+            return httpx.Response(
+                202, json={"upload_session_id": "q1", "file_count": 1}
+            )
+        if request.url.path.endswith("/upload-sessions/q1/status/"):
+            return httpx.Response(
+                200, json={"total": 1, "completed": 1, "processing": 0, "failed": 0}
+            )
+        if request.url.path == BASE:
+            fields = multipart(request)
+            assert fields["annotation_file"] == labels.read_bytes()
+            assert fields["source_name"] == b"detector-v1"
+            assert json.loads(fields["options"]) == {}
+            return httpx.Response(201, json=PREVIEW)
+        if request.url.path == BASE + "b1/commit/":
+            assert json.loads(request.content) == {
+                "token": "reviewed-token",
+                "decisions": {},
+                "allow_partial": False,
+            }
+            return httpx.Response(200, json={"created": 1, "batch_id": "b1"})
+        raise AssertionError(request.url)
+
+    project = project_factory(handler)
+    media = project.import_cloud("storage1", ["images/"])
+    assert media.wait().failed == 0
+    batch = project.annotation_imports.create(labels, source_name="detector-v1")
+    assert isinstance(batch, AnnotationImport)
+    assert batch.preview["counts"] == {"create": 1}
+    assert len(calls) == 3  # Preview does not implicitly commit.
+    assert batch.commit() == batch.commit()
+    assert calls[-2:] == [BASE + "b1/commit/"] * 2
+
+
+def test_video_upload_sends_explicit_frame_map(project_factory, labels, tmp_path):
+    frame_map = tmp_path / "frames.json"
+    frame_map.write_text('{"schema_version":"unitlab-frame-map/1","frames":[]}')
+
+    def handler(request):
+        fields = multipart(request)
+        assert fields["frame_mapping_file"] == frame_map.read_bytes()
+        assert fields["track_profile"] == b"attributes.track_id"
+        assert fields["source_id"] == b"s1"
+        assert "source_name" not in fields
+        return httpx.Response(201, json=PREVIEW)
+
+    project_factory(handler).annotation_imports.create(
+        labels,
+        source_id="s1",
+        frame_mapping_file=frame_map,
+        track_profile="attributes.track_id",
+    )
+
+
+def test_cloud_annotation_document_uses_json_request(project_factory):
+    def handler(request):
+        assert json.loads(request.content) == {
+            "source_name": "model",
+            "cloud_storage_id": "storage1",
+            "annotation_key": "labels/predictions.json",
+            "frame_mapping_key": "labels/frames.json",
+            "options": {"stable_ids": True},
+            "track_profile": "none",
+        }
+        return httpx.Response(201, json=PREVIEW)
+
+    batch = project_factory(handler).annotation_imports.create(
+        cloud_storage=SimpleNamespace(id="storage1"),
+        annotation_key="labels/predictions.json",
+        frame_mapping_key="labels/frames.json",
+        source_name="model",
+        options={"stable_ids": True},
+    )
+    assert batch.source_id == "s1"
+
+
+def test_refresh_preserves_options_and_uses_only_new_reviewed_token(
+    project_factory, labels
+):
+    calls = []
+
+    def handler(request):
+        calls.append(request.url.path)
+        if request.url.path == BASE:
+            return httpx.Response(201, json=PREVIEW)
+        if request.url.path.endswith("/preview/"):
+            assert json.loads(request.content) == {
+                "stable_ids": True,
+                "media_mapping": {"road.jpg": "m1"},
+            }
+            return httpx.Response(200, json={**PREVIEW, "token": "new-token"})
+        assert json.loads(request.content)["token"] == "new-token"
+        return httpx.Response(200, json={"created": 1})
+
+    options = {"stable_ids": True, "media_mapping": {"road.jpg": "m1"}}
+    batch = project_factory(handler).annotation_imports.create(
+        labels, source_name="model", options=options
+    )
+    options["media_mapping"]["road.jpg"] = "mutated"
+    assert batch.refresh() is batch
+    assert batch.commit()["created"] == 1
+    assert calls == [BASE, BASE + "b1/preview/", BASE + "b1/commit/"]
+
+
+def test_stale_preview_is_not_automatically_refreshed_or_committed(
+    project_factory, labels
+):
+    calls = []
+
+    def handler(request):
+        calls.append(request.url.path)
+        if request.url.path == BASE:
+            return httpx.Response(201, json=PREVIEW)
+        return httpx.Response(
+            409, json={"detail": "Preview changed.", "code": "CONFLICT"}
+        )
+
+    batch = project_factory(handler).annotation_imports.create(
+        labels, source_name="model"
+    )
+    with pytest.raises(ConflictError):
+        batch.commit()
+    assert calls == [BASE, BASE + "b1/commit/"]
+    assert batch.preview["token"] == "reviewed-token"
+
+
+def test_uncertain_commit_can_be_retried_with_identical_request(
+    project_factory, labels
+):
+    commits = []
+
+    def handler(request):
+        if request.url.path == BASE:
+            return httpx.Response(201, json=PREVIEW)
+        commits.append(json.loads(request.content))
+        if len(commits) == 1:
+            raise httpx.ReadTimeout("Response lost", request=request)
+        return httpx.Response(200, json={"created": 1})
+
+    batch = project_factory(handler).annotation_imports.create(
+        labels, source_name="model"
+    )
+    decisions = {"a1": "keep"}
+    with pytest.raises(RequestTimeoutError):
+        batch.commit(decisions=decisions)
+    assert batch.commit(decisions=decisions)["created"] == 1
+    assert commits[0] == commits[1]
+
+
+@pytest.mark.parametrize(
+    "extra",
+    [
+        {},
+        {"source_name": "model", "source_id": "s1"},
+        {"source_name": "model", "cloud_storage": "storage1"},
+        {
+            "source_name": "model",
+            "cloud_storage": "storage1",
+            "annotation_key": "labels.json",
+        },
+        {"source_name": "model", "frame_mapping_key": "frames.json"},
+        {"source_name": "model", "track_profile": "guess"},
+    ],
+)
+def test_invalid_source_combinations_do_not_send_requests(
+    project_factory, labels, extra
+):
+    def handler(request):
+        raise AssertionError("Invalid input must not reach the server.")
+
+    with pytest.raises(ValueError):
+        project_factory(handler).annotation_imports.create(labels, **extra)
+
+
+def test_file_size_limit_and_closed_streams_on_request_failure(
+    project_factory, labels, monkeypatch
+):
+    project = project_factory(lambda request: httpx.Response(500))
+    opened = []
+
+    def post(endpoint, *, data, files):
+        opened.extend(item[1] for item in files.values())
+        raise RuntimeError("request failed")
+
+    monkeypatch.setattr(project._client._api, "post", post)
+    with pytest.raises(RuntimeError, match="request failed"):
+        project.annotation_imports.create(labels, source_name="model")
+    assert opened and all(stream.closed for stream in opened)
+    monkeypatch.setattr("unitlab.resources.annotation_imports.MAX_FILE_BYTES", 1)
+    with pytest.raises(ValueError, match="600 MiB"):
+        project.annotation_imports.create(labels, source_name="model")
+    assert len(opened) == 1
+
+
+def test_geojson_export_is_uploaded_but_not_as_a_frame_map(
+    project_factory, labels, tmp_path
+):
+    geojson = tmp_path / "release.geojson"
+    geojson.write_text(json.dumps({"type": "FeatureCollection", "features": []}))
+
+    def handler(request):
+        parts = multipart(request)
+        assert json.loads(parts["annotation_file"])["type"] == "FeatureCollection"
+        assert "frame_mapping_file" not in parts
+        return httpx.Response(201, json=PREVIEW)
+
+    imports = project_factory(handler).annotation_imports
+    assert imports.create(geojson, source_name="raster").id == "b1"
+    with pytest.raises(ValueError, match="frame_mapping_file"):
+        imports.create(labels, frame_mapping_file=geojson, source_name="raster")
+
+
+def test_creatorless_key_commit_raises_permission_denied(project_factory, labels):
+    def handler(request):
+        if request.url.path == BASE:
+            return httpx.Response(201, json=PREVIEW)
+        return httpx.Response(
+            403,
+            json={
+                "detail": "A user-created API key is required to commit.",
+                "code": "permission_denied",
+            },
+        )
+
+    batch = project_factory(handler).annotation_imports.create(
+        labels, source_name="model"
+    )
+    with pytest.raises(PermissionDeniedError, match="user-created API key"):
+        batch.commit()
+
+
+def test_source_and_media_helpers_use_project_scoped_routes(project_factory):
+    def handler(request):
+        if request.url.path == BASE + "sources/":
+            return httpx.Response(
+                200, json={"sources": [{"id": "s1", "name": "model"}]}
+            )
+        assert request.url.path == BASE + "media/"
+        assert request.url.params["search"] == "images/road.jpg"
+        return httpx.Response(
+            200, json={"media": [{"id": "m1", "name": "images/road.jpg"}]}
+        )
+
+    imports = project_factory(handler).annotation_imports
+    assert imports.sources()[0]["id"] == "s1"
+    assert imports.media("images/road.jpg")[0]["id"] == "m1"

unitlab-3.1.0/tests/test_http.py

@@ -0,0 +1,243 @@
+import httpx
+import pytest
+
+from unitlab import (
+    ConflictError,
+    NetworkError,
+    NotFoundError,
+    PermissionDeniedError,
+    RequestTimeoutError,
+    SubscriptionError,
+)
+from unitlab._http import HttpApi, raise_for_response
+
+
+def test_requests_keep_client_timeout_unless_explicitly_overridden():
+    seen = []
+
+    def handler(request):
+        seen.append(request.extensions["timeout"])
+        return httpx.Response(200, json={"ok": True})
+
+    api = HttpApi("key", "http://testserver")
+    api.client.close()
+    api.client = httpx.Client(
+        base_url="http://testserver",
+        transport=httpx.MockTransport(handler),
+        timeout=12,
+    )
+
+    api.get("/default")
+    api.get("/override", timeout=7)
+
+    assert set(seen[0].values()) == {12}
+    assert set(seen[1].values()) == {7}
+    api.close()
+
+
+def test_forbidden_responses_distinguish_permission_and_subscription_errors():
+    request = httpx.Request("POST", "http://testserver/action")
+    permission = httpx.Response(
+        403,
+        request=request,
+        json={
+            "detail": "A user-created API key is required.",
+            "code": "permission_denied",
+        },
+    )
+    subscription = httpx.Response(
+        403,
+        request=request,
+        json={"detail": "Resource Limit Exceeded"},
+    )
+
+    with pytest.raises(PermissionDeniedError, match="user-created API key") as exc:
+        raise_for_response(permission)
+    assert exc.value.code == "permission_denied"
+
+    with pytest.raises(SubscriptionError, match="Resource Limit Exceeded") as exc:
+        raise_for_response(subscription)
+    assert exc.value.code == ""
+
+
+@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": code,
+        },
+    )
+
+    with pytest.raises(SubscriptionError) as exc:
+        raise_for_response(response)
+
+    assert exc.value.code == code
+
+
+def test_conflict_responses_raise_conflict_error_even_when_detail_says_not_found():
+    # A 409 detail may legitimately contain "not found"; the message-based
+    # NotFound fallback must never reclassify a conflict.
+    response = httpx.Response(
+        409,
+        request=httpx.Request("POST", "http://testserver/action"),
+        json={
+            "detail": "Release 0.3 is still being prepared; archive not found yet.",
+            "code": "release_not_ready",
+        },
+    )
+
+    with pytest.raises(ConflictError, match="still being prepared") as exc:
+        raise_for_response(response)
+
+    assert isinstance(exc.value, NetworkError)
+    assert not isinstance(exc.value, NotFoundError)
+    assert exc.value.code == "release_not_ready"
+
+
+@pytest.mark.parametrize(
+    ("api_url", "expected_proxy"),
+    [
+        ("http://api.example.test", "http://http-proxy.test:8080"),
+        ("https://api.example.test", "http://https-proxy.test:8081"),
+        ("http://internal.example.test", None),
+        ("https://internal.example.test", None),
+    ],
+)
+def test_environment_proxies_and_no_proxy_route_requests(
+    monkeypatch, api_url, expected_proxy
+):
+    # Observe the actual public transport selected by HTTPX, without opening
+    # sockets or inspecting its private client/mount/pool attributes.
+    for name in ("HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY"):
+        monkeypatch.delenv(name, raising=False)
+        monkeypatch.delenv(name.lower(), raising=False)
+    monkeypatch.setenv("HTTP_PROXY", "http://http-proxy.test:8080")
+    monkeypatch.setenv("HTTPS_PROXY", "http://https-proxy.test:8081")
+    monkeypatch.setenv("NO_PROXY", "internal.example.test")
+
+    original_init = httpx.HTTPTransport.__init__
+    transports = {}
+    requests = []
+
+    def initialize(transport, *args, **kwargs):
+        transports[transport] = kwargs.get("proxy")
+        original_init(transport, *args, **kwargs)
+
+    def handle_request(transport, request):
+        proxy = transports[transport]
+        requests.append((request, proxy.url if proxy is not None else None))
+        return httpx.Response(200, json={"ok": True})
+
+    monkeypatch.setattr(httpx.HTTPTransport, "__init__", initialize)
+    monkeypatch.setattr(httpx.HTTPTransport, "handle_request", handle_request)
+    api = HttpApi("synthetic-key", api_url)
+    try:
+        assert api.get("/health") == {"ok": True}
+    finally:
+        api.close()
+
+    assert len(requests) == 1
+    request, proxy = requests[0]
+    assert request.url == httpx.URL(api_url + "/health")
+    assert proxy == (httpx.URL(expected_proxy) if expected_proxy else None)
+
+
+@pytest.fixture
+def http_api():
+    api = HttpApi("synthetic-key", "https://api.example.test")
+    yield api
+    api.close()
+
+
+@pytest.mark.parametrize(
+    ("error_type", "sdk_error"),
+    [(httpx.ConnectError, NetworkError), (httpx.ConnectTimeout, RequestTimeoutError)],
+)
+@pytest.mark.parametrize("failures", [3, 4])
+def test_only_connection_failures_receive_three_retries(
+    monkeypatch, http_api, error_type, sdk_error, failures
+):
+    attempts = []
+    delays = []
+
+    def request(method, endpoint, **kwargs):
+        attempts.append((method, endpoint, kwargs))
+        if len(attempts) <= failures:
+            raise error_type("Connection could not be established")
+        return httpx.Response(200, json={"created": True})
+
+    monkeypatch.setattr(http_api.client, "request", request)
+    monkeypatch.setattr("unitlab._http.time.sleep", delays.append)
+
+    if failures == 3:
+        assert http_api.post("/imports", json={"name": "fixture"}) == {"created": True}
+    else:
+        with pytest.raises(sdk_error) as exc:
+            http_api.post("/imports", json={"name": "fixture"})
+        assert isinstance(exc.value.detail, error_type)
+    assert len(attempts) == 4
+    assert delays == [0.0, 0.5, 1.0]
+    assert all(
+        method == "POST"
+        and endpoint == "/imports"
+        and kwargs["json"] == {"name": "fixture"}
+        for method, endpoint, kwargs in attempts
+    )
+
+
+@pytest.mark.parametrize(
+    ("error_type", "sdk_error"),
+    [
+        (httpx.ReadError, NetworkError),
+        (httpx.WriteError, NetworkError),
+        (httpx.ReadTimeout, RequestTimeoutError),
+        (httpx.WriteTimeout, RequestTimeoutError),
+        (httpx.PoolTimeout, RequestTimeoutError),
+        (httpx.ProxyError, NetworkError),
+        (httpx.RemoteProtocolError, NetworkError),
+    ],
+)
+def test_post_is_not_retried_after_other_transport_failures(
+    monkeypatch, http_api, error_type, sdk_error
+):
+    attempts = []
+    delays = []
+
+    def request(method, endpoint, **kwargs):
+        attempts.append(method)
+        raise error_type("Request failed")
+
+    monkeypatch.setattr(http_api.client, "request", request)
+    monkeypatch.setattr("unitlab._http.time.sleep", delays.append)
+    with pytest.raises(sdk_error) as exc:
+        http_api.post("/imports", json={"name": "fixture"})
+    assert isinstance(exc.value.detail, error_type)
+    assert attempts == ["POST"]
+    assert delays == []
+
+
+@pytest.mark.parametrize("status_code", [400, 409, 429, 503])
+def test_post_error_status_is_not_retried(monkeypatch, http_api, status_code):
+    attempts = []
+    delays = []
+
+    def request(method, endpoint, **kwargs):
+        attempts.append(method)
+        return httpx.Response(
+            status_code,
+            request=httpx.Request(method, "https://api.example.test" + endpoint),
+            json={"detail": "Synthetic error"},
+        )
+
+    monkeypatch.setattr(http_api.client, "request", request)
+    monkeypatch.setattr("unitlab._http.time.sleep", delays.append)
+    with pytest.raises(NetworkError):
+        http_api.post("/imports", json={"name": "fixture"})
+    assert attempts == ["POST"]
+    assert delays == []

unitlab-3.0.5/tests/test_http.py

@@ -1,99 +0,0 @@
-import httpx
-import pytest
-
-from unitlab import (
-    ConflictError,
-    NetworkError,
-    NotFoundError,
-    PermissionDeniedError,
-    SubscriptionError,
-)
-from unitlab._http import HttpApi, raise_for_response
-
-
-def test_requests_keep_client_timeout_unless_explicitly_overridden():
-    seen = []
-
-    def handler(request):
-        seen.append(request.extensions["timeout"])
-        return httpx.Response(200, json={"ok": True})
-
-    api = HttpApi("key", "http://testserver")
-    api.client.close()
-    api.client = httpx.Client(
-        base_url="http://testserver",
-        transport=httpx.MockTransport(handler),
-        timeout=12,
-    )
-
-    api.get("/default")
-    api.get("/override", timeout=7)
-
-    assert set(seen[0].values()) == {12}
-    assert set(seen[1].values()) == {7}
-    api.close()
-
-
-def test_forbidden_responses_distinguish_permission_and_subscription_errors():
-    request = httpx.Request("POST", "http://testserver/action")
-    permission = httpx.Response(
-        403,
-        request=request,
-        json={
-            "detail": "A user-created API key is required.",
-            "code": "permission_denied",
-        },
-    )
-    subscription = httpx.Response(
-        403,
-        request=request,
-        json={"detail": "Resource Limit Exceeded"},
-    )
-
-    with pytest.raises(PermissionDeniedError, match="user-created API key") as exc:
-        raise_for_response(permission)
-    assert exc.value.code == "permission_denied"
-
-    with pytest.raises(SubscriptionError, match="Resource Limit Exceeded") as exc:
-        raise_for_response(subscription)
-    assert exc.value.code == ""
-
-
-@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": code,
-        },
-    )
-
-    with pytest.raises(SubscriptionError) as exc:
-        raise_for_response(response)
-
-    assert exc.value.code == code
-
-
-def test_conflict_responses_raise_conflict_error_even_when_detail_says_not_found():
-    # A 409 detail may legitimately contain "not found"; the message-based
-    # NotFound fallback must never reclassify a conflict.
-    response = httpx.Response(
-        409,
-        request=httpx.Request("POST", "http://testserver/action"),
-        json={
-            "detail": "Release 0.3 is still being prepared; archive not found yet.",
-            "code": "release_not_ready",
-        },
-    )
-
-    with pytest.raises(ConflictError, match="still being prepared") as exc:
-        raise_for_response(response)
-
-    assert isinstance(exc.value, NetworkError)
-    assert not isinstance(exc.value, NotFoundError)
-    assert exc.value.code == "release_not_ready"