supervisely 6.73.438__py3-none-any.whl → 6.73.513__py3-none-any.whl

supervisely/api/guides_api.py

@@ -0,0 +1,210 @@
+# coding: utf-8
+"""create or manipulate guides that can be assigned to labeling jobs and labeling queues"""
+
+# docs
+from __future__ import annotations
+
+from typing import Dict, List, NamedTuple, Optional
+
+from supervisely.api.module_api import ApiField, ModuleApiBase
+
+
+class GuideInfo(NamedTuple):
+    """
+    Information about a Guide.
+
+    :param id: Guide ID in Supervisely.
+    :type id: int
+    :param name: Guide name.
+    :type name: str
+    :param description: Guide description.
+    :type description: str
+    :param file_path: Path to the guide file (PDF or other).
+    :type file_path: str
+    :param created_at: Guide creation date.
+    :type created_at: str
+    :param updated_at: Guide last update date.
+    :type updated_at: str
+    :param created_by_id: ID of the User who created the Guide.
+    :type created_by_id: int
+    :param team_id: Team ID where the Guide is located.
+    :type team_id: int
+    :param video_id: ID of the video associated with the guide (if any).
+    :type video_id: Optional[int]
+    :param disabled_by: ID of the User who disabled the Guide (if disabled).
+    :type disabled_by: Optional[int]
+    :param disabled_at: Date when the Guide was disabled (if disabled).
+    :type disabled_at: Optional[str]
+    """
+
+    id: int
+    name: str
+    description: str
+    file_path: str
+    created_at: str
+    updated_at: str
+    created_by_id: int
+    team_id: int
+    video_id: Optional[int] = None
+    disabled_by: Optional[int] = None
+    disabled_at: Optional[str] = None
+
+
+class GuidesApi(ModuleApiBase):
+    """
+    API for working with Guides. :class:`GuidesApi<GuidesApi>` object is immutable.
+
+    :param api: API connection to the server.
+    :type api: Api
+    :Usage example:
+
+     .. code-block:: python
+
+        import os
+        from dotenv import load_dotenv
+
+        import supervisely as sly
+
+        # Load secrets and create API object from .env file (recommended)
+        # Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
+
+        api = sly.Api.from_env()
+
+        # Get list of guides in team
+        guides = api.guides.get_list(team_id=123)
+    """
+
+    @staticmethod
+    def info_sequence():
+        """
+        NamedTuple GuideInfo information about Guide.
+
+        :Example:
+
+         .. code-block:: python
+
+            GuideInfo(
+                id=1,
+                name='How to label objects',
+                description='Comprehensive guide on object labeling',
+                file_path='/path/to/guide.pdf',
+                created_at='2023-01-01T00:00:00.000Z',
+                updated_at='2025-11-17T18:21:10.217Z',
+                created_by_id=1,
+                team_id=1,
+                video_id=None,
+                disabled_by=None,
+                disabled_at=None
+            )
+        """
+        return [
+            ApiField.ID,
+            ApiField.NAME,
+            ApiField.DESCRIPTION,
+            ApiField.FILE_PATH,
+            ApiField.CREATED_AT,
+            ApiField.UPDATED_AT,
+            ApiField.CREATED_BY_ID,
+            ApiField.TEAM_ID,
+            ApiField.VIDEO_ID,
+            ApiField.DISABLED_BY,
+            ApiField.DISABLED_AT,
+        ]
+
+    @staticmethod
+    def info_tuple_name():
+        """
+        NamedTuple name - **GuideInfo**.
+        """
+        return "GuideInfo"
+
+    def get_list(
+        self, team_id: int, filters: Optional[List[Dict[str, str]]] = None
+    ) -> List[GuideInfo]:
+        """
+        Get list of Guides in the given Team.
+
+        :param team_id: Team ID in Supervisely.
+        :type team_id: int
+        :param filters: List of parameters to filter Guides.
+        :type filters: List[Dict[str, str]], optional
+        :return: List of information about Guides.
+        :rtype: :class:`List[GuideInfo]`
+        :Usage example:
+
+         .. code-block:: python
+
+            import os
+            from dotenv import load_dotenv
+
+            import supervisely as sly
+
+            # Load secrets and create API object from .env file (recommended)
+            # Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
+
+            api = sly.Api.from_env()
+
+            team_id = 123
+            guides = api.guides.get_list(team_id)
+            print(guides)
+            # Output: [
+            #     GuideInfo(
+            #         id=1,
+            #         name='How to label objects',
+            #         description='Comprehensive guide on object labeling',
+            #         file_path='/path/to/guide.pdf',
+            #         created_at='2023-01-01T00:00:00.000Z',
+            #         updated_at='2025-11-17T18:21:10.217Z',
+            #         created_by_id=1,
+            #         team_id=1,
+            #         video_id=None,
+            #         disabled_by=None,
+            #         disabled_at=None
+            #     )
+            # ]
+        """
+        return self.get_list_all_pages(
+            "guides.list",
+            {ApiField.TEAM_ID: team_id, ApiField.FILTER: filters or []},
+        )
+
+    def get_info_by_id(self, id: int) -> GuideInfo:
+        """
+        Get Guide information by ID.
+
+        :param id: Guide ID in Supervisely.
+        :type id: int
+        :return: Information about Guide.
+        :rtype: :class:`GuideInfo`
+        :Usage example:
+
+         .. code-block:: python
+
+            import os
+            from dotenv import load_dotenv
+
+            import supervisely as sly
+
+            # Load secrets and create API object from .env file (recommended)
+            # Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
+
+            api = sly.Api.from_env()
+
+            guide_id = 1
+            guide_info = api.guides.get_info_by_id(guide_id)
+            print(guide_info)
+            # Output: GuideInfo(
+            #     id=1,
+            #     name='How to label objects',
+            #     description='Comprehensive guide on object labeling',
+            #     file_path='/path/to/guide.pdf',
+            #     created_at='2023-01-01T00:00:00.000Z',
+            #     updated_at='2025-11-17T18:21:10.217Z',
+            #     created_by_id=1,
+            #     team_id=1,
+            #     video_id=None,
+            #     disabled_by=None,
+            #     disabled_at=None
+            # )
+        """
+        return self._get_info_by_id(id, "guides.info")

