datamint 2.26.0__tar.gz → 2.28.0__tar.gz

{datamint-2.26.0 → datamint-2.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datamint
-Version: 2.26.0
+Version: 2.28.0
 Summary: A library for interacting with the Datamint API, designed for efficient data management, processing and Deep Learning workflows.
 Requires-Python: >=3.10
 Classifier: Programming Language :: Python :: 3

{datamint-2.26.0 → datamint-2.28.0}/datamint/__init__.py

@@ -15,6 +15,9 @@ if TYPE_CHECKING:
     from .dataset.image_dataset import ImageDataset as ImageDataset
     from .dataset.volume_dataset import VolumeDataset as VolumeDataset
     from .default_project import select_project as select_project
+    from .importers.coco import COCOImporter as COCOImporter
+    from .importers.pascal_voc import PascalVOCImporter as PascalVOCImporter
+    from .importers.yolo import YOLOImporter as YOLOImporter
     from .mlflow.flavors.validation import (
         ModelValidationError as ModelValidationError,
         ValidationIssue as ValidationIssue,
@@ -27,7 +30,7 @@ else:
 
     __getattr__, __dir__, __all__ = lazy.attach(
         __name__,
-        submodules=['dataset', "examples"],
+        submodules=['dataset', "examples", "importers"],
         submod_attrs={
             "api.client": ["Api"],
             # New modular dataset classes
@@ -36,6 +39,9 @@ else:
             "mlflow.flavors.validation": ["validate_model", "ValidationReport",
                                           "ValidationIssue", "ModelValidationError"],
             "default_project": ["select_project"],
+            "importers.coco": ["COCOImporter"],
+            "importers.pascal_voc": ["PascalVOCImporter"],
+            "importers.yolo": ["YOLOImporter"],
         },
     )
 

{datamint-2.26.0 → datamint-2.28.0}/datamint/api/base_api.py

@@ -593,6 +593,7 @@ class BaseApi:
                                       endpoint: str,
                                       return_field: str | None = None,
                                       limit: int | None = None,
+                                      max_page_size: int | None = None,
                                       **kwargs
                                       ) -> Generator[tuple[httpx.Response, list | dict | str], None, None]:
         """Make paginated HTTP requests, yielding each page of results.
@@ -602,6 +603,8 @@ class BaseApi:
             endpoint: API endpoint path
             return_field: Optional field name to extract from each item in the response
             limit: Optional maximum number of items to retrieve
+            max_page_size: Optional cap on the per-request page size, for endpoints
+                whose server route enforces a lower limit than the client default.
             **kwargs: Additional arguments for the request (e.g., params, json)
 
         Yields:
@@ -609,6 +612,7 @@ class BaseApi:
         """
         offset = 0
         total_fetched = 0
+        page_size = min(_PAGE_LIMIT, max_page_size) if max_page_size is not None else _PAGE_LIMIT
 
         use_json_pagination = method.upper() == 'POST' and 'json' in kwargs and isinstance(kwargs['json'], dict)
 
@@ -621,10 +625,10 @@ class BaseApi:
             if limit is not None and total_fetched >= limit:
                 break
 
-            page_limit = _PAGE_LIMIT
+            page_limit = page_size
             if limit is not None:
                 remaining = limit - total_fetched
-                page_limit = min(_PAGE_LIMIT, remaining)
+                page_limit = min(page_size, remaining)
 
             if use_json_pagination:
                 kwargs['json']['offset'] = str(offset)
@@ -649,7 +653,7 @@ class BaseApi:
             yield response, items_to_yield
             total_fetched += len(items_to_yield)
 
-            if len(items) < _PAGE_LIMIT:
+            if len(items) < page_size:
                 break
 
             offset += len(items)

{datamint-2.26.0 → datamint-2.28.0}/datamint/api/endpoints/annotationsets_api.py

@@ -173,6 +173,16 @@ class AnnotationWorklistApi(CreatableEntityApi[AnnotationWorklist],
                                          worklist_id,
                                          'segmentation-group').json()
 
+    def get_list(self, limit: int | None = None, **kwargs) -> list[AnnotationWorklist]:
+        """Not supported: there is no server endpoint to list worklists across all projects.
+
+        Use :meth:`get_by_project` instead.
+        """
+        raise NotImplementedError(
+            "AnnotationWorklistApi.get_list()/get_all() is not supported. Use "
+            "get_by_project(project) to list the worklists for a specific project."
+        )
+
     def get_by_project(self, project: 'str | Project') -> list[AnnotationWorklist]:
         """Get the worklist IDs associated with a project.
 

{datamint-2.26.0 → datamint-2.28.0}/datamint/api/endpoints/inference_api.py

@@ -36,6 +36,8 @@ class InferenceApi(EntityBaseApi[InferenceJob]):
     (image, frame, slice, volume).
     """
 
+    _max_page_size = 500  # server enforces `le=500` on the list route's `limit` query param
+
     def __init__(self,
                  config: ApiConfig,
                  client: httpx.Client | None = None,
@@ -54,6 +56,12 @@ class InferenceApi(EntityBaseApi[InferenceJob]):
             data['id'] = data.pop('job_id')
         return self._init_entity_obj(**data)
 
+    def _init_entity_obj(self, **kwargs) -> InferenceJob:
+        """Rename the server's 'job_id' to 'id' before constructing the entity."""
+        if 'job_id' in kwargs and 'id' not in kwargs:
+            kwargs['id'] = kwargs.pop('job_id')
+        return super()._init_entity_obj(**kwargs)
+
     def _build_common_payload(
         self,
         model_name: str,

{datamint-2.26.0 → datamint-2.28.0}/datamint/api/entity_base_api.py

@@ -139,6 +139,10 @@ class EntityBaseApi(BaseApi, Generic[T]):
                 raise ItemNotFoundError(self.endpoint_base, {'id': entity_id}) from e
             raise
 
+    #: Optional cap on the per-request page size, for endpoints whose server
+    #: route enforces a lower limit than the client default.
+    _max_page_size: int | None = None
+
     def get_list(self, limit: int | None = None,
                  **kwargs) -> Sequence[T]:
         """Get entities with optional filtering.
@@ -159,6 +163,7 @@ class EntityBaseApi(BaseApi, Generic[T]):
         items_gen = self._make_request_with_pagination('GET', f'/{self.endpoint_base}',
                                                        return_field=self.endpoint_base,
                                                        limit=limit,
+                                                       max_page_size=self._max_page_size,
                                                        **new_kwargs)
 
         all_items = []

{datamint-2.26.0 → datamint-2.28.0}/datamint/entities/base_entity.py

@@ -77,53 +77,6 @@ class BaseEntityModel(BaseModel):
             if hasattr(self, field_name) and isinstance(getattr(self, field_name), str) and getattr(self, field_name) == MISSING_FIELD:
                 delattr(self, field_name)
 
-    def __getattr__(self, name: str) -> Any:
-        """Intercept access to missing fields and trigger automatic refresh.
-
-        When a field has the MISSING_FIELD sentinel value, it is deleted in __init__.
-        This method catches subsequent attribute access attempts and automatically
-        refreshes the entity from the server to populate all missing fields.
-
-        Private attributes (e.g. ``_api``) are forwarded to Pydantic's own
-        ``__getattr__`` so we don't break Pydantic's private-attribute handling,
-        which we override by defining this method.
-        """
-        # Delegate private attributes to Pydantic's handler (manages __pydantic_private__).
-        # Defining our own __getattr__ overrides Pydantic's, so we must forward these.
-        if name.startswith('_'):
-            try:
-                return super().__getattr__(name)
-            except AttributeError:
-                raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
-
-        # Check if this is a declared Pydantic field that was deleted (MISSING_FIELD)
-        try:
-            pydantic_fields = object.__getattribute__(self, '__pydantic_fields__')
-        except AttributeError:
-            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
-
-        if name not in pydantic_fields:
-            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
-
-        # This is a declared field that was deleted (MISSING_FIELD sentinel).
-        # Try to refresh from the server using _api stored in __pydantic_private__.
-        try:
-            private_state = object.__getattribute__(self, '__pydantic_private__') or {}
-            api_ref = private_state.get('_api')
-            if api_ref is not None:
-                _LOGGER.debug(
-                    "Lazy-loading missing field '%s' on %s (id=%s) via automatic refresh",
-                    name, type(self).__name__, getattr(self, 'id', '<unknown>')
-                )
-                self._refresh()
-                # After refresh, the field should be populated
-                return object.__getattribute__(self, name)
-        except Exception:
-            # If refresh fails for any reason, fall through to standard error
-            pass
-
-        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
-
     def asdict(self) -> dict[str, Any]:
         """Convert the entity to a dictionary, including unknown fields."""
         d = self.model_dump(warnings='none')
@@ -149,22 +102,6 @@ class BaseEntityModel(BaseModel):
             if have_to_log:
                 _LOGGER.warning(f"Unknown fields {list(self.__pydantic_extra__.keys())} found in {class_name}")
 
-    def is_attr_missing(self, attr_name: str) -> bool:
-        """Check if a value is the MISSING_FIELD sentinel."""
-        if attr_name not in self.__pydantic_fields__:
-            raise AttributeError(f"Attribute '{attr_name}' not found in entity of type '{self.__class__.__name__}'")
-        if not hasattr(self, attr_name):
-            return True
-        return getattr(self, attr_name) == MISSING_FIELD
-
-    def has_missing_attrs(self) -> bool:
-        """Check if the entity has any attributes that are MISSING_FIELD.
-
-        Returns:
-            True if any attribute is MISSING_FIELD, False otherwise
-        """
-        return any(self.is_attr_missing(attr_name) for attr_name in self.__pydantic_fields__)
-
 
 class BaseEntity(BaseEntityModel):
     """
@@ -195,8 +132,8 @@ class BaseEntity(BaseEntityModel):
         # nested Pydantic models are preserved as model instances rather than
         # being converted to plain dicts (as model_dump() would do).
         for field_name in updated_ent.__pydantic_fields__:
-            if hasattr(updated_ent, field_name): # FIXME: might be always true
-                setattr(self, field_name, getattr(updated_ent, field_name))
+            if updated_ent._raw_hasattr(field_name):
+                setattr(self, field_name, updated_ent._getraw_attr(field_name))
 
         # Also propagate any extra (unknown) fields
         if updated_ent.__pydantic_extra__:
@@ -206,6 +143,69 @@ class BaseEntity(BaseEntityModel):
 
         return self
 
+    def _getraw_attr(self, name: str) -> Any:
+        """Get the raw attribute value without triggering automatic refresh."""
+        return object.__getattribute__(self, name)  # Pydantic has this implemented
+
+    def _raw_hasattr(self, name: str) -> bool:
+        try:
+            v = self._getraw_attr(name)
+            if v is MISSING_FIELD:
+                return False
+            return True
+        except AttributeError:
+            return False
+
+    def __getattr__(self, name: str) -> Any:
+        """Intercept access to missing fields and trigger automatic refresh.
+
+        When a field has the MISSING_FIELD sentinel value, it is deleted in __init__.
+        This method catches subsequent attribute access attempts and automatically
+        refreshes the entity from the server to populate all missing fields.
+
+        """
+        # Delegate private attributes to Pydantic's handler (manages __pydantic_private__).
+        # Defining our own __getattr__ overrides Pydantic's, so we must forward these.
+        if name.startswith('_'):
+            try:
+                return super().__getattr__(name)  # pydantic implements __getattr__
+            except AttributeError:
+                try:
+                    return object.__getattribute__(self, name)
+                except AttributeError:
+                    raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+
+        # Check if this is a declared Pydantic field that was deleted (MISSING_FIELD)
+        try:
+            pydantic_fields = object.__getattribute__(self, '__pydantic_fields__')
+        except AttributeError:
+            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+
+        if name not in pydantic_fields:
+            # Not a declared field - fall back to pydantic's extra fields (extra='allow')
+            pydantic_extra = object.__getattribute__(self, '__pydantic_extra__')
+            if pydantic_extra is not None and name in pydantic_extra:
+                return pydantic_extra[name]
+            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+
+        # This is a declared field that was deleted (MISSING_FIELD sentinel).
+        # Try to refresh from the server using _api stored in __pydantic_private__.
+        try:
+            private_state = object.__getattribute__(self, '__pydantic_private__') or {}
+            api_ref = private_state.get('_api')
+            if api_ref is not None:
+                _LOGGER.debug("Refreshing %s from server since %s is missing",
+                              type(self).__name__, name)
+                self._refresh()
+                # After refresh, the field should be populated. If not, raise AttributeError
+                if self._raw_hasattr(name):
+                    return self._getraw_attr(name)
+        except Exception as e:
+            # If refresh fails for any reason, fall through to standard error
+            raise
+
+        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+
     def _ensure_attr(self, attr_name: str) -> None:
         """Ensure that a given attribute is not MISSING_FIELD, refreshing if necessary.
 
@@ -279,7 +279,7 @@ class BaseEntity(BaseEntityModel):
         # Try to get from cache
         img_data = None
         should_load_from_cache, should_save_to_cache = self._resolve_cache_mode(use_cache)
-        
+
         if should_load_from_cache:
             img_data = cache_manager.get(self.id, data_key, version_info)
 
@@ -287,11 +287,10 @@ class BaseEntity(BaseEntityModel):
             # Cache miss - fetch from server
             if should_save_to_cache and save_path:
                 # Download directly to save_path, register location in cache metadata
-                _LOGGER.debug("Downloading to save_path: %s", save_path)
                 Path(save_path).parent.mkdir(parents=True, exist_ok=True)
-                
+
                 img_data = download_callback(save_path)
-                
+
                 # Register save_path in cache metadata (no file duplication)
                 cache_manager.register_file_location(
                     self.id, data_key, save_path, version_info
@@ -300,9 +299,9 @@ class BaseEntity(BaseEntityModel):
                 # No save_path - download to cache directory
                 cache_path = cache_manager.get_expected_path(self.id, data_key)
                 _LOGGER.debug("Downloading to cache: %s", cache_path)
-                
+
                 img_data = download_callback(str(cache_path))
-                
+
                 # Register in cache metadata
                 cache_manager.set(self.id, data_key, img_data, version_info)
             else:
@@ -322,3 +321,19 @@ class BaseEntity(BaseEntityModel):
                 f.write(img_data)
 
         return img_data
+
+    def is_attr_missing(self, attr_name: str) -> bool:
+        """Check if a value is the MISSING_FIELD sentinel."""
+        if attr_name not in self.__pydantic_fields__:
+            raise AttributeError(f"Attribute '{attr_name}' not found in entity of type '{self.__class__.__name__}'")
+        if not self._raw_hasattr(attr_name):
+            return True
+        return getattr(self, attr_name) == MISSING_FIELD
+
+    def has_missing_attrs(self) -> bool:
+        """Check if the entity has any attributes that are MISSING_FIELD.
+
+        Returns:
+            True if any attribute is MISSING_FIELD, False otherwise
+        """
+        return any(self.is_attr_missing(attr_name) for attr_name in self.__pydantic_fields__)

{datamint-2.26.0 → datamint-2.28.0}/datamint/entities/project.py

@@ -45,7 +45,6 @@ class Project(BaseEntity):
         closed_resources_count: Number of resources marked as closed/completed
         resources_to_annotate_count: Number of resources still needing annotation
         annotators: List of annotators assigned to this project
-        pinned_metrics: Metric names pinned for display for this project
     """
     id: str
     name: str
@@ -55,18 +54,9 @@ class Project(BaseEntity):
     archived: bool
     resource_count: int
     description: str | None
-    registered_model: Any | None = Field(default=MISSING_FIELD)
-    ai_model_id: str | None = Field(default=MISSING_FIELD)
-    closed_resources_count: int = Field(default=MISSING_FIELD)
-    resources_to_annotate_count: int = Field(default=MISSING_FIELD)
+    archived: bool
     most_recent_experiment: str | None = Field(default=MISSING_FIELD)
     annotators: list[_ProjectAnnotatorInfo] = Field(default=MISSING_FIELD)
-    archived_on: str | None = Field(default=MISSING_FIELD)
-    archived_by: str | None = Field(default=MISSING_FIELD)
-    is_active_learning: bool = Field(default=MISSING_FIELD)
-    two_up_display: bool = Field(default=MISSING_FIELD)
-    require_review: bool = Field(default=MISSING_FIELD)
-    pinned_metrics: list[str] | None = Field(default=MISSING_FIELD)
 
     _api: 'ProjectsApi' = PrivateAttr()
 

datamint-2.28.0/datamint/importers/__init__.py

@@ -0,0 +1,9 @@
+from .coco import COCOBox, COCOImporter, COCOImportResult, COCOParseResult, COCOSample
+from .pascal_voc import PascalVOCBox, PascalVOCImporter, PascalVOCImportResult, PascalVOCParseResult, PascalVOCSample
+from .yolo import YOLOBox, YOLOImporter, YOLOImportResult, YOLOParseResult, YOLOSample
+
+__all__ = [
+    'COCOImporter', 'COCOParseResult', 'COCOImportResult', 'COCOSample', 'COCOBox',
+    'PascalVOCImporter', 'PascalVOCParseResult', 'PascalVOCImportResult', 'PascalVOCSample', 'PascalVOCBox',
+    'YOLOImporter', 'YOLOParseResult', 'YOLOImportResult', 'YOLOSample', 'YOLOBox',
+]

datamint-2.28.0/datamint/importers/_common.py

@@ -0,0 +1,86 @@
+import logging
+from typing import Callable, Literal, Sequence
+
+from tqdm.auto import tqdm
+
+from datamint import Api
+from datamint.entities import Project
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def import_boxes_to_project(result,
+                            project: Project | str,
+                            api: Api | None,
+                            *,
+                            box_points: Callable[[object], tuple[tuple[float, float], tuple[float, float]]],
+                            source_label: str,
+                            tags: Sequence[str] | None,
+                            imported_from: str,
+                            on_error: Literal['raise', 'skip'],
+                            progress_bar: bool,
+                            result_cls: type):
+    """Shared upload loop behind every ``*Importer.import_to_project()``.
+
+    ``result`` is a parse result with ``samples``, ``missing_images``, and
+    ``unsupported_annotations`` attributes. ``box_points`` maps a format's box
+    dataclass to a ``(point1, point2)`` pair for ``add_box_annotation``.
+
+    """
+    api = api or Api()
+
+    if result.missing_images:
+        _LOGGER.warning(f'{len(result.missing_images)} image(s) referenced in {source_label} '
+                        f'were not found on disk and will be skipped.')
+    if result.unsupported_annotations:
+        _LOGGER.warning(f'{result.unsupported_annotations} annotation(s) in {source_label} use an '
+                        f'unsupported annotation type (e.g. polygon/segmentation) and were not '
+                        f'imported; only bounding boxes are supported.')
+
+    uploaded = api.resources.upload_resources(
+        [str(s.image_path) for s in result.samples],
+        tags=tags,
+        publish_to=project,
+        on_error=on_error,
+        progress_bar=progress_bar,
+    )
+
+    resource_ids: list[str] = []
+    errors: list[tuple[str, Exception]] = []
+    n_boxes_uploaded = 0
+
+    iterator = zip(result.samples, uploaded)
+    if progress_bar:
+        iterator = tqdm(iterator, total=len(result.samples), desc='Uploading annotations')
+
+    for sample, resource_id in iterator:
+        if isinstance(resource_id, Exception):
+            errors.append((sample.file_name, resource_id))
+            continue
+        resource_ids.append(resource_id)
+
+        for box in sample.boxes:
+            point1, point2 = box_points(box)
+            try:
+                api.annotations.add_box_annotation(
+                    point1=point1,
+                    point2=point2,
+                    resource=resource_id,
+                    identifier=box.label,
+                    imported_from=imported_from,
+                )
+                n_boxes_uploaded += 1
+            except (KeyboardInterrupt, SystemExit):
+                raise
+            except Exception as e:
+                if on_error == 'raise':
+                    raise
+                errors.append((sample.file_name, e))
+
+    return result_cls(
+        project=project,
+        resource_ids=resource_ids,
+        n_images_uploaded=len(resource_ids),
+        n_boxes_uploaded=n_boxes_uploaded,
+        errors=errors,
+    )

datamint-2.28.0/datamint/importers/coco.py

@@ -0,0 +1,150 @@
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, Sequence
+
+from datamint import Api
+from datamint.entities import Project
+
+from . import _common
+
+
+@dataclass
+class COCOBox:
+    label: str
+    x: float
+    y: float
+    width: float
+    height: float
+
+
+@dataclass
+class COCOSample:
+    image_path: Path
+    file_name: str
+    boxes: list[COCOBox] = field(default_factory=list)
+
+
+@dataclass
+class COCOParseResult:
+    samples: list[COCOSample]
+    class_names: list[str]
+    missing_images: list[str]
+    unsupported_annotations: int
+
+    @property
+    def num_images(self) -> int:
+        return len(self.samples)
+
+    @property
+    def num_boxes(self) -> int:
+        return sum(len(s.boxes) for s in self.samples)
+
+
+@dataclass
+class COCOImportResult:
+    project: Project | str
+    resource_ids: list[str]
+    n_images_uploaded: int
+    n_boxes_uploaded: int
+    errors: list[tuple[str, Exception]] = field(default_factory=list)
+
+
+class COCOImporter:
+    """Parse a COCO-format annotations file and upload it to a Datamint project. """
+
+    def __init__(self, annotations_file: str | Path, images_dir: str | Path | None = None):
+        self.annotations_file = Path(annotations_file)
+        self.images_dir = Path(images_dir) if images_dir is not None else self.annotations_file.parent
+        self._result: COCOParseResult | None = None
+
+    def parse(self, force: bool = False) -> COCOParseResult:
+        """Read and validate the COCO JSON file.
+
+        Cached after the first call; pass ``force=True`` to reparse.
+
+        Raises:
+            ValueError: If the file is structurally invalid (missing required
+                keys, or an annotation references an unknown category/image id).
+        """
+        if self._result is not None and not force:
+            return self._result
+
+        with open(self.annotations_file) as f:
+            data = json.load(f)
+
+        for key in ('images', 'annotations', 'categories'):
+            if key not in data:
+                raise ValueError(f"Invalid COCO file: missing required key '{key}'.")
+
+        categories = {cat['id']: cat['name'] for cat in data['categories']}
+
+        images_by_id: dict[int, tuple[str, Path]] = {}
+        missing_images: list[str] = []
+        samples_by_id: dict[int, COCOSample] = {}
+        for img in data['images']:
+            file_name = img['file_name']
+            image_path = self.images_dir / file_name
+            images_by_id[img['id']] = (file_name, image_path)
+            if not image_path.exists():
+                missing_images.append(file_name)
+                continue
+            samples_by_id[img['id']] = COCOSample(image_path=image_path, file_name=file_name)
+
+        used_class_names: set[str] = set()
+        unsupported_annotations = 0
+        for ann in data['annotations']:
+            image_id = ann['image_id']
+            if image_id not in images_by_id:
+                raise ValueError(f"Annotation {ann.get('id')} references unknown image_id {image_id}.")
+            if image_id not in samples_by_id:
+                continue  # image file missing on disk, already recorded above
+
+            category_id = ann['category_id']
+            if category_id not in categories:
+                raise ValueError(f"Annotation {ann.get('id')} references unknown category_id {category_id}.")
+
+            bbox = ann.get('bbox')
+            if bbox is None:
+                # COCO allows annotations without bounding boxes (e.g., segmentation-only annotations)
+                if ann.get('segmentation'):
+                    unsupported_annotations += 1
+                continue
+
+            x, y, width, height = bbox
+            label = categories[category_id]
+            samples_by_id[image_id].boxes.append(COCOBox(label=label, x=x, y=y, width=width, height=height))
+            used_class_names.add(label)
+
+        self._result = COCOParseResult(
+            samples=list(samples_by_id.values()),
+            class_names=sorted(used_class_names),
+            missing_images=missing_images,
+            unsupported_annotations=unsupported_annotations,
+        )
+        return self._result
+
+    def import_to_project(self,
+                          project: Project | str,
+                          api: Api | None = None,
+                          *,
+                          tags: Sequence[str] | None = None,
+                          imported_from: str = 'coco-import',
+                          on_error: Literal['raise', 'skip'] = 'raise',
+                          progress_bar: bool = True) -> COCOImportResult:
+        """Upload the parsed images and box annotations to a Datamint project.
+
+        Calls :meth:`parse` first (reusing the cached result if already called).
+        ``api`` defaults to a new :class:`~datamint.api.client.Api` instance if not given.
+        """
+        result = self.parse()
+        return _common.import_boxes_to_project(
+            result, project, api,
+            box_points=lambda b: ((b.x, b.y), (b.x + b.width, b.y + b.height)),
+            source_label=str(self.annotations_file),
+            tags=tags,
+            imported_from=imported_from,
+            on_error=on_error,
+            progress_bar=progress_bar,
+            result_cls=COCOImportResult,
+        )