Added a range option to Worksheet.get_notes [Issue #1482]

.github/CONTRIBUTING.md

@@ -6,11 +6,13 @@
 - Make sure unit tests pass. Please read how to run unit tests [below](#run-tests-offline).
 
 - If you are fixing a bug:
+
   - If you are resolving an existing issue, reference the issue ID in a commit message `(e.g., fixed #XXXX)`.
   - If the issue has not been reported, please add a detailed description of the bug in the Pull Request (PR).
   - Please add a regression test case to check the bug is fixed.
 
 - If you are adding a new feature:
+
   - Please open a suggestion issue first.
   - Provide a convincing reason to add this feature and have it greenlighted before working on it.
   - Add tests to cover the functionality.
@@ -110,23 +112,23 @@ In the following cases, you must record new HTTP requests:
 - an existing test is updated and does a new HTTP request
 - gspread is updated and does a new HTTP request
 
-### Run test, capturing *all* HTTP requests
+### Run test, capturing _all_ HTTP requests
 
 In some cases if the test suite can't record new episodes, or it can't replay them offline, you can run a complete update of the cassettes.
 
 ```bash
 GS_CREDS_FILENAME=<./YOUR_CREDS.json> GS_RECORD_MODE=all tox -e py
 ```
 
-### Run test, capturing *only new* HTTP requests
+### Run test, capturing _only new_ HTTP requests
 
 To record new HTTP requests:
 
 1. Remove the file holding the recorded HTTP requests of the test(s).
-  e.g.,
-     1. for the file `tests/cell_test.py`:
-     2. for the test `test_a1_value`
-     3. remove the file `tests/cassettes/CellTest.test_a1_value.json`
+   e.g.,
+   1. for the file `tests/cell_test.py`:
+   2. for the test `test_a1_value`
+   3. remove the file `tests/cassettes/CellTest.test_a1_value.json`
 1. Run the tests with `GS_RECORD_MODE=new_episodes`.
 
 ```bash

gspread/worksheet.py

@@ -2606,8 +2606,12 @@ def unmerge_cells(self, name: str) -> JSONResponse:
 
         return self.client.batch_update(self.spreadsheet_id, body)
 
-    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::
 
@@ -2622,6 +2626,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::
 
@@ -2631,21 +2636,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([])