improve docstring - add small example

gspread/utils.py

@@ -878,6 +878,35 @@ def get_a1_from_absolute_range(range_name: str) -> str:
     return range_name
 
 
+def to_records(
+    headers: Iterable[Any] = [], values: Iterable[Iterable[Any]] = [[]]
+) -> List[Dict[str, Union[str, int, float]]]:
+    """Builds the list of dictionaries, all of them have the headers sequence as keys set,
+    each key is associated to the corresponding value for the same index in each list from
+    the matrix ``values``.
+    There are as many dictionaries as they are entry in the list of given values.
+
+    :param list: headers the key set for all dictionaries
+    :param list: values a matrix of values
+
+    Examples::
+
+        >>> to_records(["name", "City"], [["Spiderman", "NY"], ["Batman", "Gotham"]])
+        [
+            {
+                "Name": "Spiderman",
+                "City": "NY",
+            },
+            {
+                "Name": "Batman",
+                "City": "Gotham",
+            },
+        ]
+    """
+
+    return [dict(zip(headers, row)) for row in values]
+
+
 # SHOULD NOT BE NEEDED UNTIL NEXT MAJOR VERSION
 # def deprecation_warning(version: str, msg: str) -> None:
 #     """Emit a deprecation warning.

gspread/worksheet.py

@@ -462,6 +462,15 @@ def get_all_records(
         dictionaries holding the contents of subsequent rows of cells as
         values.
 
+        This method uses the function :func:`gspread.utils.to_records` to build the resulting
+        records. It mainly wraps around the function and handle the simplest use case
+        using a header row (default = 1) and the the reste of the entire sheet.
+
+        .. note::
+
+           for any particular use-case, please get your dataset, your headers
+           then use the function :func:`gspread.utils.to_records` to build the records.
+
         Cell values are numericised (strings that can be read as ints or floats
         are converted), unless specified in numericise_ignore