datamint 1.9.2__py3-none-any.whl → 2.0.0__py3-none-any.whl

datamint/api/endpoints/users_api.py

@@ -0,0 +1,38 @@
+from ..entity_base_api import CreatableEntityApi, ApiConfig
+from datamint.entities import User
+import httpx
+
+
+class UsersApi(CreatableEntityApi[User]):
+    def __init__(self,
+                 config: ApiConfig,
+                 client: httpx.Client | None = None) -> None:
+        super().__init__(config, User, 'users', client)
+
+    def create(self,
+               email: str,
+               password: str | None = None,
+               firstname: str | None = None,
+               lastname: str | None = None,
+               roles: list[str] | None = None
+               ) -> str:
+        """Create a new user.
+
+        Args:
+            email: The user's email address.
+            password: The user's password. If None, a random password will be generated.
+            firstname: The user's first name.
+            lastname: The user's last name.
+            roles: List of roles to assign to the user.
+
+        Returns:
+            The id of the created user.
+        """
+        data = dict(
+            email=email,
+            password=password,
+            firstname=firstname,
+            lastname=lastname,
+            roles=roles
+        )
+        return self._create(data)

datamint/api/entity_base_api.py

@@ -0,0 +1,347 @@
+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
+import asyncio
+from .base_api import ApiConfig, BaseApi
+import contextlib
+from typing import AsyncGenerator
+
+logger = logging.getLogger(__name__)
+T = TypeVar('T', bound=BaseEntity)
+
+
+class EntityBaseApi(BaseApi, Generic[T]):
+    """Base API handler for entity-related endpoints with CRUD operations.
+
+    This class provides a template for API handlers that work with specific
+    entity types, offering common CRUD operations with proper typing.
+
+    Type Parameters:
+        T: The entity type this API handler manages (must extend BaseEntity)
+    """
+
+    def __init__(self, config: ApiConfig,
+                 entity_class: Type[T],
+                 endpoint_base: str,
+                 client: httpx.Client | None = None) -> None:
+        """Initialize the entity API handler.
+
+        Args:
+            config: API configuration containing base URL, API key, etc.
+            entity_class: The entity class this handler manages
+            endpoint_base: Base endpoint path (e.g., 'projects', 'annotations')
+            client: Optional HTTP client instance. If None, a new one will be created.
+        """
+        super().__init__(config, client)
+        self.entity_class = entity_class
+        self.endpoint_base = endpoint_base.strip('/')
+
+    @staticmethod
+    def _entid(entity: BaseEntity | str) -> str:
+        return entity if isinstance(entity, str) else entity.id
+
+    def _make_entity_request(self,
+                             method: str,
+                             entity_id: str | BaseEntity,
+                             add_path: str = '',
+                             **kwargs) -> httpx.Response:
+        try:
+            entity_id = self._entid(entity_id)
+            add_path = '/'.join(add_path.strip().strip('/').split('/'))
+            return self._make_request(method, f'/{self.endpoint_base}/{entity_id}/{add_path}', **kwargs)
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise ResourceNotFoundError(self.endpoint_base, {'id': entity_id}) from e
+            raise
+
+    @contextlib.asynccontextmanager
+    async def _make_entity_request_async(self,
+                                         method: str,
+                                         entity_id: str | BaseEntity,
+                                         add_path: str = '',
+                                         session: aiohttp.ClientSession | None = None,
+                                         **kwargs) -> AsyncGenerator[aiohttp.ClientResponse, None]:
+        try:
+            entity_id = self._entid(entity_id)
+            add_path = '/'.join(add_path.strip().strip('/').split('/'))
+            async with self._make_request_async(method,
+                                                f'/{self.endpoint_base}/{entity_id}/{add_path}',
+                                                session=session,
+                                                **kwargs) as resp:
+                yield resp
+        except aiohttp.ClientResponseError as e:
+            if e.status == 404:
+                raise ResourceNotFoundError(self.endpoint_base, {'id': entity_id}) from e
+            raise
+
+    def _stream_entity_request(self,
+                               method: str,
+                               entity_id: str,
+                               add_path: str = '',
+                               **kwargs):
+        try:
+            add_path = '/'.join(add_path.strip().strip('/').split('/'))
+            return self._stream_request(method, f'/{self.endpoint_base}/{entity_id}/{add_path}', **kwargs)
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise ResourceNotFoundError(self.endpoint_base, {'id': entity_id}) from e
+            raise
+
+    def get_list(self, limit: int | None = None,
+                 **kwargs) -> Sequence[T]:
+        """Get entities with optional filtering.
+
+        Returns:
+            List of entity instances.
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails.
+        """
+        new_kwargs = dict(kwargs)
+
+        # Remove None values from the payload.
+        for k in list(new_kwargs.keys()):
+            if new_kwargs[k] is None:
+                del new_kwargs[k]
+
+        items_gen = self._make_request_with_pagination('GET', f'/{self.endpoint_base}',
+                                                       return_field=self.endpoint_base,
+                                                       limit=limit,
+                                                       **new_kwargs)
+
+        all_items = []
+        for resp, items in items_gen:
+            all_items.extend(items)
+
+        return [self.entity_class(**item) for item in all_items]
+
+    def get_all(self, limit: int | None = None) -> Sequence[T]:
+        """Get all entities with optional pagination and filtering.
+
+        Returns:
+            List of entity instances
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails
+        """
+        return self.get_list(limit=limit)
+
+    def get_by_id(self, entity_id: str) -> T:
+        """Get a specific entity by its ID.
+
+        Args:
+            entity_id: Unique identifier for the entity.
+
+        Returns:
+            Entity instance.
+
+        Raises:
+            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())
+
+    async def _create_async(self, entity_data: dict[str, Any]) -> str | Sequence[str | dict]:
+        """Create a new entity.
+
+        Args:
+            entity_data: Dictionary containing entity data for creation.
+
+        Returns:
+            The id of the created entity.
+
+        Raises:
+            httpx.HTTPStatusError: If creation fails.
+        """
+        respdata = await self._make_request_async_json('POST',
+                                                       f'/{self.endpoint_base}',
+                                                       json=entity_data)
+        if 'error' in respdata:
+            raise DatamintException(respdata['error'])
+        if isinstance(respdata, str):
+            return respdata
+        if isinstance(respdata, list):
+            return respdata
+        if isinstance(respdata, dict):
+            return respdata.get('id')
+        return respdata
+
+    def _get_child_entities(self,
+                            parent_entity: BaseEntity | str,
+                            child_entity_name: str) -> httpx.Response:
+        response = self._make_entity_request('GET', parent_entity,
+                                             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.
+
+    This class adds methods to handle soft-deleted entities, allowing
+    retrieval and restoration of such entities.
+    """
+
+    def delete(self, entity: str | BaseEntity) -> None:
+        """Delete an entity.
+
+        Args:
+            entity: Unique identifier for the entity to delete or the entity instance itself.
+
+        Raises:
+            httpx.HTTPStatusError: If deletion fails or entity not found
+        """
+        self._make_entity_request('DELETE', entity)
+
+    def bulk_delete(self, entities: Sequence[str | BaseEntity]) -> None:
+        """Delete multiple entities.
+
+        Args:
+            entities: Sequence of unique identifiers for the entities to delete or the entity instances themselves.
+
+        Raises:
+            httpx.HTTPStatusError: If deletion fails or any entity not found
+        """
+        async def _delete_all_async():
+            async with aiohttp.ClientSession() as session:
+                tasks = [
+                    self._delete_async(entity, session)
+                    for entity in entities
+                ]
+                await asyncio.gather(*tasks)
+
+        loop = asyncio.get_event_loop()
+        loop.run_until_complete(_delete_all_async())
+
+    async def _delete_async(self,
+                            entity: str | BaseEntity,
+                            session: aiohttp.ClientSession | None = None) -> None:
+        """Asynchronously delete an entity by its ID.
+
+        Args:
+            entity: Unique identifier for the entity to delete or the entity instance itself.
+
+        Raises:
+            httpx.HTTPStatusError: If deletion fails or entity not found
+        """
+        async with self._make_entity_request_async('DELETE', entity,
+                                              session=session) as resp:
+            await resp.text()  # Consume response to complete request
+
+    # def get_deleted(self, **kwargs) -> Sequence[T]:
+    #     pass
+
+    # def restore(self, entity_id: str | BaseEntity) -> T:
+    #     pass
+
+
+class CreatableEntityApi(EntityBaseApi[T]):
+    """Extension of EntityBaseApi for entities that support creation.
+
+    This class adds methods to handle creation of new entities.
+    """
+
+    def _create(self, entity_data: dict[str, Any]) -> str | list[str | dict]:
+        """Create a new entity.
+
+        Args:
+            entity_data: Dictionary containing entity data for creation.
+
+        Returns:
+            The id of the created entity.
+
+        Raises:
+            httpx.HTTPStatusError: If creation fails.
+        """
+        response = self._make_request('POST', f'/{self.endpoint_base}', json=entity_data)
+        respdata = response.json()
+        if isinstance(respdata, str):
+            return respdata
+        if isinstance(respdata, list):
+            return respdata
+        if isinstance(respdata, dict):
+            return respdata.get('id')
+        return respdata
+
+    def create(self, *args, **kwargs) -> str | T:
+        raise NotImplementedError("Subclasses must implement the create method with their own custom parameters")
+
+
+class UpdatableEntityApi(EntityBaseApi[T]):
+    # def update(self, entity_id: str, entity_data: dict[str, Any]):
+    #     """Update an existing entity.
+
+    #     Args:
+    #         entity_id: Unique identifier for the entity.
+    #         entity_data: Dictionary containing updated entity data.
+
+    #     Returns:
+    #         Updated entity instance.
+
+    #     Raises:
+    #         httpx.HTTPStatusError: If update fails or entity not found.
+    #     """
+    #     self._make_entity_request('PUT', entity_id, json=entity_data)
+
+    def patch(self, entity: str | T, entity_data: dict[str, Any]):
+        """Partially update an existing entity.
+
+        Args:
+            entity: Unique identifier for the entity or the entity instance.
+            entity_data: Dictionary containing fields to update. Only provided fields will be updated.
+
+        Returns:
+            Updated entity instance.
+
+        Raises:
+            httpx.HTTPStatusError: If update fails or entity not found.
+        """
+        self._make_entity_request('PATCH', entity, json=entity_data)
+
+    def partial_update(self, entity: str | T, entity_data: dict[str, Any]):
+        """Alias for :py:meth:`patch` to partially update an entity."""
+        return self.patch(entity, entity_data)
+
+
+class CRUDEntityApi(CreatableEntityApi[T], UpdatableEntityApi[T], DeletableEntityApi[T]):
+    """Full CRUD API handler for entities supporting create, read, update, delete operations."""
+    pass

