datamint 2.3.1__py3-none-any.whl → 2.3.3__py3-none-any.whl

datamint/api/entity_base_api.py

@@ -1,7 +1,6 @@
 from typing import Any, TypeVar, Generic, Type, Sequence
 import logging
 import httpx
-from dataclasses import dataclass
 from datamint.entities.base_entity import BaseEntity
 from datamint.exceptions import DatamintException, ResourceNotFoundError
 import aiohttp
@@ -37,9 +36,14 @@ class EntityBaseApi(BaseApi, Generic[T]):
             client: Optional HTTP client instance. If None, a new one will be created.
         """
         super().__init__(config, client)
-        self.entity_class = entity_class
+        self.__entity_class = entity_class
         self.endpoint_base = endpoint_base.strip('/')
 
+    def _init_entity_obj(self, **kwargs) -> T:
+        obj = self.__entity_class(**kwargs)
+        obj._api = self
+        return obj
+
     @staticmethod
     def _entid(entity: BaseEntity | str) -> str:
         return entity if isinstance(entity, str) else entity.id
@@ -117,7 +121,7 @@ class EntityBaseApi(BaseApi, Generic[T]):
         for resp, items in items_gen:
             all_items.extend(items)
 
-        return [self.entity_class(**item) for item in all_items]
+        return [self._init_entity_obj(**item) for item in all_items]
 
     def get_all(self, limit: int | None = None) -> Sequence[T]:
         """Get all entities with optional pagination and filtering.
@@ -143,7 +147,7 @@ class EntityBaseApi(BaseApi, Generic[T]):
             httpx.HTTPStatusError: If the entity is not found or request fails.
         """
         response = self._make_entity_request('GET', entity_id)
-        return self.entity_class(**response.json())
+        return self._init_entity_obj(**response.json())
 
     async def _create_async(self, entity_data: dict[str, Any]) -> str | Sequence[str | dict]:
         """Create a new entity.
@@ -177,42 +181,6 @@ class EntityBaseApi(BaseApi, Generic[T]):
                                              add_path=child_entity_name)
         return response
 
-    # def bulk_create(self, entities_data: list[dict[str, Any]]) -> list[T]:
-    #     """Create multiple entities in a single request.
-
-    #     Args:
-    #         entities_data: List of dictionaries containing entity data
-
-    #     Returns:
-    #         List of created entity instances
-
-    #     Raises:
-    #         httpx.HTTPStatusError: If bulk creation fails
-    #     """
-    #     payload = {'items': entities_data}  # Common bulk API format
-    #     response = self._make_request('POST', f'/{self.endpoint_base}/bulk', json=payload)
-    #     data = response.json()
-
-    #     # Handle response format - may be direct list or wrapped
-    #     items = data if isinstance(data, list) else data.get('items', [])
-    #     return [self.entity_class(**item) for item in items]
-
-    # def count(self, **params: Any) -> int:
-    #     """Get the total count of entities matching the given filters.
-
-    #     Args:
-    #         **params: Query parameters for filtering
-
-    #     Returns:
-    #         Total count of matching entities
-
-    #     Raises:
-    #         httpx.HTTPStatusError: If the request fails
-    #     """
-    #     response = self._make_request('GET', f'/{self.endpoint_base}/count', params=params)
-    #     data = response.json()
-    #     return data.get('count', 0) if isinstance(data, dict) else data
-
 
 class DeletableEntityApi(EntityBaseApi[T]):
     """Extension of EntityBaseApi for entities that support soft deletion.
@@ -221,7 +189,7 @@ class DeletableEntityApi(EntityBaseApi[T]):
     retrieval and restoration of such entities.
     """
 
-    def delete(self, entity: str | BaseEntity) -> None:
+    def delete(self, entity: str | T) -> None:
         """Delete an entity.
 
         Args:
@@ -232,7 +200,7 @@ class DeletableEntityApi(EntityBaseApi[T]):
         """
         self._make_entity_request('DELETE', entity)
 
-    def bulk_delete(self, entities: Sequence[str | BaseEntity]) -> None:
+    def bulk_delete(self, entities: Sequence[str | T]) -> None:
         """Delete multiple entities.
 
         Args:
@@ -264,7 +232,7 @@ class DeletableEntityApi(EntityBaseApi[T]):
             httpx.HTTPStatusError: If deletion fails or entity not found
         """
         async with self._make_entity_request_async('DELETE', entity,
-                                              session=session) as resp:
+                                                   session=session) as resp:
             await resp.text()  # Consume response to complete request
 
     # def get_deleted(self, **kwargs) -> Sequence[T]:

