Merge pull request #1487 from muddi900/add/notes-range

Added a range option to `Worksheet.get_notes` [Issue #1482]
burnash · Oct 7, 2024 · 1960c29 · 1960c29
2 parents d606420 + 58d7368
commit 1960c29
Show file tree

Hide file tree

Showing 4 changed files with 1,846 additions and 257 deletions.
diff --git a/gspread/worksheet.py b/gspread/worksheet.py
@@ -2639,8 +2639,12 @@ def batch_merge(
 
         return self.client.batch_update(self.spreadsheet_id, {"requests": requests})
 
-    def get_notes(self, default_empty_value: Optional[str] = "") -> List[List[str]]:
-        """Returns a list of lists containing all notes in the sheet.
+    def get_notes(
+        self,
+        default_empty_value: Optional[str] = "",
+        grid_range: Optional[str] = None,
+    ) -> List[List[str]]:
+        """Returns a list of lists containing all notes in the sheet or range.
 
         .. note::
 
@@ -2655,6 +2659,7 @@ def get_notes(self, default_empty_value: Optional[str] = "") -> List[List[str]]:
 
         :param str default_empty_value: (optional) Determines which value to use
             for cells without notes, defaults to None.
+        :param str grid_range: (optional) Range name in A1 notation, e.g. 'A1:A5'.
 
         Examples::
 
@@ -2664,21 +2669,32 @@ def get_notes(self, default_empty_value: Optional[str] = "") -> List[List[str]]:
             # 2    -      B2
 
             # Read all notes from the sheet
-            >>> arr = worksheet.get_notes()
-            >>> print(arr)
+            >>> worksheet.get_notes()
             [
                 ["A1"],
                 ["", "B2"]
             ]
-            >>> print(gspread.utils.fill_gaps(arr, len(arr), max(len(a) for a in arr), None))
+            >>> arr = worksheet.get_notes()
+            >>> gspread.utils.fill_gaps(arr, len(arr), max(len(a) for a in arr), None)
             [
                 ["A1", ""],
                 ["", "B2"]
             ]
+            # Read notes from a specific range
+            >>> worksheet.get_notes(grid_range="A2:B2")
+            [
+                ["", "B2"]
+            ]
         """
-        params: ParamsType = {"fields": "sheets.data.rowData.values.note"}
+        params: ParamsType = {
+            "fields": "sheets.data.rowData.values.note",
+            "ranges": absolute_range_name(self.title, grid_range),
+        }
+
         res = self.client.spreadsheets_get(self.spreadsheet_id, params)
-        data = res["sheets"][self.index]["data"][0].get("rowData", [{}])
+
+        # access 0th sheet because we specified a sheet with params["ranges"] above
+        data = res["sheets"][0]["data"][0].get("rowData", [{}])
         notes: List[List[str]] = []
         for row in data:
             notes.append([])