datamint/apihandler/annotation_api_handler.py

@@ -995,11 +995,11 @@ class AnnotationAPIHandler(BaseAPIHandler):
 
     def update_annotation_worklist(self,
                                    worklist_id: str,
-                                   frame_labels: list[str] = None,
-                                   image_labels: list[str] = None,
-                                   annotations: list[dict] = None,
-                                   status: Literal['new', 'updating', 'active', 'completed'] = None,
-                                   name: str = None,
+                                   frame_labels: list[str] | None = None,
+                                   image_labels: list[str] | None = None,
+                                   annotations: list[dict] | None = None,
+                                   status: Literal['new', 'updating', 'active', 'completed'] | None = None,
+                                   name: str | None = None,
                                    ):
         """
         Update the status of an annotation worklist.

datamint/apihandler/api_handler.py

@@ -1,15 +1,12 @@
 from .root_api_handler import RootAPIHandler
 from .annotation_api_handler import AnnotationAPIHandler
 from .exp_api_handler import ExperimentAPIHandler
+from deprecated.sphinx import deprecated
 
 
+@deprecated(reason="Please use `from datamint import Api` instead.", version="2.0.0")
 class APIHandler(RootAPIHandler, ExperimentAPIHandler, AnnotationAPIHandler):
     """
-    Import using this code:
-
-    .. code-block:: python
-    
-        from datamint import APIHandler
-        api = APIHandler()
+    Deprecated. Use `from datamint import Api` instead.
     """
     pass

datamint/apihandler/base_api_handler.py

@@ -15,7 +15,8 @@ import nibabel as nib
 from nibabel.filebasedimages import FileBasedImage as nib_FileBasedImage
 from datamint import configs
 import gzip
-from datamint.exceptions import DatamintException
+from datamint.exceptions import DatamintException, ResourceNotFoundError
+from deprecated.sphinx import deprecated
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -30,33 +31,7 @@ ResourceFields: TypeAlias = Literal['modality', 'created_by', 'published_by', 'p
 _PAGE_LIMIT = 5000
 
 
-class ResourceNotFoundError(DatamintException):
-    """
-    Exception raised when a resource is not found. 
-    For instance, when trying to get a resource by a non-existing id.
-    """
-
-    def __init__(self,
-                 resource_type: str,
-                 params: dict):
-        """ Constructor.
-
-        Args:
-            resource_type (str): A resource type.
-            params (dict): Dict of params identifying the sought resource.
-        """
-        super().__init__()
-        self.resource_type = resource_type
-        self.params = params
-
-    def set_params(self, resource_type: str, params: dict):
-        self.resource_type = resource_type
-        self.params = params
-
-    def __str__(self):
-        return f"Resource '{self.resource_type}' not found for parameters: {self.params}"
-
-
+@deprecated(reason="Please use `from datamint import Api` instead.", version="2.0.0")
 class BaseAPIHandler:
     """
     Class to handle the API requests to the Datamint API