datamint/apihandler/dto/annotation_dto.py

@@ -17,7 +17,11 @@ Classes:
 import json
 from typing import Any, TypeAlias, Literal
 import logging
-from enum import Enum
+import sys
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+    from backports.strenum import StrEnum
 from medimgkit.dicom_utils import pixel_to_patient
 import pydicom
 import numpy as np
@@ -31,7 +35,7 @@ CoordinateSystem: TypeAlias = Literal['pixel', 'patient']
 """
 
 
-class AnnotationType(Enum):
+class AnnotationType(StrEnum):
     SEGMENTATION = 'segmentation'
     AREA = 'area'
     DISTANCE = 'distance'

datamint/configs.py

@@ -18,6 +18,12 @@ _LOGGER = logging.getLogger(__name__)
 
 DIRS = PlatformDirs(appname='datamintapi')
 CONFIG_FILE = os.path.join(DIRS.user_config_dir, 'datamintapi.yaml')
+try:
+    DATAMINT_DATA_DIR = os.path.join(os.path.expanduser("~"), '.datamint')
+except Exception as e:
+    _LOGGER.error(f"Could not determine home directory: {e}")
+    DATAMINT_DATA_DIR = None
+    
 
 
 def get_env_var_name(key: str) -> str:

datamint/dataset/base_dataset.py

@@ -11,7 +11,6 @@ from torch.utils.data import DataLoader
 import torch
 from torch import Tensor
 from datamint.exceptions import DatamintException
-from medimgkit.dicom_utils import is_dicom
 from medimgkit.readers import read_array_normalized
 from medimgkit.format_detection import guess_extension, guess_typez
 from medimgkit.nifti_utils import NIFTI_MIMES, get_nifti_shape
@@ -20,6 +19,7 @@ from pathlib import Path
 from datamint.entities import Annotation, DatasetInfo
 import cv2
 from datamint.entities import Resource
+import datamint.configs
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -55,7 +55,7 @@ class DatamintBaseDataset:
         exclude_frame_label_names: List of frame label names to exclude. If None, no frame labels will be excluded.
     """
 
