Merge pull request #455 from superannotateai/doc_updates

Updated the docs

Author: VaghinakDev

docs/source/index.rst

@@ -29,7 +29,9 @@ SuperAnnotate Python SDK allows access to the platform without web browser:
 
 .. code-block:: python
 
-   import superannotate as sa
+   from superannotate import SAClient
+
+   sa = SAClient()
 
    sa.create_project("Example Project 1", "example", "Vector")
 

docs/source/superannotate.sdk.rst

@@ -8,14 +8,12 @@ API Reference
 Remote functions
 ----------------
 
-Initialization and authentication
+Instantiation and authentication
 _________________________________
 
-.. automethod:: superannotate.SAClient.__init__
+.. autoclass:: superannotate.SAClient
 
 
-.. _ref_projects:
-
 Projects
 ________
 
@@ -93,8 +91,6 @@ ______
 
 .. _ref_search_images:
 .. automethod:: superannotate.SAClient.download_image
-.. automethod:: superannotate.SAClient.set_image_annotation_status
-.. automethod:: superannotate.SAClient.set_images_annotation_statuses
 .. automethod:: superannotate.SAClient.download_image_annotations
 .. automethod:: superannotate.SAClient.upload_image_annotations
 .. automethod:: superannotate.SAClient.copy_image

docs/source/tutorial.sdk.rst

@@ -77,14 +77,14 @@ Include the package in your Python code:
 
 .. code-block:: python
 
-   import superannotate as sa
+   from superannotate import SAClient
 
 SDK is ready to be used if default location config file was created using 
 the :ref:`CLI init <ref_cli_init>`. Otherwise to authenticate SDK with the :ref:`custom config file <ref_custom_config_file>`:
 
 .. code-block:: python
 
-   sa.init("<path_to_config_json>")
+   sa = SAClient(config_path="<path_to_config_json>")
 
 Creating a project
 ____________________________
