Merge pull request #470 from superannotateai/custom_field_values

Custom field values

Author: VaghinakDev

docs/source/superannotate.sdk.rst

@@ -85,6 +85,8 @@ ______
 .. automethod:: superannotate.SAClient.create_custom_fields
 .. automethod:: superannotate.SAClient.get_custom_fields
 .. automethod:: superannotate.SAClient.delete_custom_fields
+.. automethod:: superannotate.SAClient.upload_custom_values
+.. automethod:: superannotate.SAClient.delete_custom_values
 
 ----------
 

src/superannotate/lib/app/interface/sdk_interface.py

@@ -5,6 +5,7 @@
 import tempfile
 from pathlib import Path
 from typing import Callable
+from typing import Dict
 from typing import Iterable
 from typing import List
 from typing import Optional
@@ -2571,7 +2572,6 @@ def set_annotation_statuses(
             raise AppException(response.errors)
         else:
             logger.info("Annotation statuses of items changed")
-        return response.data
 
     def download_annotations(
         self,
@@ -2666,7 +2666,8 @@ def create_custom_fields(self, project: NotEmptyStr, fields: dict):
         --------------------------------------
          field spec           spec value
         ==============  ======================
-        format          “email” or “date”
+        format          “email” (user@example.com) or “date” (YYYY-MM-DD)
+
         enum            list of strings
         ==============  ======================
         ::
@@ -2724,40 +2725,42 @@ def get_custom_fields(self, project: NotEmptyStr):
 
         Response Example:
         ::
-        {
-           "study_date": {
-               "type": "string",
-               "format": "date"
-           },
-           "patient_id": {
-               "type": "string"
-           },
-           "patient_sex": {
-               "type": "string",
-               "enum": [
-                   "male", "female"
-               ]
-           },
-           "patient_age": {
-               "type": "number"
-           },
-           "medical_specialist": {
-               "type": "string",
-               "format": "email"
-           },
-           "duration": {
-               "type": "number",
-               "minimum": 10
-           }
-        }
+            {
+               "study_date": {
+                   "type": "string",
+                   "format": "date"
+               },
+               "patient_id": {
+                   "type": "string"
+               },
+               "patient_sex": {
+                   "type": "string",
+                   "enum": [
+                       "male", "female"
+                   ]
+               },
+               "patient_age": {
+                   "type": "number"
+               },
+               "medical_specialist": {
+                   "type": "string",
+                   "format": "email"
+               },
+               "duration": {
+                   "type": "number",
+                   "minimum": 10
+               }
+            }
         """
         project_name, _ = extract_project_folder(project)
         response = self.controller.get_custom_schema(project_name=project)
         if response.errors:
             raise AppException(response.errors)
         return response.data
 
-    def delete_custom_fields(self, project: NotEmptyStr, fields: list):
+    def delete_custom_fields(
+        self, project: NotEmptyStr, fields: conlist(NotEmptyStr, min_items=1)
+    ):
         """Remove custom fields from a project’s custom metadata schema.
 
         :param project: project name  (e.g., “project1”)
@@ -2771,39 +2774,143 @@ def delete_custom_fields(self, project: NotEmptyStr, fields: list):
 
         Request Example:
         ::
-        client = SAClient()
-        client.delete_custom_fields(
-           project = "Medical Annotations",
-           fields = ["duration", patient_age]
-        )
+            client = SAClient()
+            client.delete_custom_fields(
+               project = "Medical Annotations",
+               fields = ["duration", patient_age]
+            )
 
         Response Example:
         ::
-        {
-            "study_date": {
-               "type": "string",
-               "format": "date"
-            },
-            "patient_id": {
-               "type": "string"
-            },
-            "patient_sex": {
-               "type": "string",
-               "enum": [
-                   "male", "female"
-               ]
-            },
-            "medical_specialist": {
-               "type": "string",
-               "format": "email"
+            {
+                "study_date": {
+                   "type": "string",
+                   "format": "date"
+                },
+                "patient_id": {
+                   "type": "string"
+                },
+                "patient_sex": {
+                   "type": "string",
+                   "enum": [
+                       "male", "female"
+                   ]
+                },
+                "medical_specialist": {
+                   "type": "string",
+                   "format": "email"
+                }
             }
-        }
 
         """
         project_name, _ = extract_project_folder(project)
         response = self.controller.delete_custom_schema(
-            project_name=project, fields=fields
+            project_name=project_name, fields=fields
         )
         if response.errors:
             raise AppException(response.errors)
         return response.data
+
+    def upload_custom_values(
+        self, project: NotEmptyStr, items: conlist(Dict[str, dict], min_items=1)
+    ):
+        """
+        Attach custom metadata to items.
+        SAClient.get_item_metadata(), SAClient.search_items(), SAClient.query() methods
+        will return the item metadata and custom metadata.
+
+        :param project: project name or folder path (e.g., “project1/folder1”)
+        :type project: str
+
+        :param items:  list of name-data pairs.
+            The key of each dict indicates an existing item name and the value represents the custom metadata dict.
+             The values for the corresponding keys will be added to an item or will be overridden.
+        :type items: list of dicts
+
+        :return: the count of succeeded items and the list of failed item names.
+        :rtype: dict
+
+        Request Example:
+        ::
+            client = SAClient()
+
+            items_values = [
+               {
+                   "image_1.png": {
+                       "study_date": "2021-12-31",
+                       "patient_id": "62078f8a756ddb2ca9fc9660",
+                       "patient_sex": "female",
+                       "medical_specialist": "robertboxer@ms.com"
+                   }
+               },
+               {
+                   "image_2.png": {
+                       "study_date": "2021-12-31",
+                       "patient_id": "62078f8a756ddb2ca9fc9661",
+                       "patient_sex": "female",
+                       "medical_specialist": "robertboxer@ms.com"
+                   }
+               },
+               {
+                   "image_3.png": {
+                       "study_date": "2011-10-05T14:48:00.000Z",
+                       "patient_": "62078f8a756ddb2ca9fc9660",
+                       "patient_sex": "female",
+                       "medical_specialist": "robertboxer"
+                   }
+               }
+            ]
+
+            client.upload_custom_values(
+               project = "Medical Annotations",
+               items = items_values
+            )
+        Response Example:
+        ::
+            {
+               "successful_items_count": 2,
+               "failed_items_names": ["image_3.png"]
+            }
+        """
+
+        project_name, folder_name = extract_project_folder(project)
+        response = self.controller.upload_custom_values(
+            project_name=project_name, folder_name=folder_name, items=items
+        )
+        if response.errors:
+            raise AppException(response.errors)
+        return response.data
+
+    def delete_custom_values(
+        self, project: NotEmptyStr, items: conlist(Dict[str, List[str]], min_items=1)
+    ):
+        """
+        Remove custom data from items
+
+        :param project: project name or folder path (e.g., “project1/folder1”)
+        :type project: str
+
+        :param items:   list of name-custom data dicts.
+         The key of each dict element indicates an existing item in the project root or folder.
+          The value should be the list of fields to be removed from the given item.
+          Please note, that the function removes pointed metadata from a given item.
+          To delete metadata for all items you should delete it from the custom metadata schema.
+          To override values for existing fields, use SAClient.upload_custom_values()
+        :type items: list of dicts
+
+        Request Example:
+        ::
+            client.delete_custom_values(
+                project = "Medical Annotations",
+                items = [
+                   {"image_1.png": ["study_date", "patient_sex"]},
+                   {"image_2.png": ["study_date", "patient_sex"]}
+                ]
+            )
+        """
+        project_name, folder_name = extract_project_folder(project)
+        response = self.controller.delete_custom_values(
+            project_name=project_name, folder_name=folder_name, items=items
+        )
+        if response.errors:
+            raise AppException(response.errors)

src/superannotate/lib/core/entities/__init__.py

@@ -1,11 +1,10 @@
 from lib.core.entities.base import AttachmentEntity
-from lib.core.entities.base import BaseEntity as TmpBaseEntity
+from lib.core.entities.base import BaseItemEntity
 from lib.core.entities.base import ProjectEntity
 from lib.core.entities.base import SettingEntity
 from lib.core.entities.base import SubSetEntity
 from lib.core.entities.integrations import IntegrationEntity
 from lib.core.entities.items import DocumentEntity
-from lib.core.entities.items import Entity
 from lib.core.entities.items import TmpImageEntity
 from lib.core.entities.items import VideoEntity
 from lib.core.entities.project_entities import AnnotationClassEntity
@@ -36,8 +35,7 @@
     # items
     "TmpImageEntity",
     "BaseEntity",
-    "TmpBaseEntity",
-    "Entity",
+    "BaseItemEntity",
     "VideoEntity",
     "DocumentEntity",
     # Utils

src/superannotate/lib/core/entities/base.py

@@ -40,7 +40,7 @@ class TimedBaseModel(BaseModel):
     updatedAt: StringDate = Field(None, alias="updatedAt")
 
 
-class BaseEntity(TimedBaseModel):
+class BaseItemEntity(TimedBaseModel):
     name: str
     path: Optional[str] = Field(
         None, description="Item’s path in SuperAnnotate project"
@@ -52,10 +52,25 @@ class BaseEntity(TimedBaseModel):
     entropy_value: Optional[float] = Field(description="Priority score of given item")
     createdAt: str = Field(description="Date of creation")
     updatedAt: str = Field(description="Update date")
+    custom_metadata: Optional[dict]
 
     class Config:
         extra = Extra.allow
 
+    def add_path(self, project_name: str, folder_name: str):
+        self.path = (
+            f"{project_name}{f'/{folder_name}' if folder_name != 'root' else ''}"
+        )
+        return self
+
+    @staticmethod
+    def map_fields(entity: dict) -> dict:
+        entity["url"] = entity.get("path")
+        entity["path"] = None
+        entity["annotator_email"] = entity.get("annotator_id")
+        entity["qa_email"] = entity.get("qa_id")
+        return entity
+
 
 class AttachmentEntity(BaseModel):
     name: Optional[str] = Field(default_factory=lambda: str(uuid.uuid4()))

src/superannotate/lib/core/entities/items.py

@@ -1,32 +1,13 @@
 from typing import Optional
 
-from lib.core.entities.base import BaseEntity
+from lib.core.entities.base import BaseItemEntity
 from lib.core.enums import ApprovalStatus
 from lib.core.enums import SegmentationStatus
 from pydantic import Extra
 from pydantic import Field
 
 
-class Entity(BaseEntity):
-    class Config:
-        extra = Extra.allow
-
-    def add_path(self, project_name: str, folder_name: str):
-        self.path = (
-            f"{project_name}{f'/{folder_name}' if folder_name != 'root' else ''}"
-        )
-        return self
-
-    @staticmethod
-    def map_fields(entity: dict) -> dict:
-        entity["url"] = entity.get("path")
-        entity["path"] = None
-        entity["annotator_email"] = entity.get("annotator_id")
-        entity["qa_email"] = entity.get("qa_id")
-        return entity
-
-
-class TmpImageEntity(Entity):
+class TmpImageEntity(BaseItemEntity):
     prediction_status: Optional[SegmentationStatus] = Field(
         SegmentationStatus.NOT_STARTED
     )
@@ -40,13 +21,13 @@ class Config:
         extra = Extra.ignore
 
 
-class VideoEntity(Entity):
+class VideoEntity(BaseItemEntity):
     approval_status: Optional[ApprovalStatus] = Field(None)
 
     class Config:
         extra = Extra.ignore
 
 
-class DocumentEntity(Entity):
+class DocumentEntity(BaseItemEntity):
     class Config:
         extra = Extra.ignore