supervisely/api/image_api.py

@@ -70,7 +70,11 @@ from supervisely.api.module_api import (
     _get_single_item,
 )
 from supervisely.imaging import image as sly_image
-from supervisely.io.env import app_categories, increment_upload_count, add_uploaded_ids_to_env
+from supervisely.io.env import (
+    add_uploaded_ids_to_env,
+    app_categories,
+    increment_upload_count,
+)
 from supervisely.io.fs import (
     OFFSETS_PKL_BATCH_SIZE,
     OFFSETS_PKL_SUFFIX,
@@ -393,6 +397,9 @@ class ImageInfo(NamedTuple):
     #: Format: "YYYY-MM-DDTHH:MM:SS.sssZ"
     embeddings_updated_at: Optional[str] = None
 
+    #: :class:`int`: :class:`Dataset<supervisely.project.project.Project>` ID in Supervisely.
+    project_id: int = None
+
     # DO NOT DELETE THIS COMMENT
     #! New fields must be added with default values to keep backward compatibility.
 
@@ -472,6 +479,7 @@ class ImageApi(RemoveableBulkModuleApi):
             ApiField.OFFSET_END,
             ApiField.AI_SEARCH_META,
             ApiField.EMBEDDINGS_UPDATED_AT,
+            ApiField.PROJECT_ID,
         ]
 
     @staticmethod
@@ -5519,3 +5527,66 @@ class ImageApi(RemoveableBulkModuleApi):
             method,
             {ApiField.IMAGES: images},
         )