@@ -68,6 +43,9 @@ class BaseAPIHandler:
                  root_url: Optional[str] = None,
                  api_key: Optional[str] = None,
                  check_connection: bool = True):
+        # deprecated
+        _LOGGER.warning("The class APIHandler is deprecated and will be removed in future versions. "
+                        "Please use `from datamint import Api` instead.")
         nest_asyncio.apply()  # For running asyncio in jupyter notebooks
         self.root_url = root_url if root_url is not None else configs.get_value(configs.APIURL_KEY)
         if self.root_url is None:

datamint/apihandler/dto/annotation_dto.py

@@ -152,7 +152,7 @@ class CreateAnnotationDto:
                  type: AnnotationType | str,
                  identifier: str,
                  scope: str,
-                 annotation_worklist_id: str,
+                 annotation_worklist_id: str | None = None,
                  value=None,
                  imported_from: str | None = None,
                  import_author: str | None = None,

datamint/apihandler/root_api_handler.py

@@ -6,7 +6,7 @@ from requests.exceptions import HTTPError
 import logging
 import asyncio
 import aiohttp
-from medimgkit.dicom_utils import anonymize_dicom, to_bytesio, is_dicom, is_dicom_report
+from medimgkit.dicom_utils import anonymize_dicom, to_bytesio, is_dicom, is_dicom_report, GeneratorWithLength
 from medimgkit import dicom_utils, standardize_mimetype
 from medimgkit.io_utils import is_io_object, peek
 from medimgkit.format_detection import guess_typez, guess_extension, DEFAULT_MIME_TYPE