-    DATAMINT_DEFAULT_DIR = ".datamint"
+    
     DATAMINT_DATASETS_DIR = "datasets"
 
     def __init__(
@@ -184,8 +184,7 @@ class DatamintBaseDataset:
         """Setup root and dataset directories."""
         if root is None:
             root = os.path.join(
-                os.path.expanduser("~"),
-                self.DATAMINT_DEFAULT_DIR,
+                datamint.configs.DATAMINT_DATA_DIR,
                 self.DATAMINT_DATASETS_DIR
             )
             os.makedirs(root, exist_ok=True)
@@ -306,6 +305,15 @@ class DatamintBaseDataset:
         """Setup label sets and mappings."""
         self.frame_lsets, self.frame_lcodes = self._get_labels_set(framed=True)
         self.image_lsets, self.image_lcodes = self._get_labels_set(framed=False)
+        worklist_id = self.get_info()['worklist_id']
+        groups: dict[str, dict] = self.api.annotationsets.get_segmentation_group(worklist_id)['groups']
+        # order by 'index' key
+        max_index = max([g['index'] for g in groups.values()])
+        self.seglabel_list : list[str] = ['UNKNOWN'] * max_index  # 1-based
+        for segname, g in groups.items():
+            self.seglabel_list[g['index'] - 1] = segname
+
+        self.seglabel2code = {label: idx + 1 for idx, label in enumerate(self.seglabel_list)}
 
     def _filter_items(self, images_metainfo: list[dict]) -> list[dict]:
         """Filter items that have annotations."""
@@ -357,9 +365,7 @@ class DatamintBaseDataset:
     @property
     def segmentation_labels_set(self) -> list[str]:
         """Returns the set of segmentation labels in the dataset."""
-        a = set(self.frame_lsets['segmentation'])
-        b = set(self.image_lsets['segmentation'])
-        return list(a.union(b))
+        return self.seglabel_list
 
     def _get_annotations_internal(
         self,
@@ -463,8 +469,8 @@ class DatamintBaseDataset:
             label_anns = self.get_annotations(i, type='label', scope=scope)
             multilabel_set.update(ann.name for ann in label_anns)
 
-            seg_anns = self.get_annotations(i, type='segmentation', scope=scope)
-            segmentation_labels.update(ann.name for ann in seg_anns)
+            # seg_anns = self.get_annotations(i, type='segmentation', scope=scope)
+            # segmentation_labels.update(ann.name for ann in seg_anns)
 
             cat_anns = self.get_annotations(i, type='category', scope=scope)
             multiclass_set.update((ann.name, ann.value) for ann in cat_anns)
@@ -472,17 +478,17 @@ class DatamintBaseDataset:
         # Sort and create mappings
         multilabel_list = sorted(multilabel_set)
         multiclass_list = sorted(multiclass_set)
-        segmentation_list = sorted(segmentation_labels)
+        # segmentation_list = sorted(segmentation_labels)
 
         sets = {
             'multilabel': multilabel_list,
-            'segmentation': segmentation_list,
+            # 'segmentation': segmentation_list,
             'multiclass': multiclass_list
         }
 
         codes_map = {
             'multilabel': {label: idx for idx, label in enumerate(multilabel_list)},
-            'segmentation': {label: idx + 1 for idx, label in enumerate(segmentation_list)},
+            # 'segmentation': {label: idx + 1 for idx, label in enumerate(segmentation_list)},
             'multiclass': {label: idx for idx, label in enumerate(multiclass_list)}
         }
 

datamint/dataset/dataset.py

@@ -191,7 +191,7 @@ class DatamintDataset(DatamintBaseDataset):
             author_labels = seg_labels[author]
 
             if frame_index is not None and ann.scope == 'frame':
-                seg_code = self.frame_lcodes['segmentation'][ann.name]
+                seg_code = self.seglabel2code[ann.name]
                 if author_segs[frame_index] is None:
                     author_segs[frame_index] = []
                     author_labels[frame_index] = []
@@ -199,7 +199,7 @@ class DatamintDataset(DatamintBaseDataset):
                 author_segs[frame_index].append(s)
                 author_labels[frame_index].append(seg_code)
             elif frame_index is None and ann.scope == 'image':
-                seg_code = self.image_lcodes['segmentation'][ann.name]
+                seg_code = self.seglabel2code[ann.name]
                 # apply to all frames
                 for i in range(nframes):
                     if author_segs[i] is None:

datamint/entities/__init__.py

@@ -7,14 +7,16 @@ from .project import Project
 from .resource import Resource
 from .user import User  # new export
 from .datasetinfo import DatasetInfo
+from .cache_manager import CacheManager
 
 __all__ = [
     'Annotation',
     'BaseEntity',
+    'CacheManager',
     'Channel',
     'ChannelResourceData',
+    'DatasetInfo',
     'Project',
     'Resource',
-    "User",
-    'DatasetInfo',
+    'User',
 ]

datamint/entities/annotation.py

@@ -5,11 +5,20 @@ This module defines the Annotation model used to represent annotation
 records returned by the DataMint API.
 """
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 import logging
+import os
+
 from .base_entity import BaseEntity, MISSING_FIELD
-from pydantic import Field
+from .cache_manager import CacheManager
+from pydantic import PrivateAttr
 from datetime import datetime
+from datamint.api.dto import AnnotationType
+from datamint.types import ImagingData
+
+if TYPE_CHECKING:
+    from datamint.api.endpoints.annotations_api import AnnotationsApi
+    from .resource import Resource
 
 logger = logging.getLogger(__name__)
 
@@ -21,6 +30,8 @@ _FIELD_MAPPING = {
     'index': 'frame_index',
 }
 
+_ANNOTATION_CACHE_KEY = "annotation_data"
+
 
 class Annotation(BaseEntity):
     """Pydantic Model representing a DataMint annotation.
@@ -60,7 +71,7 @@ class Annotation(BaseEntity):
     identifier: str
     scope: str
     frame_index: int | None
-    annotation_type: str
+    annotation_type: AnnotationType
     text_value: str | None
     numeric_value: float | int | None
     units: str | None
@@ -83,7 +94,66 @@ class Annotation(BaseEntity):
     annotation_worklist_name: str | None
     user_info: dict | None
     values: list | None = MISSING_FIELD
-    file: str | None = None  # Add file field for segmentations
+    file: str | None = None
+
+    _api: 'AnnotationsApi' = PrivateAttr()
+
+    def __init__(self, **data):
+        """Initialize the annotation entity."""
+        super().__init__(**data)
+        self._cache: CacheManager = CacheManager('annotations')
+        self._resource: 'Resource | None' = None
+
+    @property
+    def resource(self) -> 'Resource':
+        """Lazily load and cache the associated Resource entity."""
+        if self._resource is None:
+            self._resource = self._api._get_resource(self)
+        return self._resource
+
+    def fetch_file_data(
+        self,
+        save_path: os.PathLike | str | None = None,
+        auto_convert: bool = True,
+        use_cache: bool = False,
+    ) -> bytes | ImagingData:
+        # Version info for cache validation
+        version_info = self._generate_version_info()
+
+        # Try to get from cache
+        img_data = None
+        if use_cache:
+            img_data = self._cache.get(self.id, _ANNOTATION_CACHE_KEY, version_info)
+
+        if img_data is None:
+            # Fetch from server using download_resource_file
+            logger.debug(f"Fetching image data from server for resource {self.id}")
+            img_data = self._api.download_file(
+                self,
+                fpath_out=save_path
+            )
+            # Cache the data
+            if use_cache:
+                self._cache.set(self.id, _ANNOTATION_CACHE_KEY, img_data, version_info)
+
+        if auto_convert:
+            return self._api.convert_format(img_data)
+
+        return img_data
+
+    def _generate_version_info(self) -> dict:
+        """Helper to generate version info for caching."""
+        return {
+            'created_at': self.created_at,
+            'deleted_at': self.deleted_at,
+            'associated_file': self.associated_file,
+        }
+
+    def invalidate_cache(self) -> None:
+        """Invalidate all cached data for this annotation."""
+        self._cache.invalidate(self.id)
+        self._resource = None
+        logger.debug(f"Invalidated cache for annotation {self.id}")
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> 'Annotation':

datamint/entities/base_entity.py

@@ -1,7 +1,11 @@
 import logging
 import sys
-from typing import Any
-from pydantic import ConfigDict, BaseModel
+from typing import Any, TYPE_CHECKING
+from pydantic import ConfigDict, BaseModel, PrivateAttr
+
+if TYPE_CHECKING:
+    from datamint.api.client import Api
+    from datamint.api.entity_base_api import EntityBaseApi
 
 if sys.version_info >= (3, 11):
     from typing import Self
@@ -22,9 +26,14 @@ class BaseEntity(BaseModel):
     This class provides common functionality for all entities, such as
     serialization and deserialization from dictionaries, as well as
     handling unknown fields gracefully.
+
+    The API client is automatically injected by the Api class when entities
+    are created through API endpoints.
     """
 
-    model_config = ConfigDict(extra='allow')  # Allow extra fields not defined in the model
+    model_config = ConfigDict(extra='allow', arbitrary_types_allowed=True)  # Allow extra fields and arbitrary types
+
+    _api: 'EntityBaseApi[Self] | EntityBaseApi' = PrivateAttr()
 
     def asdict(self) -> dict[str, Any]:
         """Convert the entity to a dictionary, including unknown fields."""
@@ -38,14 +47,46 @@ class BaseEntity(BaseModel):
         """Handle unknown fields by logging a warning once per class/field combination in debug mode."""
         if self.__pydantic_extra__ and _LOGGER.isEnabledFor(logging.DEBUG):
             class_name = self.__class__.__name__
-            
+
             have_to_log = False
             for key in self.__pydantic_extra__.keys():
                 warning_key = (class_name, key)
-                
+
                 if warning_key not in _LOGGED_WARNINGS:
                     _LOGGED_WARNINGS.add(warning_key)
                     have_to_log = True
-            
+
             if have_to_log:
                 _LOGGER.warning(f"Unknown fields {list(self.__pydantic_extra__.keys())} found in {class_name}")
+
+    @staticmethod
+    def is_attr_missing(value: Any) -> bool:
+        """Check if a value is the MISSING_FIELD sentinel."""
+        return value == MISSING_FIELD
+
+    def _refresh(self) -> Self:
+        """Refresh the entity data from the server.
+
+        This method fetches the latest data from the server and updates
+        the current instance with any missing or updated fields.
+
+        Returns:
+            The updated Entity instance (self)
+        """
+        updated_ent = self._api.get_by_id(self._api._entid(self))
+
+        # Update all fields from the fresh data
+        for field_name, field_value in updated_ent.model_dump().items():
+            if field_value != MISSING_FIELD:
+                setattr(self, field_name, field_value)
+
+        return self
+
+    def _ensure_attr(self, attr_name: str) -> None:
+        """Ensure that a given attribute is not MISSING_FIELD, refreshing if necessary.
+
+        Args:
+            attr_name: Name of the attribute to check and ensure
+        """
+        if self.is_attr_missing(getattr(self, attr_name)):
+            self._refresh()