@@ -273,80 +273,81 @@ You can find more information annotation format conversion :ref:`here <ref_conve
 
 .. code-block:: python
 
-   import superannotate as sa
+   from superannotate import export_annotation
+   from superannotate import import_annotation
 
     # From SA format to COCO panoptic format
-    sa.export_annotation(
+    export_annotation(
        "tests/converter_test/COCO/input/fromSuperAnnotate/cats_dogs_panoptic_segm",
        "tests/converter_test/COCO/output/panoptic",
        "COCO", "panoptic_test", "Pixel","panoptic_segmentation"
     )
 
     # From COCO keypoints detection format to SA annotation format
-    sa.import_annotation(
+    import_annotation(
        "tests/converter_test/COCO/input/toSuperAnnotate/keypoint_detection",
        "tests/converter_test/COCO/output/keypoints",
        "COCO", "person_keypoints_test", "Vector", "keypoint_detection"
     )
 
     # Pascal VOC annotation format to SA annotation format
-    sa.import_annotation(
+    import_annotation(
        "tests/converter_test/VOC/input/fromPascalVOCToSuperAnnotate/VOC2012",
        "tests/converter_test/VOC/output/instances",
        "VOC", "instances_test", "Pixel", "instance_segmentation"
     )
 
     # YOLO annotation format to SA annotation format
-    sa.import_annotation(
+    import_annotation(
       'tests/converter_test/YOLO/input/toSuperAnnotate',
       'tests/converter_test/YOLO/output',
       'YOLO', '', 'Vector', 'object_detection'
       )
 
     # LabelBox annotation format to SA annotation format
-    sa.import_annotation(
+    import_annotation(
        "tests/converter_test/LabelBox/input/toSuperAnnotate/",
        "tests/converter_test/LabelBox/output/objects/",
        "LabelBox", "labelbox_example", "Vector", "object_detection"
     )
 
     # Supervisely annotation format to SA annotation format
-    sa.import_annotation(
+    import_annotation(
        "tests/converter_test/Supervisely/input/toSuperAnnotate",
        "tests/converter_test/Supervisely/output",
        "Supervisely", "", "Vector", "vector_annotation"
     )
 
     # DataLoop annotation format to SA annotation format
-    sa.import_annotation(
+    import_annotation(
        "tests/converter_test/DataLoop/input/toSuperAnnotate",
        "tests/converter_test/DataLoop/output",
        "DataLoop", "", "Vector", "vector_annotation"
     )
 
     # VGG annotation format to SA annotation format
-    sa.import_annotation(
+    import_annotation(
        "tests/converter_test/VGG/input/toSuperAnnotate",
        "tests/converter_test/VGG/output",
        "VGG", "vgg_test", "Vector", "instance_segmentation"
     )
 
     # VoTT annotation format to SA annotation format
-    sa.import_annotation(
+    import_annotation(
        "tests/converter_test/VoTT/input/toSuperAnnotate",
        "tests/converter_test/VoTT/output",
        "VoTT", "", "Vector", "vector_annotation"
     )
 
     # GoogleCloud annotation format to SA annotation format
-    sa.import_annotation(
+    import_annotation(
        "tests/converter_test/GoogleCloud/input/toSuperAnnotate",
        "tests/converter_test/GoogleCloud/output",
        "GoogleCloud", "image_object_detection", "Vector", "object_detection"
     )
 
     # GoogleCloud annotation format to SA annotation format
-    sa.import_annotation(
+    import_annotation(
        "tests/converter_test/SageMaker/input/toSuperAnnotate",
        "tests/converter_test/SageMaker/output",
        "SageMaker", "test-obj-detect", "Vector", "object_detection"

requirements_dev.txt

@@ -1,2 +1,2 @@
-superannotate_schemas>=v1.0.43dev5
+superannotate_schemas>=v1.0.45dev1
 

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

@@ -62,6 +62,18 @@
 
 
 class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
+    """Create SAClient instance to authorize SDK in a team scope.
+    In case of no argument has been provided, SA_TOKEN environmental variable
+    will be checked or $HOME/.superannotate/config.json will be used.
+
+    :param token: team token
+    :type token: str
+
+    :param config_path: path to config file
+    :type config_path: path-like (str or Path)
+
+    """
+
     def __init__(
         self,
         token: str = None,
@@ -618,37 +630,6 @@ def pin_image(
             is_pinned=int(pin),
         )
 
-    def set_images_annotation_statuses(
-        self,
-        project: Union[NotEmptyStr, dict],
-        annotation_status: NotEmptyStr,
-        image_names: Optional[List[NotEmptyStr]] = None,
-    ):
-        """Sets annotation statuses of images
-
-        :param project: project name or folder path (e.g., "project1/folder1")
-        :type project: str
-        :param image_names: image names. If None, all the images in the project will be used
-        :type image_names: list of str
-        :param annotation_status: annotation status to set,
-               should be one of NotStarted InProgress QualityCheck Returned Completed Skipped
-        :type annotation_status: str
-        """
-        warning_msg = (
-            "We're deprecating the set_images_annotation_statuses function. Please use set_annotation_statuses instead. "
-            "Learn more. \n"
-            "https://superannotate.readthedocs.io/en/stable/superannotate.sdk.html#superannotate.set_annotation_statuses"
-        )
-        logger.warning(warning_msg)
-        warnings.warn(warning_msg, DeprecationWarning)
-        project_name, folder_name = extract_project_folder(project)
-        response = self.controller.set_images_annotation_statuses(
-            project_name, folder_name, image_names, annotation_status
-        )
-        if response.errors:
-            raise AppException(response.errors)
-        logger.info("Annotations status of images changed")
-
     def delete_images(
         self, project: Union[NotEmptyStr, dict], image_names: Optional[List[str]] = None
     ):
@@ -682,9 +663,7 @@ def delete_images(
             f"Images deleted in project {project_name}{'/' + folder_name if folder_name else ''}"
         )
 
-    def delete_items(
-        self, project: str, items: Optional[List[str]] = None
-    ):
+    def delete_items(self, project: str, items: Optional[List[str]] = None):
         """Delete items in a given project.
 
         :param project: project name or folder path (e.g., "project1/folder1")
@@ -700,7 +679,6 @@ def delete_items(
         if response.errors:
             raise AppException(response.errors)
 
-
     def assign_items(
         self, project: Union[NotEmptyStr, dict], items: List[str], user: str
     ):
@@ -1427,41 +1405,6 @@ def download_export(
             raise AppException(response.errors)
         logger.info(response.data)
 
-    def set_image_annotation_status(
-        self,
-        project: Union[NotEmptyStr, dict],
-        image_name: NotEmptyStr,
-        annotation_status: NotEmptyStr,
-    ):
-        """Sets the image annotation status
-
-        :param project: project name or folder path (e.g., "project1/folder1")
-        :type project: str
-        :param image_name: image name
-        :type image_name: str
-        :param annotation_status: annotation status to set,
-               should be one of NotStarted InProgress QualityCheck Returned Completed Skipped
-        :type annotation_status: str
-
-        :return: metadata of the updated image
-        :rtype: dict
-        """
-        warning_msg = (
-            "We're deprecating the set_image_annotation_status function. Please use set_annotation_statuses instead. "
-            "Learn more. \n"
-            "https://superannotate.readthedocs.io/en/stable/superannotate.sdk.html#superannotate.set_annotation_statuses"
-        )
-        logger.warning(warning_msg)
-        warnings.warn(warning_msg, DeprecationWarning)
-        project_name, folder_name = extract_project_folder(project)
-        response = self.controller.set_images_annotation_statuses(
-            project_name, folder_name, [image_name], annotation_status
-        )
-        if response.errors:
-            raise AppException(response.errors)
-        image = self.controller.get_item(project_name, folder_name, image_name).data
-        return BaseSerializer(image).serialize()
-
     def set_project_workflow(
         self, project: Union[NotEmptyStr, dict], new_workflow: List[dict]
     ):
@@ -1720,7 +1663,7 @@ def download_model(self, model: MLModel, output_dir: Union[str, Path]):
 
         :param model: the model that needs to be downloaded
         :type  model: dict
-        :param output_dir: the directiory in which the files will be saved
+        :param output_dir: the directory in which the files will be saved
         :type output_dir: str
         :return: the metadata of the model
         :rtype: dict

src/superannotate/lib/core/usecases/images.py

@@ -2063,61 +2063,6 @@ def execute(self):
         return self._response
 
 
-class SetImageAnnotationStatuses(BaseUseCase):
-    CHUNK_SIZE = 500
-
-    def __init__(
-        self,
-        service: SuperannotateServiceProvider,
-        projects: BaseReadOnlyRepository,
-        image_names: list,
-        team_id: int,
-        project_id: int,
-        folder_id: int,
-        images_repo: BaseManageableRepository,
-        annotation_status: int,
-    ):
-        super().__init__()
-        self._service = service
-        self._projects = projects
-        self._image_names = image_names
-        self._team_id = team_id
-        self._project_id = project_id
-        self._folder_id = folder_id
-        self._annotation_status = annotation_status
-        self._images_repo = images_repo
-
-    def validate_project_type(self):
-        project = self._projects.get_one(uuid=self._project_id, team_id=self._team_id)
-        if project.type in constances.LIMITED_FUNCTIONS:
-            raise AppValidationException(constances.LIMITED_FUNCTIONS[project.type])
-
-    def execute(self):
-        if self.is_valid():
-            if self._image_names is None:
-                condition = (
-                    Condition("team_id", self._team_id, EQ)
-                    & Condition("project_id", self._project_id, EQ)
-                    & Condition("folder_id", self._folder_id, EQ)
-                )
-                self._image_names = [
-                    image.name for image in self._images_repo.get_all(condition)
-                ]
-            for i in range(0, len(self._image_names), self.CHUNK_SIZE):
-                status_changed = self._service.set_images_statuses_bulk(
-                    image_names=self._image_names[
-                        i : i + self.CHUNK_SIZE  # noqa: E203
-                    ],
-                    team_id=self._team_id,
-                    project_id=self._project_id,
-                    folder_id=self._folder_id,
-                    annotation_status=self._annotation_status,
-                )
-                if not status_changed:
-                    self._response.errors = AppException("Failed to change status.")
-        return self._response
-
-
 class CreateAnnotationClassUseCase(BaseUseCase):
     def __init__(
         self,

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

@@ -9,6 +9,7 @@
 from lib.core.entities import DocumentEntity
 from lib.core.entities import Entity
 from lib.core.entities import FolderEntity
+from lib.core.entities import ImageEntity
 from lib.core.entities import ProjectEntity
 from lib.core.entities import SubSetEntity
 from lib.core.entities import TmpImageEntity
@@ -22,11 +23,11 @@
 from lib.core.serviceproviders import SuperannotateServiceProvider
 from lib.core.usecases.base import BaseReportableUseCase
 from lib.core.usecases.base import BaseUseCase
-from lib.core.entities import ImageEntity
 from superannotate.logger import get_default_logger
 
 logger = get_default_logger()
 
+
 class GetBulkItems(BaseUseCase):
     def __init__(
         self,
@@ -56,11 +57,12 @@ def execute(self):
 
             if not response.ok:
                 raise AppException(response.error)
-            #TODO stop using Image Entity when it gets deprecated and from_dict gets implemented for items
+            # TODO stop using Image Entity when it gets deprecated and from_dict gets implemented for items
             res += [ImageEntity.from_dict(**item) for item in response.data]
         self._response.data = res
         return self._response
 
+
 class GetItem(BaseReportableUseCase):
     def __init__(
         self,
@@ -133,7 +135,7 @@ def __init__(
 
     def validate_query(self):
         if self._project.sync_status != constants.ProjectState.SYNCED.value:
-            raise AppException("Data is not synced.")
+            raise AppException("Project data is not synced.")
         if self._query:
             response = self._backend_client.validate_saqul_query(
                 self._project.team_id, self._project.id, self._query
@@ -722,6 +724,7 @@ def execute(self):
                     break
         return self._response
 
+
 class DeleteItemsUseCase(BaseUseCase):
     CHUNK_SIZE = 1000