@@ -185,9 +185,7 @@ class RootAPIHandler(BaseAPIHandler):
             resp_data = await self._run_request_async(request_params, session)
             if 'error' in resp_data:
                 raise DatamintException(resp_data['error'])
-            _LOGGER.info(f"Response on uploading {name}: {resp_data}")
-
-            _USER_LOGGER.info(f'"{name}" uploaded')
+            _LOGGER.debug(f"Response on uploading {name}: {resp_data}")
             return resp_data['id']
         except Exception as e:
             if 'name' in locals():
@@ -212,6 +210,7 @@ class RootAPIHandler(BaseAPIHandler):
                                       segmentation_files: Optional[list[dict]] = None,
                                       transpose_segmentation: bool = False,
                                       metadata_files: Optional[list[str | dict | None]] = None,
+                                      progress_bar: tqdm | None = None,
                                       ) -> list[str]:
         if on_error not in ['raise', 'skip']:
             raise ValueError("on_error must be either 'raise' or 'skip'")
@@ -225,6 +224,8 @@ class RootAPIHandler(BaseAPIHandler):
         async with aiohttp.ClientSession() as session:
             async def __upload_single_resource(file_path, segfiles: dict[str, list | dict],
                                                metadata_file: str | dict | None):
+                name = file_path.name if is_io_object(file_path) else file_path
+                name = os.path.basename(name)
                 rid = await self._upload_single_resource_async(
                     file_path=file_path,
                     mimetype=mimetype,
@@ -238,6 +239,12 @@ class RootAPIHandler(BaseAPIHandler):
                     publish=publish,
                     metadata_file=metadata_file,
                 )
+                if progress_bar:
+                    progress_bar.update(1)
+                    progress_bar.set_postfix(file=name)
+                else:
+                    _USER_LOGGER.info(f'"{name}" uploaded')
+
                 if segfiles is not None:
                     fpaths = segfiles['files']
                     names = segfiles.get('names', _infinite_gen(None))
@@ -295,18 +302,17 @@ class RootAPIHandler(BaseAPIHandler):
         if new_len != orig_len:
             _LOGGER.info(f"Assembled {new_len} dicom files out of {orig_len} files.")
             mapping_idx = [None] * len(files_path)
