Feat/better client module by Lucashsmello · Pull Request #55 · SonanceAI/datamint-python-api

Lucashsmello · 2025-09-11T11:59:38Z

More intuitive use: All project-related functions are located at api.projects.*

Separation of Concerns:
- Entities (e.g., Resource, Project, Annotation) are defined as distinct classes, decoupling data models from logic.
- Each API resource has its own handler class (e.g., ResourcesApi, ProjectsApi), replacing the monolithic APIHandler.
Reusability & Abstraction:
- Generic base classes (EntityBaseApi) and CRUD variants (CreatableEntityApi, CRUDEntityApi) centralize common operations.
- Reduces code duplication and enforces consistent patterns.
Maintainability & Scalability:
- Modular endpoint classes make code easier to debug, extend, and scale.
- Changes are localized to single files, unlike the old interdependent APIHandler.
Clearer Structure:
- Code cleanly maps to REST endpoints (e.g., /projects/{id}/resources in ProjectsApi).
- Improves readability and discoverability compared to the older design.

- Added streaming request support in BaseApi for large file handling. - Improved error handling with ResourceNotFoundError in API requests. - Updated ApiConfig to include detailed attribute documentation. - Enhanced entity request methods for better clarity and functionality. - Adjusted entity serialization methods to suppress warnings for unknown fields.

- Added `Api` class to serve as the main API client, providing access to endpoint handlers. - Introduced `AnnotationsApi` and `ResourcesApi` classes for handling annotation and resource-related API calls. - Enhanced `BaseApi` with asynchronous request - Created `Annotation` and `Resource` entity models to represent data structures returned by the API. - Implemented methods for uploading resources, including support for DICOM files and metadata handling.

- Added `Api` class to replace `APIHandler` for improved API interactions. - Updated `ApiConfig` to use `server_url` instead of `base_url`. - Introduced `AnnotationsApi` and `ResourcesApi` with pagination support. - Implemented asynchronous methods for uploading segmentations and files. - Enhanced error handling and logging for better debugging. - Updated entity models to support optional fields and missing values. - Added DTOs for annotations to streamline data handling. - Refactored upload logic in `datamint_upload.py` to utilize new API structure.

…ersion functionalities

…BaseApi

…operations

…and improved error handling - Added `upload_segmentations` method to `AnnotationsApi` for uploading segmentations with detailed parameter handling. - Refactored existing upload methods in `AnnotationsApi` to use a unified async request method. - Introduced `upload_resource` method in `ResourcesApi` for single file uploads, simplifying the interface. - Updated `upload_resources` to enforce multiple file uploads and improved parameter processing. - Enhanced error handling across API methods, ensuring exceptions are raised appropriately. - Improved documentation and examples in the API and notebooks for clarity and usability. - Bumped version to 2.0.0 to reflect significant changes and enhancements.

…arning messages

- Updated import paths for Annotation and DatasetInfo entities. - Modified the DatamintDataset class to use new image resizing method. - Added new DatasetInfo model for dataset representation. - Enhanced Annotation model with additional properties and methods for better usability. - Updated documentation to reflect changes in API class names and structure. - Removed deprecated Experiment class documentation and related examples. - Improved resource upload and management methods in the API client. - Adjusted API key setup instructions to align with new class structure.

Enhances API implementations by refining type annotations, improving parameter type handling, and addressing potential edge cases. Removes unused or commented-out code for better code clarity. Adds new methods to extend functionality, such as resource status updates and project retrieval with archived inclusion. Optimizes error handling for consistency and implements minor adjustments to payload processing. Improves dataset handling by supporting additional file types and ensuring compatibility with various formats.

Copilot

Pull Request Overview

This PR introduces a major architectural refactor to modernize the DataMint Python API client. It replaces the monolithic APIHandler class with a modular API client architecture that provides better separation of concerns and improved usability.

Implements a new modular API client with dedicated endpoint handlers (Api.resources, Api.projects, etc.)
Introduces Pydantic-based entity models for type safety and data validation
Adds comprehensive base classes for consistent CRUD operations across endpoints
Updates documentation, examples, and notebooks to use the new API structure