+
+    def get_subsequent_image_ids(
+        self,
+        image_id: int,
+        images_count: Optional[int] = None,
+        job_id: Optional[int] = None,
+        params: Optional[dict] = None,
+        dataset_id: Optional[int] = None,
+        project_id: Optional[int] = None,
+    ) -> List[int]:
+        """
+        Get list of subsequent image IDs after the specified image ID.
+
+        :param image_id: Image ID in Supervisely.
+        :type image_id: int
+        :param images_count: Number of subsequent images to retrieve. If None, retrieves all subsequent images.
+        :type images_count: int, optional
+        :param job_id: Job ID to filter images. If None, does not filter by job ID.
+        :type job_id: int, optional
+        :param params: Additional parameters for filtering and sorting images.
+        :type params: dict, optional
+        :param dataset_id: Dataset ID to filter images.
+        :type dataset_id: int, optional
+        :param project_id: Project ID to filter images. If None, makes a request to retrieve it from the specified image.
+        :type project_id: int, optional
+        """
+        data = {
+            "recursive": True,
+            "projectId": project_id,
+            "filters": [],
+            "sort": "name",
+            "sort_order": "asc",
+        }
+
+        if params is not None:
+            data.update(params)
+
+        if data["projectId"] is None:
+            image_info = self.get_info_by_id(image_id)
+            if image_info is None:
+                raise ValueError(f"Image with ID {image_id} not found.")
+            project_id = self._api.dataset.get_info_by_id(image_info.dataset_id).project_id
+        if job_id is not None:
+            self._api.add_header("x-job-id", str(job_id))
+        if dataset_id is not None:
+            data["datasetId"] = dataset_id
+
+        image_infos = self.get_list_all_pages(
+            "images.list",
+            data,
+            limit=None,
+            return_first_response=False,
+        )
+        self._api.headers.pop("x-job-id", None)
+        image_ids = [img_info.id for img_info in image_infos]
+        if len(image_ids) == 0:
+            raise ValueError("No images found with the specified criteria.")
+        elif image_id not in image_ids:
+            raise ValueError(f"Image with ID {image_id} not found in the specified entity.")
+
+        target_idx = image_ids.index(image_id) + 1
+        to_idx = target_idx + images_count if images_count is not None else len(image_ids)
+        return image_ids[target_idx:to_idx]

supervisely/api/labeling_job_api.py

@@ -89,6 +89,7 @@ class LabelingJobInfo(NamedTuple):
     exclude_images_with_tags: list
     entities: list
     priority: int
+    guide_id: Optional[int] = None
 
 
 class LabelingJobApi(RemoveableBulkModuleApi, ModuleWithStatus):
@@ -223,6 +224,7 @@ class LabelingJobApi(RemoveableBulkModuleApi, ModuleWithStatus):
             ApiField.EXCLUDE_IMAGES_WITH_TAGS,
             ApiField.ENTITIES,
             ApiField.PRIORITY,
+            ApiField.M_GUIDE_ID,
         ]
 
     @staticmethod
@@ -261,7 +263,10 @@ class LabelingJobApi(RemoveableBulkModuleApi, ModuleWithStatus):
                             else:
                                 value = info[sub_name]
                         else:
-                            value = value[sub_name]
+                            if skip_missing is True:
+                                value = value.get(sub_name, None)
+                            else:
+                                value = value[sub_name]
                 else:
                     raise RuntimeError("Can not parse field {!r}".format(field_name))
 
@@ -341,6 +346,8 @@ class LabelingJobApi(RemoveableBulkModuleApi, ModuleWithStatus):
         disable_submit: Optional[bool] = None,
         toolbox_settings: Optional[Dict] = None,
         enable_quality_check: Optional[bool] = None,
