Add insert_note feature (burnash#50)

Add the 'insert_note' and 'clear_note' feature.
Notice:
The request to set a note on a cell with an empty string clears the note.
The 'insert_note' function only accepts string as note content

Signed-off-by: Lavigne958 <[email protected]>

gspread/models.py

@@ -1935,6 +1935,83 @@ def merge_cells(self, name, merge_type="MERGE_ALL"):
 
         return self.spreadsheet.batch_update(body)
 
+    def update_note(self, cell, content):
+        """Update the content of the cell pointed by `cell`.
+
+        :param: str cell A string with a cell coordinates in A1 notation,
+            e.g. 'D7'.
+        :param: str note The text note to insert.
+        """
+
+        if not isinstance(content, str):
+            raise TypeError("Only string allowed as content for a note.")
+
+        (startRow, startColumn) = a1_to_rowcol(cell)
+
+        body = {
+            "requests": [
+                {
+                    "updateCells": {
+                        "range": {
+                            "sheetId": self.id,
+                            "startRowIndex": startRow - 1,
+                            "endRowIndex": startRow,
+                            "startColumnIndex": startColumn - 1,
+                            "endColumnIndex": startColumn,
+                        },
+                        "rows": [
+                            {
+                                "values": [
+                                    {
+                                        "note": content
+                                    }
+                                ]
+                            }
+                        ],
+                        "fields": "note"
+                    }
+                }
+            ]
+        }
+        self.spreadsheet.batch_update(body)
+
+    @cast_to_a1_notation
+    def insert_note(self, cell, content):
+        """Insert a note. The note is attached to a certain cell.
+
+        :param: str cell A string with a cell coordinates in A1 notation,
+            e.g. 'D7'.
+
+        Alternatively, you may specify numeric boundaries. All values
+        index from 1 (one):
+
+        :param int first_row: First row number
+        :param int first_col: First column number
+        :param int last_row: Last row number
+        :param int last_col: Last column number
+
+        :param: str note The text note to insert.
+        """
+        self.update_note(cell, content)
+
+    @cast_to_a1_notation
+    def clear_note(self, cell):
+        """Clear a note. The note is attached to a certain cell.
+
+        :param: str cell A string with a cell coordinates in A1 notation,
+            e.g. 'D7'.
+
+        Alternatively, you may specify numeric boundaries. All values
+        index from 1 (one):
+
+        :param int first_row: First row number
+        :param int first_col: First column number
+        :param int last_row: Last row number
+        :param int last_col: Last column number
+        """
+        # set the note to <empty string> will clear it
+        self.update_note(cell, "")
+
 
 class Cell(object):
     """An instance of this class represents a single cell

tests/test.py

@@ -1132,6 +1132,18 @@ def test_worksheet_update_index(self):
         w = self.spreadsheet.worksheets()
         self.assertEqual(w[0].id, last_sheet.id)
 
+    def test_worksheet_notes(self):
+        w = self.spreadsheet.worksheets()[0]
+
+        # will trigger a Exception in case of any issue
+        w.insert_note("A1", "This is a test note")
+        w.clear_note("A1")
+
+        with self.assertRaises(TypeError) as _:
+            w.insert_note("A1", 42)
+            w.insert_note("A1", ["asddf", "asdfqwebn"])
+            w.insert_note("A1", w)
+
 
 class CellTest(GspreadTest):
     """Test for gspread.Cell."""