superannotate 4.5.9__tar.gz → 4.6.0__tar.gz

{superannotate-4.5.9/src/superannotate.egg-info → superannotate-4.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: superannotate
-Version: 4.5.9
+Version: 4.6.0
 Summary: Python SDK to SuperAnnotate platform
 Home-page: https://github.com/superannotateai/superannotate-python-sdk
 Author: SuperAnnotate AI
@@ -19,12 +19,12 @@ Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: pydantic~=2.5
 Requires-Dist: pydantic-extra-types~=2.11
-Requires-Dist: aiohttp~=3.8
+Requires-Dist: aiohttp~=3.14
 Requires-Dist: boto3~=1.42
 Requires-Dist: opencv-python-headless~=4.7
 Requires-Dist: plotly~=6.5
 Requires-Dist: pandas~=2.0
-Requires-Dist: pillow~=12.1
+Requires-Dist: pillow~=12.3
 Requires-Dist: tqdm~=4.66
 Requires-Dist: requests~=2.33
 Requires-Dist: aiofiles~=25.1
@@ -66,7 +66,7 @@ Authentication
     # by environment variable SA_TOKEN
     sa_client = SAClient()
     # by token
-    sa_client = SAClient(token='<team token>')
+    sa_client = SAClient(token='<API key>')
     # by config file
     # default path is ~/.superannotate/config.ini
     sa_client = SAClient(config_path='~/.superannotate/dev_config.ini')
@@ -77,8 +77,9 @@ config.ini example
 .. code-block:: python
 
     [DEFAULT]
-    SA_TOKEN = <Token>
+    SA_TOKEN = <API key>
     LOGGING_LEVEL = INFO
+    LOGGING_PATH = /Users/username/data/superannotate_logs
 
 
 Using superannotate
@@ -89,7 +90,7 @@ Using superannotate
     from superannotate import SAClient
 
 
-    sa_client =SAClient()
+    sa_client = SAClient()
 
     project = 'Dogs'
 
@@ -145,34 +146,6 @@ Windows (`Anaconda <https://www.anaconda.com/products/individual#windows>`__
 ) platforms.
 
 
-Supported Features
-------------------
-
-- search/get/create/clone/update/delete projects
-- search/get/create/delete folders
-- assign folders to project contributors
-- upload items to a project from a local or AWS S3 folder
-- attach items by URL or from an integrated storage, meanwhile keeping them secure in your cloud provider
-- get integrated cloud storages
-- upload annotations (also from local or AWS S3 folder)
-- delete annotations
-- set items annotations statuses
-- get/download/export annotations from a project (also to a local or AWS S3 folder)
-- invite/search team contributors or add contributors to a specific project
-- search/get/copy/move items in a project
-- query items using SA Query Language
-- define custom metadata for items and upload custom values (query based on your custom metadata)
-- upload priority scores
-- get available subsets (sets of segregated items), query items in a subset or add items to a subset
-- assign or anassign items to project contributors
-- download an image that has been uploaded to project
-- search/create/download/delete project annotation classes
-- search/download models
-- run predictions
-- convert annotations from/to COCO format
-- convert annotation from VOC, SuperVisely, LabelBox, DataLoop, VGG, VoTT, SageMaker, GoogleCloud, YOLO formats
-- CLI commands for simple tasks
-
 Questions and Issues
 --------------------
 

{superannotate-4.5.9 → superannotate-4.6.0}/README.rst

@@ -31,7 +31,7 @@ Authentication
     # by environment variable SA_TOKEN
     sa_client = SAClient()
     # by token
-    sa_client = SAClient(token='<team token>')
+    sa_client = SAClient(token='<API key>')
     # by config file
     # default path is ~/.superannotate/config.ini
     sa_client = SAClient(config_path='~/.superannotate/dev_config.ini')
@@ -42,8 +42,9 @@ config.ini example
 .. code-block:: python
 
     [DEFAULT]
-    SA_TOKEN = <Token>
+    SA_TOKEN = <API key>
     LOGGING_LEVEL = INFO
+    LOGGING_PATH = /Users/username/data/superannotate_logs
 
 
 Using superannotate
@@ -54,7 +55,7 @@ Using superannotate
     from superannotate import SAClient
 
 
-    sa_client =SAClient()
+    sa_client = SAClient()
 
     project = 'Dogs'
 
@@ -110,34 +111,6 @@ Windows (`Anaconda <https://www.anaconda.com/products/individual#windows>`__
 ) platforms.
 
 
-Supported Features
-------------------
-
-- search/get/create/clone/update/delete projects
-- search/get/create/delete folders
-- assign folders to project contributors
-- upload items to a project from a local or AWS S3 folder
-- attach items by URL or from an integrated storage, meanwhile keeping them secure in your cloud provider
-- get integrated cloud storages
-- upload annotations (also from local or AWS S3 folder)
-- delete annotations
-- set items annotations statuses
-- get/download/export annotations from a project (also to a local or AWS S3 folder)
-- invite/search team contributors or add contributors to a specific project
-- search/get/copy/move items in a project
-- query items using SA Query Language
-- define custom metadata for items and upload custom values (query based on your custom metadata)
-- upload priority scores
-- get available subsets (sets of segregated items), query items in a subset or add items to a subset
-- assign or anassign items to project contributors
-- download an image that has been uploaded to project
-- search/create/download/delete project annotation classes
-- search/download models
-- run predictions
-- convert annotations from/to COCO format
-- convert annotation from VOC, SuperVisely, LabelBox, DataLoop, VGG, VoTT, SageMaker, GoogleCloud, YOLO formats
-- CLI commands for simple tasks
-
 Questions and Issues
 --------------------
 

{superannotate-4.5.9 → superannotate-4.6.0}/requirements.txt

@@ -1,11 +1,11 @@
 pydantic~=2.5
 pydantic-extra-types~=2.11
-aiohttp~=3.8
+aiohttp~=3.14
 boto3~=1.42
 opencv-python-headless~=4.7
 plotly~=6.5
 pandas~=2.0
-pillow~=12.1
+pillow~=12.3
 tqdm~=4.66
 requests~=2.33
 aiofiles~=25.1

{superannotate-4.5.9 → superannotate-4.6.0}/src/superannotate/__init__.py

@@ -2,7 +2,7 @@ import logging
 import os
 import sys
 
-__version__ = "4.5.9"
+__version__ = "4.6.0"
 
 
 os.environ.update({"sa_version": __version__})

{superannotate-4.5.9 → superannotate-4.6.0}/src/superannotate/lib/app/input_converters/converters/coco_converters/coco_converter.py

@@ -199,7 +199,7 @@ class CocoBaseStrategy(baseStrategy):
         else:
             try:
                 img = Image.open(image_path)
-                img_width, img_height = img.size()
+                img_width, img_height = img.size
             except Exception as e:
                 raise
 

{superannotate-4.5.9 → superannotate-4.6.0}/src/superannotate/lib/app/interface/base_interface.py

@@ -124,11 +124,14 @@ class Tracker:
 
     @staticmethod
     @lru_cache
-    def get_default_payload(team_name, user_email):
+    def get_default_payload(team_name, user_email, auth_type):
         return {
             "SDK": True,
             "Team": team_name,
             "User Email": user_email,
+            # How the client authenticated: "sdk" for a legacy team token,
+            # "api_key" for a scoped API key.
+            "Auth Type": auth_type,
             "Version": os.environ["sa_version"],
             "Python version": platform.python_version(),
             "Python interpreter type": platform.python_implementation(),
@@ -205,11 +208,12 @@ class Tracker:
             arguments = self.extract_arguments(self.function, *args, **kwargs)
             event_name, properties = self.default_parser(function_name, arguments)
             user_email = client.controller.current_user.email
-            team_name = client.controller.team_data.name
+            team_name = client.controller.team_name
+            auth_type = client.controller.token_context.auth_type
 
             properties["Success"] = success
             default = self.get_default_payload(
-                team_name=team_name, user_email=user_email
+                team_name=team_name, user_email=user_email, auth_type=auth_type
             )
             self._track(
                 user_email,

{superannotate-4.5.9 → superannotate-4.6.0}/src/superannotate/lib/app/interface/cli_interface.py

@@ -33,10 +33,10 @@ class CLIFacade:
         logging_path: str = constances.LOG_FILE_LOCATION,
     ):
         """
-        To initialize CLI (and SDK) with team token
-        Input the team SDK token from https://app.superannotate.com/team
+        To initialize CLI (and SDK) with API key.
+        The API key is available on the team setup page, for more details please visit our documentation at https://doc.superannotate.com/docs/api-keys.
 
-        :param token: the team token
+        :param token: the API key
         :type token: str
 
         :param logging_level: logging level, default is "INFO"

{superannotate-4.5.9 → superannotate-4.6.0}/src/superannotate/lib/app/interface/sdk_interface.py

@@ -295,7 +295,7 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
     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
+    :param token: API key
     :type token: str
 
     :param config_path: path to config file
@@ -303,11 +303,7 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
 
     """
 
-    def __init__(
-        self,
-        token: str | None = None,
-        config_path: str | None = None,
-    ):
+    def __init__(self, token: str | None = None, config_path: str | None = None):
         super().__init__(token, config_path)
 
     def get_project_by_id(self, project_id: int):
@@ -1223,6 +1219,161 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
             operation="revoke",
         )
 
+    def grant_team_user_permissions(
+        self,
+        permissions: list[NotEmptyStr] | Literal["*"],
+        user: int | str,
+    ) -> None:
+        """
+        Grants permissions for a team user. Accepts "*" to indicate all available
+        team-level permissions based on the user's role.
+
+        :param permissions: Specifies which permissions to grant.
+         Accepts "*" to indicate all available team user permissions.
+
+            Possible values are
+
+            - "Access team API keys": Only for Team Admins. Allows Team Admins to
+              create, rotate, and revoke team API keys which have full Team Admin
+              permissions. If this permission is set, it will automatically grant
+              access to all the other admin permissions.
+            - "Access Orchestrate": Only for Team Admins. Allows Team Admins to create and
+              monitor Orchestrate pipelines, as well as access Secrets and Proxies.
+            - "Revoke members' personal API keys": Only for Team Admins. Allows Team
+              Admins to revoke personal API keys generated by other members.
+            - "Manage Contributors' permissions": Only for Team Contributors. Grants
+              all contributor permissions and the ability to manage other
+              contributors' permissions. If this permission is set, it will
+              automatically grant access to all the other contributor permissions.
+            - "Invite Contributors to team": Only for Team Contributors. Allows
+              inviting contributors to the team.
+            - "Remove Contributors from team": Only for Team Contributors. Allows
+              removing contributors from the team.
+            - "View Contributors' scores": Only for Team Contributors. Allows viewing
+              contributors' scores.
+            - "View Contributors' custom field values": Only for Team Contributors.
+              Allows viewing contributors' custom field values.
+            - "Edit Contributors' custom field values": Only for Team Contributors.
+              Allows editing contributors' custom field values. If this permission is
+              set, it will automatically grant access to "View Contributors' custom
+              field values" permission.
+            - "Access Workload management": Only for Team Contributors. Allows
+              accessing Workload management.
+        :type permissions: Union[List[str], Literal["*"]]
+
+        :param user: Team user ID or email to grant permissions to.
+        :type user: Union[int, str]
+
+        :rtype: None
+
+        :raises AppException: If permissions are empty or the user is not found.
+
+        Request Example:
+        ::
+
+            # To grant a specific permission by email:
+            sa_client.grant_team_user_permissions(
+                permissions=["Access team API keys"],
+                user="test@superannotate.com"
+            )
+
+            # To grant all permissions by team user ID:
+            sa_client.grant_team_user_permissions(
+                permissions="*",
+                user=124341
+            )
+
+            # Example when granting "Edit Contributors' custom field values" permission
+            sa_client.grant_team_user_permissions(
+                permissions=["Edit Contributors' custom field values"],
+                user="test@superannotate.com"
+            )
+
+            # Example when granting "Manage Contributors' permissions" permission
+            sa_client.grant_team_user_permissions(
+                permissions=["Manage Contributors' permissions"],
+                user="test@superannotate.com"
+            )
+        """
+        if not permissions:
+            raise AppException("Permission(s) cannot be empty.")
+        self.controller.work_management.edit_team_user_permissions(
+            user=user,
+            permissions=permissions,
+            operation="grant",
+        )
+
+    def revoke_team_user_permissions(
+        self,
+        permissions: list[NotEmptyStr] | Literal["*"],
+        user: int | str,
+    ) -> None:
+        """
+        Revokes permissions for a team user. Accepts "*" to indicate all available
+        team-level permissions based on the user's role.
+
+        :param permissions: Specifies which permissions to revoke.
+         Accepts "*" to indicate all available team user permissions. Possible
+         values are the same as for
+         :func:`grant_team_user_permissions`.
+
+            The following rules apply when revoking:
+
+            - "Access team API keys" grants every other Team Admin permission, so
+              no Team Admin permission can be revoked while it is still granted;
+              revoke "Access team API keys" first.
+            - "Manage Contributors' permissions" grants every other Team
+              Contributor permission, so no Team Contributor permission can be
+              revoked while it is still granted; revoke "Manage Contributors'
+              permissions" first.
+            - Revoking either of the above revokes only that permission; the
+              permissions it implied stay granted.
+            - Revoking "View Contributors' custom field values" will also revoke
+              "Edit Contributors' custom field values".
+        :type permissions: Union[List[str], Literal["*"]]
+
+        :param user: Team user ID or email to revoke permissions from.
+        :type user: Union[int, str]
+
+        :rtype: None
+
+        :raises AppException: If permissions are empty or the user is not found.
+
+        Request Example:
+        ::
+
+            # To revoke a specific permission by email:
+            sa_client.revoke_team_user_permissions(
+                permissions=["Remove Contributors from team"],
+                user="contributor@superannotate.com"
+            )
+
+            # To revoke all permissions by team user ID:
+            sa_client.revoke_team_user_permissions(
+                permissions="*",
+                user=124341
+            )
+
+            # Example when revoking "View Contributors' custom field values" permission
+            sa_client.revoke_team_user_permissions(
+                permissions=["View Contributors' custom field values"],
+                user="test@superannotate.com"
+            )
+
+            # Example when revoking "Manage Contributors' permissions" permission
+            sa_client.revoke_team_user_permissions(
+                permissions=["Manage Contributors' permissions"],
+                user="test@superannotate.com"
+            )
+        """
+        if not permissions:
+            raise AppException("Permission(s) cannot be empty.")
+        self.controller.work_management.edit_team_user_permissions(
+            user=user,
+            permissions=permissions,
+            operation="revoke",
+        )
+
     def get_component_config(self, project: NotEmptyStr | int, component_id: str):
         """
         Retrieves the configuration for a given project and component ID.
@@ -1279,44 +1430,6 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
             raise AppException("No component context found for project.")
         return _context
 
-    def search_team_contributors(
-        self,
-        email: EmailStr | None = None,
-        first_name: NotEmptyStr | None = None,
-        last_name: NotEmptyStr | None = None,
-        return_metadata: bool = True,
-    ):
-        """Search for contributors in the team
-
-        :param email: filter by email
-        :type email: str
-
-        :param first_name: filter by first name
-        :type first_name: str
-
-        :param last_name: filter by last name
-        :type last_name: str
-
-        :param return_metadata: return metadata of contributors instead of names
-        :type return_metadata: bool
-
-        :return: metadata of found users
-        :rtype: list of dicts
-        """
-        warnings.warn(
-            "This function search_team_contributors() will be deprecated and removed in version 4.6.0\n"
-            "Recommended replacement: get_user_metadata() or list_users()",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        contributors = self.controller.search_team_contributors(
-            email=email, first_name=first_name, last_name=last_name
-        ).data
-
-        if not return_metadata:
-            return [contributor["email"] for contributor in contributors]
-        return contributors
-
     def search_projects(
         self,
         name: NotEmptyStr | None = None,
@@ -1345,7 +1458,7 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
         :rtype: list of strs or dicts
         """
         warnings.warn(
-            "This function search_projects() will be deprecated and removed in version 4.6.0\n"
+            "This function search_projects() will be deprecated and removed in version 4.7.0\n"
             "Recommended replacement: get_project_metadata() or list_projects()",
             DeprecationWarning,
             stacklevel=2,
@@ -1951,7 +2064,7 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
         """
         warnings.warn(
             DeprecationWarning(
-                "This function search_folders() will be deprecated and removed in version 4.6.0 \n"
+                "This function search_folders() will be deprecated and removed in version 4.7.0 \n"
                 "Recommended replacement:list_folders()"
             )
         )
@@ -3702,6 +3815,7 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
         keep_status: bool | None = None,
         *,
         data_spec: Literal["default", "multimodal"] = "default",
+        integration: str | None = None,
     ):
         """Uploads a list of annotation dictionaries to the specified SuperAnnotate project or folder.
 
@@ -3723,6 +3837,10 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
                                      compact and modality-specific data representation.
         :type data_spec: str, optional
 
+        :param integration: The name of an existing integration on the SuperAnnotate platform, used to access external URLs in the annotations. Only supported for
+            Multimodal projects and data_spec="multimodal" and only applies to items being newly created — it has no effect on existing items.
+        :type integration: str, optional
+
         :return: A dictionary containing the results of the upload, categorized into successfully uploaded,
             failed, and skipped annotations.
         :rtype: dict
@@ -3759,6 +3877,17 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
                 keep_status=True,
                 data_spec='multimodal'
             )
+
+        Example Usage with private URLs signed via an integration::
+
+            # Upload annotations with private URLs using integration
+            sa_client.upload_annotations(
+                project="project1/folder1",
+                annotations=annotations,
+                keep_status=True,
+                data_spec="multimodal",
+                integration="AWS Main Bucket"
+            )
         """
         if keep_status is not None:
             warnings.warn(
@@ -3768,6 +3897,18 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
                 )
             )
         project, folder = self.controller.get_project_folder(project)
+        integration_entity = None
+        if integration:
+            if data_spec != "multimodal" or project.type != ProjectType.MULTIMODAL:
+                raise AppException(
+                    "Integration is only supported for Multimodal projects"
+                )
+            for i in self.controller.integrations.list().data:
+                if i.name == integration:
+                    integration_entity = i
+                    break
+            else:
+                raise AppException("Integration not found")
         response = self.controller.annotations.upload_multiple(
             project=project,
             folder=folder,
@@ -3775,6 +3916,7 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
             keep_status=keep_status,
             user=self.controller.current_user,
             output_format=data_spec,
+            integration=integration_entity,
         )
         if response.errors:
             raise AppException(response.errors)
@@ -4598,128 +4740,6 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
 
         return BaseSerializer(item).serialize(exclude=exclude)
 
-    def search_items(
-        self,
-        project: NotEmptyStr | int | tuple[int, int] | tuple[str, str],
-        name_contains: NotEmptyStr | None = None,
-        annotation_status: str | None = None,
-        annotator_email: NotEmptyStr | None = None,
-        qa_email: NotEmptyStr | None = None,
-        recursive: bool = False,
-        include_custom_metadata: bool = False,
-    ):
-        """Search items by filtering criteria.
-
-        :param project: Accepts a project as a string ("project" or "project/folder") or as a tuple (project_id, folder_id), where the folder is optional.”
-        :type project: Union[str, int, Tuple[int, int], Tuple[str, 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: returns items with the specified annotation status, which must match a predefined
-            status in the project workflow. If None, all items are returned.
-
-        :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
-
-        :param include_custom_metadata: include custom metadata that has been attached to an asset.
-        :type include_custom_metadata: bool
-
-        :return: metadata of item
-        :rtype: list of dicts
-
-        Request Example:
-        ::
-
-            sa_client.search_items(
-               project="Medical Annotations",
-               name_contains="image_1",
-               include_custom_metadata=True
-            )
-
-        Response Example:
-        ::
-
-            [
-               {
-                   "name": "image_1.jpeg",
-                   "path": "Medical Annotations/Study",
-                   "url": "https://sa-public-files.s3.../image_1.png",
-                   "annotation_status": "NotStarted",
-                   "annotator_email": None,
-                   "qa_email": None,
-                   "entropy_value": None,
-                   "createdAt": "2022-02-15T20:46:44.000Z",
-                   "updatedAt": "2022-02-15T20:46:44.000Z",
-                   "custom_metadata": {
-                       "study_date": "2021-12-31",
-                       "patient_id": "62078f8a756ddb2ca9fc9660",
-                       "patient_sex": "female",
-                       "medical_specialist": "robertboxer@ms.com",
-                   }
-               }
-            ]
-        """
-        warnings.warn(
-            "This function search_items() will be deprecated and removed in version 4.6.0\n"
-            "Recommended replacement: get_item_metadata() or list_items()",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        project, folder = self.controller.get_project_folder(project)
-        query_kwargs = {"include": ["assignments"]}
-        if name_contains:
-            query_kwargs["name__contains"] = name_contains
-        if annotation_status:
-            query_kwargs["annotation_status"] = annotation_status
-        if qa_email:
-            query_kwargs["assignments__user_id"] = qa_email
-            query_kwargs["assignments__user_role"] = "QA"
-        if annotator_email:
-            query_kwargs["assignments__user_id"] = annotator_email
-            query_kwargs["assignments__user_role"] = "Annotator"
-        if folder.is_root and recursive:
-            items = []
-            for folder in self.controller.folders.list(project=project).data:
-                path = (
-                    f"{project.name}{f'/{folder.name}' if not folder.is_root else ''}"
-                )
-                _items = self.controller.items.list_items(
-                    project,
-                    folder,
-                    **query_kwargs,
-                )
-                for i in _items:
-                    i.path = path
-                items.extend(_items)
-        else:
-            path = f"{project.name}{f'/{folder.name}' if not folder.is_root else ''}"
-            items = self.controller.items.list_items(project, folder, **query_kwargs)
-            for i in items:
-                i.path = path
-        exclude = {"meta"}
-        if include_custom_metadata:
-            item_custom_fields = self.controller.custom_fields.list_fields(
-                project=project, item_ids=[i.id for i in items]
-            )
-            for i in items:
-                i.custom_metadata = item_custom_fields[i.id]
-        else:
-            exclude.add("custom_metadata")
-        return BaseSerializer.serialize_iterable(items, exclude=exclude)
-
     def list_items(
         self,
         project: NotEmptyStr | int,
@@ -5683,7 +5703,7 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
     ):
         """
         Attach custom metadata to items.
-        SAClient.get_item_metadata(), SAClient.search_items(), SAClient.query() methods
+        SAClient.get_item_metadata(), SAClient.list_items(), SAClient.query() methods
         will return the item metadata and custom metadata.
 
         :param project: Accepts a project as a string ("project" or "project/folder") or as a tuple (project_id, folder_id), where the folder is optional.”