+        guide_id: Optional[int] = None,
+        allow_restore: bool = False,
     ) -> List[LabelingJobInfo]:
         """
         Creates Labeling Job and assigns given Users to it.
@@ -385,6 +392,10 @@ class LabelingJobApi(RemoveableBulkModuleApi, ModuleWithStatus):
         :type toolbox_settings: Dict, optional
         :param enable_quality_check: If True, adds an intermediate step between "review" and completing the Labeling Job.
         :type enable_quality_check: bool, optional
+        :param guide_id: Guide ID in Supervisely to assign a guide to the Labeling Job.
+        :type guide_id: int, optional
+        :param allow_restore: If True, allows restoring a previously deleted labeling job with the same name in the same dataset.
+        :type allow_restore: bool
         :return: List of information about new Labeling Job. See :class:`info_sequence<info_sequence>`
         :rtype: :class:`List[LabelingJobInfo]`
         :Usage example:
@@ -463,8 +474,18 @@ class LabelingJobApi(RemoveableBulkModuleApi, ModuleWithStatus):
             "entityIds": images_ids,
             "dynamicClasses": dynamic_classes,
             "dynamicTags": dynamic_tags,
+            "allowRestore": allow_restore,
         }
 
+        if guide_id is not None:
+            try:
+                guide_id = int(guide_id)
+            except Exception as e:
+                raise ValueError(
+                    f"guide_id must be an integer, got {type(guide_id)} with value '{guide_id}'"
+                ) from None
+            meta["guide"] = guide_id
+
         if toolbox_settings is not None:
             dataset_info = self._api.dataset.get_info_by_id(dataset_id)
             project_id = dataset_info.project_id
@@ -1460,3 +1481,64 @@ class LabelingJobApi(RemoveableBulkModuleApi, ModuleWithStatus):
 
         response = self._api.post("jobs.restart", data).json()
         return response
+
+    def get_custom_data(self, id: int) -> dict:
+        """
+        Get custom data of Labeling Job with given ID.
+
+        :param id: Labeling Job ID in Supervisely.
+        :type id: int
+        :return: Custom data of the job
+        :rtype: :class:`dict`
+        :Usage example:
+
+         .. code-block:: python
+
+            import supervisely as sly
+
+            os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
+            os.environ['API_TOKEN'] = 'Your Supervisely API Token'
+            api = sly.Api.from_env()
+
+            custom_data = api.labeling_job.get_custom_data(9)
+            print(custom_data)
+        """
+        method = "jobs.info"
+        response = self._get_response_by_id(id, method, id_field=ApiField.ID)
+        json_response = response.json() if response is not None else None
+        if json_response is not None:
+            return json_response.get(ApiField.CUSTOM_DATA, {})
+        return {}
+
+    def set_custom_data(self, id: int, custom_data: dict, update: bool = True) -> None:
+        """
+        Update or replace custom data of Labeling Job with given ID.
+        By default, updates existing custom data. To replace it entirely, set `update` to False.
+
+        :param id: Labeling Job ID in Supervisely.
+        :type id: int
+        :param custom_data: Custom data to set
+        :type custom_data: dict
+        :param update: Whether to update existing custom data or replace it entirely.
+        :type update: bool
+        :return: None
+        :rtype: :class:`NoneType`
+        :Usage example:
+
+         .. code-block:: python
+
+            import supervisely as sly
+
+            os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
+            os.environ['API_TOKEN'] = 'Your Supervisely API Token'
+            api = sly.Api.from_env()
+
+            api.labeling_job.set_custom_data(9, {"key": "value"})
+        """
+        method = "jobs.editInfo"
+
+        if update is True:
+            existing_custom_data = self.get_custom_data(id)
+            existing_custom_data.update(custom_data)
+            custom_data = existing_custom_data
+        self._api.post(method, {ApiField.ID: id, ApiField.CUSTOM_DATA: custom_data})

supervisely/api/labeling_queue_api.py

@@ -37,6 +37,7 @@ class LabelingQueueInfo(NamedTuple):
     in_progress_count: int
     pending_count: int
     meta: dict
+    collection_id: Optional[int] = None
 
 
 class LabelingQueueApi(RemoveableBulkModuleApi, ModuleWithStatus):
@@ -93,7 +94,8 @@ class LabelingQueueApi(RemoveableBulkModuleApi, ModuleWithStatus):
                 annotated_count=3,
                 in_progress_count=2,
                 pending_count=1,
-                meta={}
+                meta={},
+                collection_id=None,
             )
         """
         return [
@@ -115,6 +117,7 @@ class LabelingQueueApi(RemoveableBulkModuleApi, ModuleWithStatus):
             ApiField.IN_PROGRESS_COUNT,
             ApiField.PENDING_COUNT,
             ApiField.META,
+            ApiField.COLLECTION_ID,
         ]
 
     @staticmethod
@@ -200,24 +203,24 @@ class LabelingQueueApi(RemoveableBulkModuleApi, ModuleWithStatus):
         skip_complete_job_on_empty: Optional[bool] = False,
         enable_quality_check: Optional[bool] = None,
         quality_check_user_ids: Optional[List[int]] = None,