Reviewed Changes

Copilot reviewed 46 out of 48 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pyproject.toml	Version bump to 2.0.0 and updated dependencies
notebooks/upload_data.ipynb	Complete migration from APIHandler to new Api client with updated examples
docs/	Documentation restructuring and updates for new API structure
datamint/entities/	New Pydantic entity models for type-safe data handling
datamint/api/	New modular API client architecture with base classes and endpoint handlers
datamint/dataset/	Updated to use new API client and entity models
datamint/apihandler/	Marked as deprecated with migration warnings

Comments suppressed due to low confidence (4)

datamint/dataset/base_dataset.py:1

Variable name has a typo: last_updaded_at should be last_updated_at.

import os

datamint/dataset/base_dataset.py:1

Variable name has a typo: last_updaded_at should be last_updated_at (multiple occurrences).

import os

datamint/dataset/base_dataset.py:1

Variable name has a typo: last_updaded_at should be last_updated_at (multiple occurrences).

import os

datamint/dataset/base_dataset.py:1

Variable name has a typo: last_updaded_at should be last_updated_at (multiple occurrences).

import os

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-09-18T20:02:51Z

+
+    async def _upload_segmentations_async(self,
+                                          resource: str | Resource,
+                                          frame_index: int | Sequence [int] | None,


There's an extra space in the type annotation. It should be Sequence[int] instead of Sequence [int].

Suggested change

frame_index: int | Sequence [int] | None,

frame_index: int | Sequence[int] | None,

Copilot · 2025-09-18T20:02:51Z

-                                                   metadata=metadata_files,
-                                                   progress_bar=True
-                                                   )
+            print('>>>', segfiles)


Debug print statement should be removed from production code. This appears to be leftover debugging code.

Suggested change

print('>>>', segfiles)

_LOGGER.debug(f"Segmentation files: {segfiles}")

Copilot · 2025-09-18T20:02:51Z

+        if 'scope' not in converted_data:
+            converted_data['scope'] = 'image' if converted_data.get('frame_index') is None else 'frame'
+
+        if converted_data['annotation_type'] in ['segmentation']:


The list ['segmentation'] contains only one item. Consider using a simple string comparison == 'segmentation' for better readability and performance.

Suggested change

if converted_data['annotation_type'] in ['segmentation']:

if converted_data['annotation_type'] == 'segmentation':

Lucashsmello added 13 commits September 5, 2025 17:45

base classes

6f2a75b

Implement ProjectsApi class for project-related API endpoints

831ac81

feat: Enhance resource and annotation APIs with new download and conv…

838acf6

…ersion functionalities

feat: Add asynchronous entity deletion and request handling in Entity…

ffdc06d

…BaseApi

feat: Implement Channels API and enhance entity management with CRUD …

45d04d1

…operations

feat: Add Users API

6e1a68d

feat: Mark APIHandler and BaseAPIHandler as deprecated with updated w…

f08b71b

…arning messages

Lucashsmello requested a review from Copilot September 18, 2025 20:01

Lucashsmello merged commit e9e7a8c into main Sep 18, 2025
2 of 3 checks passed

Copilot AI reviewed Sep 18, 2025

View reviewed changes

Navigation Menu

Uh oh!

Feat/better client module - #55

Feat/better client module#55
Lucashsmello merged 13 commits into
mainfrom
feat/better-client-module

Lucashsmello commented Sep 11, 2025 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Sep 18, 2025

Uh oh!

Copilot AI Sep 18, 2025

Uh oh!

Copilot AI Sep 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	frame_index: int \| Sequence [int] \| None,
	frame_index: int \| Sequence[int] \| None,

	print('>>>', segfiles)
	_LOGGER.debug(f"Segmentation files: {segfiles}")

	if converted_data['annotation_type'] in ['segmentation']:
	if converted_data['annotation_type'] == 'segmentation':

Uh oh!

Conversation

Lucashsmello commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Lucashsmello commented Sep 11, 2025 •

edited

Loading