Added search/get items

Author: VaghinakDev

docs/source/superannotate.sdk.rst

@@ -70,14 +70,22 @@ _______
 
 ----------
 
+Items
+______
+
+.. autofunction:: superannotate.query
+.. autofunction:: superannotate.search_items
+.. autofunction:: superannotate.get_item_metadata
+
+----------
+
 Images
 ______
 
 
 .. _ref_search_images:
 .. autofunction:: superannotate.search_images
 .. autofunction:: superannotate.search_images_all_folders
-.. autofunction:: superannotate.query
 .. autofunction:: superannotate.get_image_metadata
 .. autofunction:: superannotate.download_image
 .. autofunction:: superannotate.set_image_annotation_status
@@ -176,6 +184,28 @@ Export metadata example:
    }
 
 
+----------
+
+Item metadata
+_______________
+
+Item metadata example:
+
+.. code-block:: python
+
+  {
+   "name": "example.jpeg",
+   "path": "project/folder_1/meow.jpeg", // <proj>/<folder>/<item name>
+   "url": "https://sa-public-files.s3.../text_file_example_1.jpeg",
+   "annotation_status": "NotStarted",
+   "annotator_name": None,
+   "qa_name": None,
+   "entropy_value": None,
+   "createdAt": "2022-02-15T20:46:44.000Z",
+   "updatedAt": "2022-02-15T20:46:44.000Z"
+}
+
+
 ----------
 
 Image metadata