+        guide_id: Optional[int] = None,
+        description: Optional[str] = None,
     ) -> int:
         """
         Creates Labeling Queue and assigns given Users to it.
 
         :param name: Labeling Queue name in Supervisely.
         :type name: str
-        :param dataset_id: Dataset ID in Supervisely.
-        :type dataset_id: int
-        :param collection_id: Entities Collection ID in Supervisely.
-        :type collection_id: int, optional
         :param user_ids: User IDs in Supervisely to assign Users as labelers to Labeling Queue.
         :type user_ids: List[int]
         :param reviewer_ids: User IDs in Supervisely to assign Users as reviewers to Labeling Queue.
         :type reviewer_ids: List[int]
+        :param dataset_id: Dataset ID in Supervisely.
+        :type dataset_id: int
+        :param collection_id: Entities Collection ID in Supervisely.
+        :type collection_id: int, optional
         :param readme: Additional information about Labeling Queue.
         :type readme: str, optional
-        :param description: Description of Labeling Queue.
-        :type description: str, optional
         :param classes_to_label: List of classes to label in Dataset.
         :type classes_to_label: List[str], optional
         :param objects_limit_per_image: Limit the number of objects that the labeler can create on each image.
@@ -256,6 +259,10 @@ class LabelingQueueApi(RemoveableBulkModuleApi, ModuleWithStatus):
         :type enable_quality_check: bool, optional
         :param quality_check_user_ids: List of User IDs in Supervisely to assign Users as Quality Checkers to Labeling Queue.
         :type quality_check_user_ids: List[int], optional
+        :param guide_id: Guide ID in Supervisely to assign a guide to the Labeling Queue.
+        :type guide_id: int, optional
+        :param description: Description of Labeling Queue.
+        :type description: str, optional
         :return: Labeling Queue ID in Supervisely.
         :rtype: int
         :Usage example:
@@ -340,6 +347,15 @@ class LabelingQueueApi(RemoveableBulkModuleApi, ModuleWithStatus):
         if images_ids is not None:
             meta["entityIds"] = images_ids
 
+        if guide_id is not None:
+            try:
+                guide_id = int(guide_id)
+            except Exception as e:
+                raise ValueError(
+                    f"guide_id must be an integer, got {type(guide_id)} with value '{guide_id}'"
+                ) from None
+            meta["guide"] = guide_id
+
         if toolbox_settings is not None:
             if dataset_id is not None:
                 dataset_info = self._api.dataset.get_info_by_id(dataset_id)
@@ -399,6 +415,9 @@ class LabelingQueueApi(RemoveableBulkModuleApi, ModuleWithStatus):
         if readme is not None:
             data[ApiField.README] = str(readme)
 
+        if description is not None:
+            data[ApiField.DESCRIPTION] = str(description)
+
         if images_range is not None and images_range != (None, None):
             if len(images_range) != 2:
                 raise RuntimeError("images_range has to contain 2 elements (start, end)")
@@ -419,6 +438,7 @@ class LabelingQueueApi(RemoveableBulkModuleApi, ModuleWithStatus):
         ids: Optional[List[int]] = None,
         names: Optional[List[str]] = None,
         show_disabled: Optional[bool] = False,
+        collection_id: Optional[int] = None,
     ) -> List[LabelingQueueInfo]:
         """
         Get list of information about Labeling Queues in the given Team.
@@ -435,6 +455,8 @@ class LabelingQueueApi(RemoveableBulkModuleApi, ModuleWithStatus):
         :type names: List[str], optional
         :param show_disabled: Show disabled Labeling Queues.
         :type show_disabled: bool, optional
+        :param collection_id: Entities Collection ID in Supervisely.
+        :type collection_id: int, optional
         :return: List of information about Labeling Queues. See :class:`info_sequence<info_sequence>`
         :rtype: :class:`List[LabelingQueueInfo]`
         :Usage example:
@@ -455,6 +477,10 @@ class LabelingQueueApi(RemoveableBulkModuleApi, ModuleWithStatus):
             filters.append({"field": ApiField.PROJECT_ID, "operator": "=", "value": project_id})
         if dataset_id is not None:
             filters.append({"field": ApiField.DATASET_ID, "operator": "=", "value": dataset_id})
+        if collection_id is not None:
+            filters.append(
+                {"field": ApiField.COLLECTION_ID, "operator": "=", "value": collection_id}
+            )
         if names is not None:
             filters.append({"field": ApiField.NAME, "operator": "in", "value": names})
         if ids is not None:

supervisely/api/module_api.py

@@ -709,6 +709,15 @@ class ApiField:
     """"""
     UNIQUE_ITEMS = "uniqueItems"
     """"""
+    NN_CREATED = "nnCreated"
+    """"""
+    NN_UPDATED = "nnUpdated"
+    """"""
+    M_GUIDE_ID = (["meta", "guide"], "guide_id")
+    """"""
+    GUIDE_ID = "guideId"
+    """"""
+    SINGLE_SESSION_MODE = "singleSessionMode"
 
 
 def _get_single_item(items):