(20241127) Labels upgraded.

2024-11-27 10:53:53 +05:30
parent 629922431d
commit 759b5a05be
2 changed files with 225 additions and 6 deletions
@@ -124,6 +124,15 @@ class AsyncGMailClient(AsyncGoogleBase):
            user_id: str = "me",
    ) -> GoogleApiResponse:

+        """
+        To get the list of labels of this user.
+        DOCUMENTATION:
+            1. https://developers.google.com/gmail/api/reference/rest/v1/users/getProfile
+        :param tokens: The object that holds the access token to the service.
+        :param user_id: The id of the user for which this service must be run. Typically, the e-mail id itself or "me".
+        :return: A structured response where the list of labels will be in the 'data' variable.
+        """
+
        # Ensure that the tokens are valid:
        await tokens.arefresh(
            http_client = self._http_client,
@@ -162,7 +171,7 @@ class AsyncGMailClient(AsyncGoogleBase):
            1. https://developers.google.com/gmail/api/reference/rest/v1/users.labels/list
            2. https://developers.google.com/gmail/api/reference/rest/v1/users.labels#Label
        :param tokens: The object that holds the access token to the service.
-        :param user_id: The id of the user for which this service must be run. Typically, the e-mail id itself.
+        :param user_id: The id of the user for which this service must be run. Typically, the e-mail id itself or "me".
        :return: A structured response where the list of labels will be in the 'data' variable.
        """

@@ -183,12 +192,216 @@ class AsyncGMailClient(AsyncGoogleBase):

        # If the call was successful:
        if api_response.httpCode in [200]:
+            api_response.success = True
            api_json = await api_response.get_json()
            api_response.data = {label.pop("name"): label for label in api_json.get("labels", [])}

        # Done here:
        return api_response

+    async def get_label(
+            self,
+            tokens: GoogleAuthTokens,
+            label_id: str,
+            user_id: str = "me"
+    ) -> GoogleApiResponse:
+
+        """
+        To get one label of this user. the label will be identified by its id.
+        DOCUMENTATION:
+            1. https://developers.google.com/gmail/api/reference/rest/v1/users.labels/get
+            2. https://developers.google.com/gmail/api/reference/rest/v1/users.labels#Label
+        :param tokens: The object that holds the access token to the service.
+        :param label_id: The id that Google assigned to the label.
+        :param user_id: The id of the user for which this service must be run. Typically, the e-mail id itself or "me".
+        :return: A structured response where the list of labels will be in the 'data' variable.
+        """
+
+        # Ensure that the tokens are valid:
+        await tokens.arefresh(
+            http_client = self._http_client,
+            client_id = self._client_id,
+            client_secret = self._client_secret,
+            force_refresh = False
+        )
+
+        # Make the API call:
+        if not self._debug_only_errors: self._printer("Getting One Label.", user_id)
+        api_response = await self.get(
+            url = f"https://gmail.googleapis.com/gmail/v1/users/{user_id}/labels/{label_id}",
+            headers = {"Authorization": f"Bearer {tokens.accessToken}"}
+        )
+
+        # If the call was successful:
+        if api_response.httpCode in [200]:
+            api_response.success = True
+            api_response.data = await api_response.get_json()
+
+        # Done here:
+        return api_response
+
+    async def create_label(
+            self,
+            tokens: GoogleAuthTokens,
+            label_name: str,
+            label_visibility: Literal["labelShow", "labelShowIfUnread", "labelHide"] = "labelShow",
+            message_visibility: Literal["show", "hide"] = "show",
+            label_text_color: str = "#434343",
+            label_background_color: str = "#000000",
+            user_id: str = "me"
+    ) -> GoogleApiResponse:
+
+        """
+        Create one label for the user. Doesn't apply it to any mail, just creates it.
+        DOCUMENTATION:
+            1. https://developers.google.com/gmail/api/reference/rest/v1/users.labels/create
+            2. https://developers.google.com/gmail/api/reference/rest/v1/users.labels#Label
+        :param tokens: The object that holds the access token to the service.
+        :param label_name: The display name of the label.
+        :param label_visibility: Whether, or not, you would like to show the label in the web UI.
+        :param message_visibility: Whether, or not, you would like to show messages with this label in the web UI.
+        :param label_text_color: The colour of the text of the label.
+        :param label_background_color: The colour of the background/tag of the label.
+        :param user_id: The id of the user for which this service must be run. Typically, the e-mail id itself or "me".
+        :return: A structured response where the list of labels will be in the 'data' variable.
+        """
+
+        # Ensure that the tokens are valid:
+        await tokens.arefresh(
+            http_client = self._http_client,
+            client_id = self._client_id,
+            client_secret = self._client_secret,
+            force_refresh = False
+        )
+
+        # Make the API call:
+        if not self._debug_only_errors: self._printer("Getting One Label.", user_id)
+        api_response = await self.post(
+            url = f"https://gmail.googleapis.com/gmail/v1/users/{user_id}/labels",
+            headers = {"Authorization": f"Bearer {tokens.accessToken}"},
+            json = {
+                "name": label_name,
+                "messageListVisibility": "show" if message_visibility else "hide",
+                "labelListVisibility": "labelShow" if label_visibility else "labelHide",
+                "color": {
+                    "textColor": label_text_color.lower(),
+                    "backgroundColor": label_background_color.lower()
+                }
+            }
+        )
+
+        # If the call was successful:
+        if api_response.httpCode in [200]:
+            api_response.success = True
+            api_response.data = await api_response.get_json()
+
+        # Done here:
+        return api_response
+
+    async def update_label(
+            self,
+            tokens: GoogleAuthTokens,
+            label_id: str,
+            label_name: str = None,
+            label_visibility: Literal["labelShow", "labelShowIfUnread", "labelHide"] = None,
+            message_visibility: Literal["show", "hide"] = None,
+            label_text_color: str = None,
+            label_background_color: str = None,
+            user_id: str = "me"
+    ) -> GoogleApiResponse:
+
+        """
+        Updates one label for the user.
+        DOCUMENTATION:
+            1. https://developers.google.com/gmail/api/reference/rest/v1/users.labels/update
+            2. https://developers.google.com/gmail/api/reference/rest/v1/users.labels#Label
+        NOTE: Both or none of the colours must be updated. For this reason, a simple default will be chosen for the
+        other if only one is provided.
+        :param tokens: The object that holds the access token to the service.
+        :param label_id: The id that Google assigned to the label.
+        :param label_name: The display name of the label.
+        :param label_visibility: Whether, or not, you would like to show the label in the web UI.
+        :param message_visibility: Whether, or not, you would like to show messages with this label in the web UI.
+        :param label_text_color: The colour of the text of the label.
+        :param label_background_color: The colour of the background/tag of the label.
+        :param user_id: The id of the user for which this service must be run. Typically, the e-mail id itself or "me".
+        :return: A structured response where the list of labels will be in the 'data' variable.
+        """
+
+        # Ensure that the tokens are valid:
+        await tokens.arefresh(
+            http_client = self._http_client,
+            client_id = self._client_id,
+            client_secret = self._client_secret,
+            force_refresh = False
+        )
+
+        # Format the JSON body:
+        json_body = {}
+        if label_name: json_body["name"] = label_name
+        if label_visibility: json_body["labelListVisibility"] = label_visibility
+        if message_visibility: json_body["messageListVisibility"] = message_visibility
+        if label_text_color or label_background_color:
+            json_body["color"] = {
+                "textColor": (label_text_color or "#434343").lower(),
+                "backgroundColor": (label_background_color or "#000000").lower()
+            }
+
+        # Make the API call:
+        if not self._debug_only_errors: self._printer("Updating One Label.", user_id)
+        api_response = await self.put(
+            url = f"https://gmail.googleapis.com/gmail/v1/users/{user_id}/labels/{label_id}",
+            headers = {"Authorization": f"Bearer {tokens.accessToken}"},
+            json = json_body
+        )
+
+        # If the call was successful:
+        if api_response.httpCode in [200]:
+            api_response.success = True
+            api_response.data = await api_response.get_json()
+
+        # Done here:
+        return api_response
+
+    async def delete_label(
+            self,
+            tokens: GoogleAuthTokens,
+            label_id: str,
+            user_id: str = "me"
+    ) -> GoogleApiResponse:
+
+        """
+        To delete one label of this user. the label will be identified by its id.
+        DOCUMENTATION:
+            1. https://developers.google.com/gmail/api/reference/rest/v1/users.labels/delete
+        :param tokens: The object that holds the access token to the service.
+        :param label_id: The id that Google assigned to the label.
+        :param user_id: The id of the user for which this service must be run. Typically, the e-mail id itself or "me".
+        :return: A structured response where the list of labels will be in the 'data' variable.
+        """
+
+        # Ensure that the tokens are valid:
+        await tokens.arefresh(
+            http_client = self._http_client,
+            client_id = self._client_id,
+            client_secret = self._client_secret,
+            force_refresh = False
+        )
+
+        # Make the API call:
+        if not self._debug_only_errors: self._printer("Getting One Label.", user_id)
+        api_response = await self.delete(
+            url = f"https://gmail.googleapis.com/gmail/v1/users/{user_id}/labels/{label_id}",
+            headers = {"Authorization": f"Bearer {tokens.accessToken}"}
+        )
+
+        # If the call was successful:
+        if api_response.httpCode in [200, 204]:
+            api_response.success = True
+
+        # Done here:
+        return api_response
+

 #   *****************************************************************************************************************
 #  *****                                                                                                          ****