@@ -189,8 +219,8 @@ Image metadata example:
    {
       "name": "000000000001.jpg",
       "annotation_status": "Completed",
-      "prediction_status": 1,
-      "segmentation_status": 1,
+      "prediction_status": "NotStarted",
+      "segmentation_status": "NotStarted",
       "annotator_id": None,
       "annotator_name": None,
       "qa_id": None,

src/superannotate/__init__.py

@@ -58,6 +58,7 @@
 from superannotate.lib.app.interface.sdk_interface import get_image_annotations
 from superannotate.lib.app.interface.sdk_interface import get_image_metadata
 from superannotate.lib.app.interface.sdk_interface import get_integrations
+from superannotate.lib.app.interface.sdk_interface import get_item_metadata
 from superannotate.lib.app.interface.sdk_interface import (
     get_project_and_folder_metadata,
 )
@@ -78,6 +79,7 @@
 from superannotate.lib.app.interface.sdk_interface import search_folders
 from superannotate.lib.app.interface.sdk_interface import search_images
 from superannotate.lib.app.interface.sdk_interface import search_images_all_folders
+from superannotate.lib.app.interface.sdk_interface import search_items
 from superannotate.lib.app.interface.sdk_interface import search_models
 from superannotate.lib.app.interface.sdk_interface import search_projects
 from superannotate.lib.app.interface.sdk_interface import search_team_contributors
@@ -172,7 +174,9 @@
     "search_folders",
     "assign_folder",
     "unassign_folder",
-    # Entities Section
+    # Items Section
+    "get_item_metadata",
+    "search_items",
     "query",
     # Image Section
     "copy_images",

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

@@ -28,7 +28,7 @@
 from lib.app.interface.types import ProjectTypes
 from lib.app.interface.types import validate_arguments
 from lib.app.mixp.decorators import Trackable
-from lib.app.serializers import BaseSerializers
+from lib.app.serializers import BaseSerializer
 from lib.app.serializers import ImageSerializer
 from lib.app.serializers import ProjectSerializer
 from lib.app.serializers import SettingsSerializer
@@ -435,7 +435,7 @@ def search_folders(
         raise AppException(response.errors)
     data = response.data
     if return_metadata:
-        return [BaseSerializers(folder).serialize() for folder in data]
+        return [BaseSerializer(folder).serialize() for folder in data]
     return [folder.name for folder in data]
 
 
@@ -763,7 +763,7 @@ def get_project_metadata(
     for elem in "classes", "workflows", "contributors":
         if response.get(elem):
             metadata[elem] = [
-                BaseSerializers(attribute).serialize() for attribute in response[elem]
+                BaseSerializer(attribute).serialize() for attribute in response[elem]
             ]
         else:
             metadata[elem] = []
@@ -829,7 +829,7 @@ def search_annotation_classes(
     """
     project_name, folder_name = extract_project_folder(project)
     classes = Controller.get_default().search_annotation_classes(project_name, name_prefix)
-    classes = [BaseSerializers(attribute).serialize() for attribute in classes.data]
+    classes = [BaseSerializer(attribute).serialize() for attribute in classes.data]
     return classes
 
 
@@ -895,6 +895,11 @@ def get_image_metadata(
     :return: metadata of image
     :rtype: dict
     """
+    warning_msg = (
+        # TODO add link
+        "We're deprecating the get_image_metadata function. Please use get_item_metadata instead. Learn more. <link>."
+    )
+    logger.warning(warning_msg)
     project_name, folder_name = extract_project_folder(project)
     project = Controller.get_default()._get_project(project_name)
     response = Controller.get_default().get_image_metadata(project_name, folder_name, image_name)
@@ -1576,7 +1581,7 @@ def create_annotation_class(
     )
     if response.errors:
         raise AppException(response.errors)
-    return BaseSerializers(response.data).serialize()
+    return BaseSerializer(response.data).serialize()
 
 
 @Trackable
@@ -1659,7 +1664,7 @@ def create_annotation_classes_from_classes_json(
     )
     if response.errors:
         raise AppException(response.errors)
-    return [BaseSerializers(i).serialize() for i in response.data]
+    return [BaseSerializer(i).serialize() for i in response.data]
 
 
 @Trackable
@@ -2157,7 +2162,7 @@ def download_model(model: MLModel, output_dir: Union[str, Path]):
     if res.errors:
         logger.error("\n".join([str(error) for error in res.errors]))
     else:
-        return BaseSerializers(res.data).serialize()
+        return BaseSerializer(res.data).serialize()
 
 
 @Trackable
@@ -2940,7 +2945,7 @@ def get_integrations():
     if response.errors:
         raise AppException(response.errors)
     integrations = response.data
-    return BaseSerializers.serialize_iterable(integrations, ("name", "type", "root"))
+    return BaseSerializer.serialize_iterable(integrations, ("name", "type", "root"))
 
 
 @Trackable
@@ -2989,4 +2994,90 @@ def query(project: NotEmptyStr, query: Optional[NotEmptyStr]):
     response = Controller.get_default().query_entities(project_name, folder_name, query)
     if response.errors:
         raise AppException(response.errors)
-    return BaseSerializers.serialize_iterable(response.data)
+    return BaseSerializer.serialize_iterable(response.data)
+
+
+@Trackable
+@validate_arguments
+def get_item_metadata(
+        project: NotEmptyStr,
+        item_name: NotEmptyStr,
+):
+    """Returns item metadata
+
+    :param project: project name or folder path (e.g., “project1/folder1”)
+    :type project: str
+
+    :param item_name: item name
+    :type item_name: str
+
+    :return: metadata of item
+    :rtype: dict
+    """
+    project_name, folder_name = extract_project_folder(project)
+    response = Controller.get_default().get_item(project_name, folder_name, item_name)
+    if response.errors:
+        raise AppException(response.errors)
+    return BaseSerializer(response.data).serialize()
+
+
+@Trackable
+@validate_arguments
+def search_items(
+        project: NotEmptyStr,
+        name_contains: NotEmptyStr = None,
+        annotation_status: Optional[AnnotationStatuses] = None,
+        annotator_email: Optional[NotEmptyStr] = None,
+        qa_email: Optional[NotEmptyStr] = None,
+        recursive: bool = False
+
+):
+    """Search items by filtering criteria.
+
+
+    :param project: project name or folder path (e.g., “project1/folder1”).
+     If recursive=False=True, then only the project name is required.
+    :type project: str
+
+    :param name_contains:  Returns those items, where the given string is found anywhere within an item’s name.
+     If None, all items returned, in accordance with the recursive=False parameter.
+    :type name_contains: str
+
+    :param annotation_status: if not None, filters items by annotation status.
+                            Values are:
+                                “NotStarted”
+                                “InProgress”
+                                “QualityCheck”
+                                “Returned”
+                                “Completed”
+                                “Skipped”
+    :type annotation_status: str
+
+
+    :param annotator_email: returns those items’ names that are assigned to the specified annotator.
+     If None, all items are returned. Strict equal.
+    :type annotator_email: str
+
+    :param qa_email:  returns those items’ names that are assigned to the specified QA.
+     If None, all items are returned. Strict equal.
+    :type qa_email: str
+
+    :param recursive: search in the project’s root and all of its folders.
+     If False search only in the project’s root or given directory.
+    :type recursive: bool
+
+    :return: items metadata
+    :rtype: list of dicts
+    """
+    project_name, folder_name = extract_project_folder(project)
+    response = Controller.get_default().list_items(
+        project_name, folder_name,
+        name_contains=name_contains,
+        annotation_status=annotation_status,
+        annotator_email=annotator_email,
+        qa_email=qa_email,
+        recursive=recursive
+    )
+    if response.errors:
+        raise AppException(response.errors)
+    return BaseSerializer.serialize_iterable(response.data)

src/superannotate/lib/app/mixp/decorators.py

@@ -1,5 +1,6 @@
 import functools
 import sys
+from inspect import signature
 
 from lib import get_default_controller
 from mixpanel import Mixpanel
@@ -9,19 +10,17 @@
 from .utils import parsers
 
 
-# TODO:
-try:
-    if "api.annotate.online" in get_default_controller()._backend_client.api_url:
-        TOKEN = "ca95ed96f80e8ec3be791e2d3097cf51"
-    else:
-        TOKEN = "e741d4863e7e05b1a45833d01865ef0d"
-except AttributeError as e:
-    TOKEN = "e741d4863e7e05b1a45833d01865ef0d"
-mp = Mixpanel(TOKEN)
-
 logger = get_default_logger()
 
 
+def get_mp_instance() -> Mixpanel:
+    try:
+        if "api.annotate.online" in get_default_controller()._backend_client.api_url:
+            return Mixpanel("ca95ed96f80e8ec3be791e2d3097cf51")
+    finally:
+        return Mixpanel("e741d4863e7e05b1a45833d01865ef0d")
+
+
 def get_default(team_name, user_id, project_name=None):
     return {
         "SDK": True,
@@ -47,6 +46,12 @@ def __init__(self, function, initial=False):
             self.track()
         functools.update_wrapper(self, function)
 
+    @staticmethod
+    def extract_arguments(function, *args, **kwargs) -> dict:
+        bound_arguments = signature(function).bind(*args, **kwargs)
+        bound_arguments.apply_defaults()
+        return dict(bound_arguments.arguments)
+
     @property
     def team(self):
         return get_default_controller().get_team()
@@ -58,7 +63,8 @@ def track(self, *args, **kwargs):
                 Trackable.INITIAL_LOGGED = True
                 self._success = True
             else:
-                data = getattr(parsers, self.function.__name__)(*args, **kwargs)
+                arguments = self.extract_arguments(self.function, *args, **kwargs)
+                data = getattr(parsers, self.function.__name__)(**arguments)
             event_name = data["event_name"]
             properties = data["properties"]
             team_data = self.team.data
@@ -74,7 +80,7 @@ def track(self, *args, **kwargs):
             properties = {**default, **properties}
 
             if "pytest" not in sys.modules:
-                mp.track(user_id, event_name, properties)
+                get_mp_instance().track(user_id, event_name, properties)
         except Exception as _:
             pass
 

src/superannotate/lib/app/mixp/utils/parsers.py

@@ -1069,7 +1069,6 @@ def search_folders(*args, **kwargs):
 
 
 def aggregate_annotations_as_df(*args, **kwargs):
-
     folder_names = kwargs.get("folder_names", "empty")
     if folder_names == "empty":
         folder_names = args[5:6]
@@ -1265,3 +1264,54 @@ def attach_items_from_integrated_storage(*args, **kwargs):
             "folder_path": bool(folder_path)
         },
     }
+
+
+def query(**kwargs):
+    project = kwargs["project"]
+    query_str = kwargs["project"]
+    project_name, folder_name = extract_project_folder(project)
+    Controller.get_default().get_project_metadata(project_name)
+    return {
+        "event_name": "attach_items_from_integrated_storage",
+        "properties": {
+            "project_type": ProjectType.get_name(project.project_type),
+            "query": query_str
+
+        },
+    }
+
+
+def get_item_metadata(**kwargs):
+    project = kwargs["project"]
+    project_name, _ = extract_project_folder(project)
+    Controller.get_default().get_project_metadata(project_name)
+    return {
+        "event_name": "attach_items_from_integrated_storage",
+        "properties": {
+            "project_type": ProjectType.get_name(project.project_type),
+        },
+    }
+
+
+def search_items(**kwargs):
+    project = kwargs["project"]
+    name_contains = kwargs["name_contains"]
+    annotation_status = kwargs["annotation_status"]
+    annotator_email = kwargs["annotator_email"]
+    qa_email = kwargs["qa_email"]
+    recursive = kwargs["recursive"]
+    project_name, folder_name = extract_project_folder(project)
+    Controller.get_default().get_project_metadata(project_name)
+    return {
+        "event_name": "attach_items_from_integrated_storage",
+        "properties": {
+            "project_type": ProjectType.get_name(project.project_type),
+            "query": query,
+            "name_contains": len(name_contains) if name_contains else False,
+            "annotation_status": annotation_status if annotation_status else False,
+            "annotator_email": bool(annotator_email),
+            "qa_email": bool(qa_email),
+            "recursive": bool(recursive),
+
+        },
+    }