Merge pull request #1199 from alifeee/master

Feature: Add "Remove tab colour" method
burnash · Jun 8, 2023 · fde332b · fde332b
2 parents 8f25aa1 + 08afe7e
commit fde332b
Show file tree

Hide file tree

Showing 5 changed files with 1,230 additions and 132 deletions.
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
@@ -105,6 +105,15 @@ Deleting a Worksheet
    sh.del_worksheet(worksheet)
 
 
+Updating a Worksheet's name and color
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: python
+
+   worksheet.update_title("December Transactions")
+   worksheet.update_tab_color({"red": 1, "green": 0.5, "blue": 0.5})
+
+
 Getting a Cell Value
 ~~~~~~~~~~~~~~~~~~~~
 

diff --git a/gspread/worksheet.py b/gspread/worksheet.py
@@ -200,7 +200,9 @@ def is_gridlines_hidden(self):
 
     @property
     def tab_color(self):
-        """Tab color style."""
+        """Tab color style. Dict with RGB color values.
+        If any of R, G, B are 0, they will not be present in the dict.
+        """
         return self._properties.get("tabColorStyle", {}).get("rgbColor", None)
 
     def _get_sheet_property(self, property, default_value):
@@ -1431,41 +1433,65 @@ def update_title(self, title):
         self._properties["title"] = title
         return response
 
-    def update_tab_color(self, color):
+    def update_tab_color(self, color: dict):
         """Changes the worksheet's tab color.
+        Use clear_tab_color() to remove the color.
 
         :param dict color: The red, green and blue values of the color, between 0 and 1.
         """
+        red, green, blue = color["red"], color["green"], color["blue"]
         body = {
             "requests": [
                 {
                     "updateSheetProperties": {
                         "properties": {
                             "sheetId": self.id,
-                            "tabColor": {
-                                "red": color["red"],
-                                "green": color["green"],
-                                "blue": color["blue"],
-                            },
                             "tabColorStyle": {
                                 "rgbColor": {
-                                    "red": color["red"],
-                                    "green": color["green"],
-                                    "blue": color["blue"],
+                                    "red": red,
+                                    "green": green,
+                                    "blue": blue,
                                 }
                             },
                         },
-                        "fields": "tabColor,tabColorStyle",
+                        "fields": "tabColorStyle",
                     }
                 }
             ]
         }
 
         response = self.spreadsheet.batch_update(body)
-        self._properties["tabColorStyle"] = {
-            "rgbColor": color,
+
+        sheet_color = {
+            "red": red,
+            "green": green,
+            "blue": blue,
         }
-        self._properties["tabColor"] = color
+
+        self._properties["tabColorStyle"] = {"rgbColor": sheet_color}
+        return response
+
+    def clear_tab_color(self):
+        """Clears the worksheet's tab color.
+        Use update_tab_color() to set the color.
+        """
+        body = {
+            "requests": [
+                {
+                    "updateSheetProperties": {
+                        "properties": {
+                            "sheetId": self.id,
+                            "tabColorStyle": {
+                                "rgbColor": None,
+                            },
+                        },
+                        "fields": "tabColorStyle",
+                    },
+                },
+            ],
+        }
+        response = self.spreadsheet.batch_update(body)
+        self._properties.pop("tabColorStyle")
         return response
 
     def update_index(self, index):