-            files_path = itertools.chain(dicoms_files_path, other_files_path)
+            
+            files_path = GeneratorWithLength(itertools.chain(dicoms_files_path, other_files_path), 
+                                             length=new_len + len(other_files_path))
             assembled = True
             for orig_idx, value in zip(dicom_original_idxs, dicoms_files_path.inverse_mapping_idx):
                 mapping_idx[orig_idx] = value
             for i, orig_idx in enumerate(others_original_idxs):
                 mapping_idx[orig_idx] = new_len + i
-            # mapping_idx = [[dicom_original_idxs[i] for i in idxlist]
-            #                for idxlist in dicoms_files_path.mapping_idx]
-            # mapping_idx += [[i] for i in others_original_idxs]
         else:
             assembled = False
-            # mapping_idx = [[i] for i in range(len(files_path))]
+            mapping_idx = [i for i in range(len(files_path))]
 
         return files_path, assembled, mapping_idx
 
@@ -391,7 +397,8 @@ class RootAPIHandler(BaseAPIHandler):
             transpose_segmentation=transpose_segmentation,
             modality=modality,
             assemble_dicoms=assemble_dicoms,
-            metadata=metadata
+            metadata=metadata,
+            progress_bar=False
         )
 
         return result[0]
@@ -412,7 +419,8 @@ class RootAPIHandler(BaseAPIHandler):
                          modality: Optional[str] = None,
                          assemble_dicoms: bool = True,
                          metadata: list[str | dict | None] | dict | str | None = None,
-                         discard_dicom_reports: bool = True
+                         discard_dicom_reports: bool = True,
+                         progress_bar: bool = False
                          ) -> list[str | Exception] | str | Exception:
         """
         Upload resources.
@@ -485,6 +493,11 @@ class RootAPIHandler(BaseAPIHandler):
             assemble_dicoms = assembled
         else:
             mapping_idx = [i for i in range(len(files_path))]
+        n_files = len(files_path)
+
+        if n_files <= 1:
+            # Disable progress bar for single file uploads
+            progress_bar = False
 
         if segmentation_files is not None:
             if assemble_dicoms:
@@ -513,22 +526,32 @@ class RootAPIHandler(BaseAPIHandler):
                             "segmentation_files['names'] must have the same length as segmentation_files['files'].")
 
         loop = asyncio.get_event_loop()
-        task = self._upload_resources_async(files_path=files_path,
-                                            mimetype=mimetype,
-                                            anonymize=anonymize,
-                                            anonymize_retain_codes=anonymize_retain_codes,
-                                            on_error=on_error,
-                                            tags=tags,
-                                            mung_filename=mung_filename,
-                                            channel=channel,
-                                            publish=publish,
-                                            segmentation_files=segmentation_files,
-                                            transpose_segmentation=transpose_segmentation,
-                                            modality=modality,
-                                            metadata_files=metadata,
-                                            )
-
-        resource_ids = loop.run_until_complete(task)
+        pbar = None
+        try:
+            if progress_bar:
+                pbar = tqdm(total=n_files, desc="Uploading resources", unit="file")
+
+            task = self._upload_resources_async(files_path=files_path,
+                                                mimetype=mimetype,
+                                                anonymize=anonymize,
+                                                anonymize_retain_codes=anonymize_retain_codes,
+                                                on_error=on_error,
+                                                tags=tags,
+                                                mung_filename=mung_filename,
+                                                channel=channel,
+                                                publish=publish,
+                                                segmentation_files=segmentation_files,
+                                                transpose_segmentation=transpose_segmentation,
+                                                modality=modality,
+                                                metadata_files=metadata,
+                                                progress_bar=pbar
+                                                )
+
+            resource_ids = loop.run_until_complete(task)
+        finally:
+            if pbar:
+                pbar.close()
+        
         _LOGGER.info(f"Resources uploaded: {resource_ids}")
 
         if publish_to is not None:
@@ -623,7 +646,9 @@ class RootAPIHandler(BaseAPIHandler):
         # get the project id by its name
         project = self.get_project_by_name(project_name)
         if 'error' in project:
-            raise ResourceNotFoundError('project', {'project_name': project_name})
+            project = self.get_project_by_id(project_name)
+            if 'error' in project:
+                raise ResourceNotFoundError('project', {'project_name': project_name})
 
         dataset_id = project['dataset_id']