From 883a944ad9cee70d570f82428a1427c9ef5a3a99 Mon Sep 17 00:00:00 2001 From: Vaghinak Basentsyan Date: Wed, 5 Mar 2025 14:10:19 +0400 Subject: [PATCH] Update docs --- CHANGELOG.rst | 4 +- docs/source/api_reference/api_item.rst | 4 + src/superannotate/__init__.py | 2 + .../lib/app/interface/sdk_interface.py | 86 +++++++++++++++++++ 4 files changed, 94 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index ca592d4b0..f2b84c702 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -7,11 +7,11 @@ History All release highlights of this project will be documented in this file. 4.4.32 - March 4, 2025 -_____________________ +______________________ **Fixed** - - ``SAClient.item_context`` Fixed an issue where setting a component value would overwrite existing comments and other associated data. + - ``SAClient.item_context`` Fixed an issue where setting a component value would overwrite existing comments and other associated data. 4.4.31 - Feb 27, 2025 _____________________ diff --git a/docs/source/api_reference/api_item.rst b/docs/source/api_reference/api_item.rst index 6dafbd743..55605ea37 100644 --- a/docs/source/api_reference/api_item.rst +++ b/docs/source/api_reference/api_item.rst @@ -9,6 +9,10 @@ Items .. automethod:: superannotate.SAClient.search_items .. automethod:: superannotate.SAClient.attach_items .. automethod:: superannotate.SAClient.item_context +.. autoclass:: superannotate.ItemContext + :members: get_metadata, get_component_value, set_component_value + :member-order: bysource + .. automethod:: superannotate.SAClient.copy_items .. automethod:: superannotate.SAClient.move_items .. automethod:: superannotate.SAClient.delete_items diff --git a/src/superannotate/__init__.py b/src/superannotate/__init__.py index d4ad72cfa..601bbc2f9 100644 --- a/src/superannotate/__init__.py +++ b/src/superannotate/__init__.py @@ -21,6 +21,7 @@ from superannotate.lib.app.input_converters import export_annotation from superannotate.lib.app.input_converters import import_annotation from superannotate.lib.app.interface.sdk_interface import SAClient +from superannotate.lib.app.interface.sdk_interface import ItemContext SESSIONS = {} @@ -29,6 +30,7 @@ __all__ = [ "__version__", "SAClient", + "ItemContext", # Utils "enums", "AppException", diff --git a/src/superannotate/lib/app/interface/sdk_interface.py b/src/superannotate/lib/app/interface/sdk_interface.py index fa20dd3cc..bd9ef2743 100644 --- a/src/superannotate/lib/app/interface/sdk_interface.py +++ b/src/superannotate/lib/app/interface/sdk_interface.py @@ -118,6 +118,20 @@ class Attachment(TypedDict, total=False): class ItemContext: + """ + A context manager for handling annotations and metadata of an item. + + The ItemContext class provides methods to retrieve and manage metadata and component + values for items in the specified context. Below are the descriptions and usage examples for each method. + + Example: + :: + + with sa_client.item_context("project_name/folder_name", "item_name") as context: + metadata = context.get_metadata() + print(metadata) + """ + def __init__( self, controller: Controller, @@ -171,9 +185,26 @@ def annotation(self): return self.annotation_adapter.annotation def __enter__(self): + """ + Enters the context manager. + + Returns: + ItemContext: The instance itself. + """ return self def __exit__(self, exc_type, exc_val, exc_tb): + """ + Exits the context manager, saving changes if no exception occurred. + + Args: + exc_type (Optional[Type[BaseException]]): Exception type if raised. + exc_val (Optional[BaseException]): Exception instance if raised. + exc_tb (Optional[TracebackType]): Traceback if an exception occurred. + + Returns: + bool: True if no exception occurred, False otherwise. + """ if exc_type: return False @@ -188,12 +219,62 @@ def save(self): self._annotation_adapter.save() def get_metadata(self): + """ + Retrieves the metadata associated with the current item context. + + :return: A dictionary containing metadata for the current item. + :rtype: dict + + Request Example: + :: + + with client.item_context(("project_name", "folder_name"), 12345) as context: + metadata = context.get_metadata() + print(metadata) + """ return self.annotation["metadata"] def get_component_value(self, component_id: str): + """ + Retrieves the value of a specific component within the item context. + + :param component_id: The name of the component whose value is to be retrieved. + :type component_id: str + + :return: The value of the specified component. + :rtype: Any + + Request Example: + :: + + with client.item_context((101, 202), "item_name") as context: # (101, 202) project and folder IDs + value = context.get_component_value("component_id") + print(value) + """ return self.annotation_adapter.get_component_value(component_id) def set_component_value(self, component_id: str, value: Any): + """ + Updates the value of a specific component within the item context. + + :param component_id: The component identifier. + :type component_id: str + + :param value: The new value to set for the specified component. + :type value: Any + + :return: The instance itself to allow method chaining. + :rtype: ItemContext + + Request Example: + :: + + with client.item_context("project_name/folder_name", "item_name") as item_context: + metadata = item_context.get_metadata() + value = item_context.get_component_value("component_id") + item_context.set_component_value("component_id", value) + + """ self.annotation_adapter.set_component_value(component_id, value) return self @@ -381,6 +462,7 @@ def list_users( ): """ Search users by filtering criteria + :param project: Project name or ID, if provided, results will be for project-level, otherwise results will be for team level. :type project: str or int @@ -4357,6 +4439,10 @@ def item_context( :return: An `ItemContext` object to manage the specified item's annotations and metadata. :rtype: ItemContext + .. seealso:: + For more details, see :class:`ItemContext`. + + **Examples:** Create an `ItemContext` using a string path and item name: