[#12441] feat(client-python): Support tag assignment values

clients/client-python/gravitino/api/tag/supports_tags.py

@@ -20,6 +20,7 @@
 from abc import ABC, abstractmethod
 
 from gravitino.api.tag.tag import Tag
+from gravitino.exceptions.base import UnsupportedOperationException
 
 
 class SupportsTags(ABC):
@@ -61,6 +62,25 @@ def get_tag(self, name: str) -> Tag:
         """
         pass
 
+    def assign_tags(
+        self,
+        tags_to_add: list[str | dict[str, str | None]] | None = None,
+        tags_to_remove: list[str | dict[str, str | None]] | None = None,
+    ) -> list[str]:
+        """Assign tag-value pairs to the specific object.
+
+        Args:
+            tags_to_add: The tag-value pairs to be added to the object.
+            tags_to_remove: The tag-value pairs to be removed from the object.
+
+        Raises:
+            UnsupportedOperationException: The assign_tags method is not supported.
+
+        Returns:
+            list[str]: The tag names directly associated with the object after assignment.
+        """
+        raise UnsupportedOperationException("The assign_tags method is not supported.")
+
     @abstractmethod
     def associate_tags(
         self, tags_to_add: list[str], tags_to_remove: list[str]

clients/client-python/gravitino/api/tag/tag.py

@@ -39,11 +39,14 @@ def count(self) -> int:
         return 0 if objects is None else len(objects)
 
     @abstractmethod
-    def objects(self) -> Optional[list[MetadataObject]]:
+    def objects(self, value: Optional[str] = None) -> Optional[list[MetadataObject]]:
         """Get the associated objects.
 
+        Args:
+            value: The optional exact assignment value filter.
+
         Returns:
-            Optional[list[MetadataObject]]: The list of objects that are associated with this tag..
+            Optional[list[MetadataObject]]: The list of objects that are associated with this tag.
         """
         pass
 
@@ -89,6 +92,22 @@ def properties(self) -> dict[str, str]:
         """
         raise NotImplementedError()
 
+    def allowed_values(self) -> Optional[list[str]]:
+        """Get the allowed values for this tag.
+
+        Returns:
+            Optional[list[str]]: The allowed values, or None if values are unrestricted.
+        """
+        return None
+
+    def assignment_values(self) -> Optional[list[str]]:
+        """Get assignment values when this tag is loaded from a metadata object.
+
+        Returns:
+            Optional[list[str]]: The assignment values, or None if not assignment-scoped.
+        """
+        return None
+
     @abstractmethod
     def inherited(self) -> Optional[bool]:
         """Check if the tag is inherited from a parent object or not.
@@ -131,10 +150,13 @@ def count(self) -> int:
             return 0 if (s := self.objects()) is None else len(s)
 
         @abstractmethod
-        def objects(self) -> list[MetadataObject]:
+        def objects(self, value: Optional[str] = None) -> list[MetadataObject]:
             """
             Retrieve the list of objects that are associated with this tag.
 
+            Args:
+                value: The optional exact assignment value filter.
+
             Raises:
                 NotImplementedError: if the method is not implemented.
 

clients/client-python/gravitino/api/tag/tag_operations.py

@@ -77,6 +77,7 @@ def create_tag(
         tag_name: str,
         comment: str,
         properties: dict[str, str],
+        allowed_values: list[str] | None = None,
     ) -> Tag:
         """
         Create a new tag under a metalake.
@@ -89,6 +90,7 @@ def create_tag(
             tag_name (str): The name of the tag.
             comment (str): The comment of the tag.
             properties (dict[str, str]): The properties of the tag.
+            allowed_values (list[str] | None): The allowed assignment values.
 
         Returns:
             Tag: The tag information.

clients/client-python/gravitino/client/base_schema_catalog.py

@@ -363,6 +363,13 @@ def list_tags_info(self) -> List[Tag]:
     def get_tag(self, name: str) -> Tag:
         return self._object_tag_operations.get_tag(name)
 
+    def assign_tags(
+        self,
+        tags_to_add: list[str | dict[str, str | None]] | None = None,
+        tags_to_remove: list[str | dict[str, str | None]] | None = None,
+    ) -> list[str]:
+        return self._object_tag_operations.assign_tags(tags_to_add, tags_to_remove)
+
     def associate_tags(
         self, tags_to_add: List[str], tags_to_remove: List[str]
     ) -> List[str]:

clients/client-python/gravitino/client/generic_column.py

@@ -90,6 +90,13 @@ def list_tags_info(self) -> list[Tag]:
     def get_tag(self, name: str) -> Tag:
         return self._object_tag_operations.get_tag(name)
 
+    def assign_tags(
+        self,
+        tags_to_add: list[str | dict[str, str | None]] | None = None,
+        tags_to_remove: list[str | dict[str, str | None]] | None = None,
+    ) -> list[str]:
+        return self._object_tag_operations.assign_tags(tags_to_add, tags_to_remove)
+
     def associate_tags(
         self, tags_to_add: list[str], tags_to_remove: list[str]
     ) -> list[str]:

clients/client-python/gravitino/client/generic_fileset.py

@@ -95,6 +95,13 @@ def list_tags_info(self) -> List[Tag]:
     def get_tag(self, name: str) -> Tag:
         return self._object_tag_operations.get_tag(name)
 
+    def assign_tags(
+        self,
+        tags_to_add: list[str | dict[str, str | None]] | None = None,
+        tags_to_remove: list[str | dict[str, str | None]] | None = None,
+    ) -> list[str]:
+        return self._object_tag_operations.assign_tags(tags_to_add, tags_to_remove)
+
     def associate_tags(
         self, tags_to_add: List[str], tags_to_remove: List[str]
     ) -> List[str]:

clients/client-python/gravitino/client/generic_function.py

@@ -98,6 +98,14 @@ def get_tag(self, name: str) -> Tag:
         """Get an associated tag by name."""
         return self._object_tag_operations.get_tag(name)
 
+    def assign_tags(
+        self,
+        tags_to_add: list[str | dict[str, str | None]] | None = None,
+        tags_to_remove: list[str | dict[str, str | None]] | None = None,
+    ) -> list[str]:
+        """Assign or remove tag-value pairs for the function."""
+        return self._object_tag_operations.assign_tags(tags_to_add, tags_to_remove)
+
     def associate_tags(
         self, tags_to_add: list[str], tags_to_remove: list[str]
     ) -> list[str]:

clients/client-python/gravitino/client/generic_model.py

@@ -80,6 +80,13 @@ def list_tags_info(self) -> list[Tag]:
     def get_tag(self, name: str) -> Tag:
         return self._model_tag_operations.get_tag(name)
 
+    def assign_tags(
+        self,
+        tags_to_add: list[str | dict[str, str | None]] | None = None,
+        tags_to_remove: list[str | dict[str, str | None]] | None = None,
+    ) -> list[str]:
+        return self._model_tag_operations.assign_tags(tags_to_add, tags_to_remove)
+
     def associate_tags(
         self, tags_to_add: list[str], tags_to_remove: list[str]
     ) -> list[str]:

clients/client-python/gravitino/client/generic_schema.py

@@ -85,6 +85,15 @@ def list_tags_info(self) -> list[Tag]:
     def get_tag(self, name: str) -> Tag:
         return self._metadata_object_tag_operations.get_tag(name)
 
+    def assign_tags(
+        self,
+        tags_to_add: list[str | dict[str, str | None]] | None = None,
+        tags_to_remove: list[str | dict[str, str | None]] | None = None,
+    ) -> list[str]:
+        return self._metadata_object_tag_operations.assign_tags(
+            tags_to_add, tags_to_remove
+        )
+
     def associate_tags(
         self, tags_to_add: list[str], tags_to_remove: list[str]
     ) -> list[str]:

clients/client-python/gravitino/client/generic_tag.py

@@ -29,6 +29,7 @@
 from gravitino.exceptions.handlers.tag_error_handler import TAG_ERROR_HANDLER
 from gravitino.rest.rest_utils import encode_string
 from gravitino.utils import HTTPClient
+from gravitino.utils.precondition import Precondition
 from gravitino.utils.http_client import Response
 
 
@@ -80,6 +81,22 @@ def properties(self) -> dict[str, str]:
         """
         return self._tag_dto.properties()
 
+    def allowed_values(self) -> Optional[list[str]]:
+        """Get the allowed values for this tag.
+
+        Returns:
+            Optional[list[str]]: The allowed values, or None if values are unrestricted.
+        """
+        return self._tag_dto.allowed_values()
+
+    def assignment_values(self) -> Optional[list[str]]:
+        """Get assignment values when this tag is loaded from a metadata object.
+
+        Returns:
+            Optional[list[str]]: The assignment values, or None if not assignment-scoped.
+        """
+        return self._tag_dto.assignment_values()
+
     def inherited(self) -> Optional[bool]:
         """Check if the tag is inherited from a parent object or not.
 
@@ -113,38 +130,53 @@ def associated_objects(self) -> Tag.AssociatedObjects:
         """
         return self
 
-    def objects(self) -> list[MetadataObject]:
+    def objects(self, value: Optional[str] = None) -> list[MetadataObject]:
         """
         Retrieve the list of objects that are associated with this tag.
 
+        Args:
+            value: The optional exact assignment value filter.
+
         Returns:
             list[MetadataObject]: The list of objects that are associated with this tag.
         """
+        params = {}
+        if value is not None:
+            Precondition.check_argument(
+                value.strip() != "" and len(value) <= 256,
+                "value must not be empty or longer than 256 characters",
+            )
+            params["value"] = value
+
         url = self.API_LIST_OBJECTS_ENDPOINT.format(
             self._metalake,
             encode_string(self.name()),
         )
 
-        response = self.get_response(url, TAG_ERROR_HANDLER)
+        response = self.get_response(url, TAG_ERROR_HANDLER, params)
         objects_resp = MetadataObjectListResponse.from_json(
             response.body, infer_missing=True
         )
         objects_resp.validate()
 
         return objects_resp.metadata_objects()
 
-    def get_response(self, url: str, error_handler: ErrorHandler) -> Response:
+    def get_response(
+        self, url: str, error_handler: ErrorHandler, params: dict[str, str]
+    ) -> Response:
         """
         Get the response from the server, for testing convenience.
 
         Args:
             url (str): The url to get the response from.
             error_handler (ErrorHandlers): The error handler to use.
+            params (dict[str, str]): The query parameters to send.
 
         Returns:
             Response: The response from the server.
         """
         return self._client.get(
             url,
+            params=params,
             error_handler=error_handler,
         )

clients/client-python/gravitino/client/generic_view.py

@@ -95,6 +95,13 @@ def list_tags_info(self) -> list[Tag]:
     def get_tag(self, name: str) -> Tag:
         return self._object_tag_operations.get_tag(name)
 
+    def assign_tags(
+        self,
+        tags_to_add: list[str | dict[str, str | None]] | None = None,
+        tags_to_remove: list[str | dict[str, str | None]] | None = None,
+    ) -> list[str]:
+        return self._object_tag_operations.assign_tags(tags_to_add, tags_to_remove)
+
     def associate_tags(
         self, tags_to_add: list[str], tags_to_remove: list[str]
     ) -> list[str]:

clients/client-python/gravitino/client/gravitino_client.py

@@ -287,7 +287,7 @@ def get_tag(self, tag_name) -> Tag:
         """
         return self.get_metalake().get_tag(tag_name)
 
-    def create_tag(self, tag_name, comment, properties) -> Tag:
+    def create_tag(self, tag_name, comment, properties, allowed_values=None) -> Tag:
         """
         Create a new tag under a metalake.
 
@@ -299,11 +299,14 @@ def create_tag(self, tag_name, comment, properties) -> Tag:
             tag_name (str): The name of the tag.
             comment (str): The comment of the tag.
             properties (dict[str, str]): The properties of the tag.
+            allowed_values (list[str] | None): The allowed assignment values.
 
         Returns:
             Tag: The tag information.
         """
-        return self.get_metalake().create_tag(tag_name, comment, properties)
+        return self.get_metalake().create_tag(
+            tag_name, comment, properties, allowed_values
+        )
 
     def alter_tag(self, tag_name, *changes) -> Tag:
         """

clients/client-python/gravitino/client/gravitino_metalake.py

@@ -653,7 +653,7 @@ def get_tag(self, tag_name) -> Tag:
 
         return GenericTag(self.name(), tag_resp.tag(), self.rest_client)
 
-    def create_tag(self, tag_name, comment, properties) -> Tag:
+    def create_tag(self, tag_name, comment, properties, allowed_values=None) -> Tag:
         """
         Create a new tag under a metalake.
 
@@ -665,6 +665,7 @@ def create_tag(self, tag_name, comment, properties) -> Tag:
             tag_name (str): The name of the tag.
             comment (str): The comment of the tag.
             properties (dict[str, str]): The properties of the tag.
+            allowed_values (list[str] | None): The allowed assignment values.
 
         Returns:
             Tag: The tag information.
@@ -673,6 +674,7 @@ def create_tag(self, tag_name, comment, properties) -> Tag:
             tag_name,
             comment,
             properties,
+            allowed_values,
         )
         tag_create_request.validate()