python-google-sheets 1.1.0__tar.gz → 1.2.0__tar.gz

{python_google_sheets-1.1.0/python_google_sheets.egg-info → python_google_sheets-1.2.0}/PKG-INFO

@@ -1,10 +1,17 @@
 Metadata-Version: 2.4
 Name: python-google-sheets
-Version: 1.1.0
+Version: 1.2.0
 Summary: A lightweight and efficient Python wrapper for the Google Sheets API v4
 Author-email: Timofey Egorov <timegorr@gmail.com>
 License-Expression: MIT
+Project-URL: Homepage, https://github.com/Timofey28/python-google-sheets
+Project-URL: Issues, https://github.com/Timofey28/python-google-sheets/issues
+Keywords: spreadsheets,google-spreadsheets,google-sheets,api,wrapper,python,pydantic
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -81,7 +88,7 @@ spreadsheet_id, url = GoogleSheets.create_spreadsheet(
 )
 ```
 
-### `update_spreadsheet(spreadsheet_id: str, api_requests: list[dict], service: 'Resource') -> None`
+### `update_spreadsheet(spreadsheet_id: str, api_requests: list[dict], *, service: 'Resource') -> None`
 Execute a `batchUpdate` with one or more request objects.
 
 ```python
@@ -93,7 +100,7 @@ requests = [
 GoogleSheets.update_spreadsheet(spreadsheet_id, requests, service)
 ```
 
-### `copy_sheet(source_spreadsheet_id: str, source_sheet_id: str, destination_spreadsheet_id: str, service: 'Resource') -> SheetProperties`
+### `copy_sheet(source_spreadsheet_id: str, source_sheet_id: str, destination_spreadsheet_id: str, *, service: 'Resource') -> SheetProperties`
 Copy a sheet from one spreadsheet into another.
 
 ```python
@@ -113,19 +120,39 @@ spreadsheet = GoogleSheets.get_spreadsheet(spreadsheet_id, service)
 print([sheet.properties.title for sheet in spreadsheet.sheets])
 ```
 
-### `get_spreadsheet_range_values(spreadsheet_id: str, sheets: list[str | int], ranges: list[list[str]], service: 'Resource') -> list[list[SimpleType] | list[list[SimpleType]]]`
-Read values from multiple ranges across one or more sheets.
+### `get_spreadsheet_range_values(spreadsheet_id: str, sheets: list[str | int] | str | int, ranges: list[list[str]] | list[str] | str, *, by_columns: bool = False, service: 'Resource') -> list[list[RangeData]] | None:`
+Reads values from multiple ranges across multiple sheets. Returns a matrix of values (RangeData - list[list[SimpleType]]) for each range of each sheet. Returns None if an error occurs.
+
+Code from this example returns one range from sheet with id `1601337967` and three ranges from sheet `Summary` (assuming that these sheets exist in the spreadsheet). You can mix and match sheet names and ids as needed.
 
 ```python
 values = GoogleSheets.get_spreadsheet_range_values(
-    spreadsheet_id=spreadsheet_id,
-    sheets=[0, 'Summary'],
-    ranges=[['A2:C8'], ['B2:B12']],
-    service=service,
+    spreadsheet_id=SPREADSHEET_ID,
+    sheets=[1601337967, 'Summary'],
+    ranges=[['A2:C100'], ['A1:E10', 'F1:F10', 'H1']],
+    service=service
 )
-print(values)
 ```
 
+Next two examples return the same data (assuming that sheet `Sheet1` exists and has id `0`). With `by_columns=True` the values are grouped by columns instead of rows.
+```python
+values = GoogleSheets.get_spreadsheet_range_values(
+    SPREADSHEET_ID,
+    sheets='Sheet1',
+    ranges=['A1:E5'],
+    by_columns=True,
+    service=service
+)
+```
+```python
+values = GoogleSheets.get_spreadsheet_range_values(
+    SPREADSHEET_ID,
+    sheets=0,
+    ranges='A1:E5',
+    by_columns=True,
+    service=service
+)
+```
 ---
 
 ## `ApiRequest` methods for `batchUpdate`
@@ -154,7 +181,7 @@ req = ApiRequest.update_cells(
 ---
 ### Conditional formatting
 
-### `add_boolean_format_rule(*, sheet_id: int, ranges: list[str], condition_type: ConditionType, condition_values: list[ConditionValue] = None, cell_format: CellFormat) -> dict`
+### `add_boolean_format_rule(sheet_id: int, ranges: list[str], condition_type: ConditionType, *, condition_values: list[ConditionValue] = None, cell_format: CellFormat) -> dict`
 Add a rule (for example, highlight values greater than `100`).
 
 ```python
@@ -172,7 +199,7 @@ req = ApiRequest.add_boolean_format_rule(
 )
 ```
 
-### `GradientRule.add(*, sheet_id: int, ranges: list[str], interpolation_points: tuple[IPTypeAndValue, IPTypeAndValue] | tuple[IPTypeAndValue, IPTypeAndValue, IPTypeAndValue], interpolation_point_colors: tuple[ColorStyle, ColorStyle] | tuple[ColorStyle, ColorStyle, ColorStyle]) -> dict`
+### `GradientRule.add(sheet_id: int, *, ranges: list[str], interpolation_points: tuple[IPTypeAndValue, IPTypeAndValue] | tuple[IPTypeAndValue, IPTypeAndValue, IPTypeAndValue], interpolation_point_colors: tuple[ColorStyle, ColorStyle] | tuple[ColorStyle, ColorStyle, ColorStyle]) -> dict`
 Add a custom color scale with 2 or 3 interpolation points.
 
 ```python
@@ -194,7 +221,7 @@ req = ApiRequest.GradientRule.add(
 )
 ```
 
-### `GradientRule.add_preset(*, sheet_id: int, ranges: list[str], preset: Preset) -> dict`
+### `GradientRule.add_preset(sheet_id: int, ranges: list[str], preset: Preset) -> dict`
 Add a gradient rule from a built-in preset.
 
 ```python
@@ -205,14 +232,14 @@ req = ApiRequest.GradientRule.add_preset(
 )
 ```
 
-### `delete_conditional_format_rule(*, sheet_id: int, index: int) -> dict`
+### `delete_conditional_format_rule(sheet_id: int, *, index: int) -> dict`
 Delete a conditional format rule by index.
 
 ```python
 req = ApiRequest.delete_conditional_format_rule(sheet_id=0, index=0)
 ```
 
-### `update_conditional_format_rule(*, sheet_id: int, index: int, rule: ConditionalFormatRule) -> dict`
+### `update_conditional_format_rule(sheet_id: int, *, index: int, rule: ConditionalFormatRule) -> dict`
 Replace an existing conditional format rule by index.
 
 ```python
@@ -300,7 +327,7 @@ Delete a sheet.
 req = ApiRequest.delete_sheet(sheet_id=3)
 ```
 
-### `add_sheet(*, sheet_id: int = None, title: str = None, index: int = None, hidden: bool = None, row_count: int = None, column_count: int = None, frozen_row_count: int = None, frozen_column_count: int = None, hide_grid_lines: bool = None) -> dict`
+### `add_sheet(sheet_id: int = None, *, title: str = None, index: int = None, hidden: bool = None, row_count: int = None, column_count: int = None, frozen_row_count: int = None, frozen_column_count: int = None, hide_grid_lines: bool = None) -> dict`
 Create a new sheet with optional properties.
 
 ```python
@@ -322,7 +349,7 @@ Merge cells in a range.
 req = ApiRequest.merge_cells(sheet_id=0, range_='A1:C1')
 ```
 
-### `unmerge_cells(sheet_id: int, range_: str = None, start_row: int = None, end_row: int = None, start_column: int | str = None, end_column: int | str = None) -> dict`
+### `unmerge_cells(sheet_id: int, *, range_: str = None, start_row: int = None, end_row: int = None, start_column: int | str = None, end_column: int | str = None) -> dict`
 Unmerge cells in a range (or by explicit indexes).
 
 ```python
@@ -339,14 +366,14 @@ req = ApiRequest.freeze(sheet_id=0, rows=1, columns=1)
 ---
 ### Rows and columns
 
-### `insert_rows(sheet_id: int, start_index: int, end_index: int = None, inherit_from_before: bool = True) -> dict`
+### `insert_rows(sheet_id: int, start_index: int, end_index: int = None, *, inherit_from_before: bool = True) -> dict`
 Insert one or more rows (Indexes are zero-based and inclusive [start_index, end_index]).
 
 ```python
 req = ApiRequest.insert_rows(sheet_id=0, start_index=5, end_index=9)
 ```
 
-### `insert_columns(sheet_id: int, start_index: int, end_index: int = None, inherit_from_before: bool = True) -> dict`
+### `insert_columns(sheet_id: int, start_index: int, end_index: int = None, *, inherit_from_before: bool = True) -> dict`
 Insert columns (Indexes are zero-based and inclusive [start_index, end_index]).
 
 ```python

python_google_sheets-1.1.0/PKG-INFO → python_google_sheets-1.2.0/README.md

@@ -1,19 +1,3 @@
-Metadata-Version: 2.4
-Name: python-google-sheets
-Version: 1.1.0
-Summary: A lightweight and efficient Python wrapper for the Google Sheets API v4
-Author-email: Timofey Egorov <timegorr@gmail.com>
-License-Expression: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: google-auth
-Requires-Dist: google-api-python-client
-Requires-Dist: pydantic>=2.0.0
-Dynamic: license-file
-
 # python-google-sheets
 
 A lightweight and efficient Python wrapper for the Google Sheets API v4, leveraging `service account` credentials for seamless authentication.
@@ -81,7 +65,7 @@ spreadsheet_id, url = GoogleSheets.create_spreadsheet(
 )
 ```
 
-### `update_spreadsheet(spreadsheet_id: str, api_requests: list[dict], service: 'Resource') -> None`
+### `update_spreadsheet(spreadsheet_id: str, api_requests: list[dict], *, service: 'Resource') -> None`
 Execute a `batchUpdate` with one or more request objects.
 
 ```python
@@ -93,7 +77,7 @@ requests = [
 GoogleSheets.update_spreadsheet(spreadsheet_id, requests, service)
 ```
 
-### `copy_sheet(source_spreadsheet_id: str, source_sheet_id: str, destination_spreadsheet_id: str, service: 'Resource') -> SheetProperties`
+### `copy_sheet(source_spreadsheet_id: str, source_sheet_id: str, destination_spreadsheet_id: str, *, service: 'Resource') -> SheetProperties`
 Copy a sheet from one spreadsheet into another.
 
 ```python
@@ -113,19 +97,39 @@ spreadsheet = GoogleSheets.get_spreadsheet(spreadsheet_id, service)
 print([sheet.properties.title for sheet in spreadsheet.sheets])
 ```
 
-### `get_spreadsheet_range_values(spreadsheet_id: str, sheets: list[str | int], ranges: list[list[str]], service: 'Resource') -> list[list[SimpleType] | list[list[SimpleType]]]`
-Read values from multiple ranges across one or more sheets.
+### `get_spreadsheet_range_values(spreadsheet_id: str, sheets: list[str | int] | str | int, ranges: list[list[str]] | list[str] | str, *, by_columns: bool = False, service: 'Resource') -> list[list[RangeData]] | None:`
+Reads values from multiple ranges across multiple sheets. Returns a matrix of values (RangeData - list[list[SimpleType]]) for each range of each sheet. Returns None if an error occurs.
+
+Code from this example returns one range from sheet with id `1601337967` and three ranges from sheet `Summary` (assuming that these sheets exist in the spreadsheet). You can mix and match sheet names and ids as needed.
 
 ```python
 values = GoogleSheets.get_spreadsheet_range_values(
-    spreadsheet_id=spreadsheet_id,
-    sheets=[0, 'Summary'],
-    ranges=[['A2:C8'], ['B2:B12']],
-    service=service,
+    spreadsheet_id=SPREADSHEET_ID,
+    sheets=[1601337967, 'Summary'],
+    ranges=[['A2:C100'], ['A1:E10', 'F1:F10', 'H1']],
+    service=service
 )
-print(values)
 ```
 
+Next two examples return the same data (assuming that sheet `Sheet1` exists and has id `0`). With `by_columns=True` the values are grouped by columns instead of rows.
+```python
+values = GoogleSheets.get_spreadsheet_range_values(
+    SPREADSHEET_ID,
+    sheets='Sheet1',
+    ranges=['A1:E5'],
+    by_columns=True,
+    service=service
+)
+```
+```python
+values = GoogleSheets.get_spreadsheet_range_values(
+    SPREADSHEET_ID,
+    sheets=0,
+    ranges='A1:E5',
+    by_columns=True,
+    service=service
+)
+```
 ---
 
 ## `ApiRequest` methods for `batchUpdate`
@@ -154,7 +158,7 @@ req = ApiRequest.update_cells(
 ---
 ### Conditional formatting
 
-### `add_boolean_format_rule(*, sheet_id: int, ranges: list[str], condition_type: ConditionType, condition_values: list[ConditionValue] = None, cell_format: CellFormat) -> dict`
+### `add_boolean_format_rule(sheet_id: int, ranges: list[str], condition_type: ConditionType, *, condition_values: list[ConditionValue] = None, cell_format: CellFormat) -> dict`
 Add a rule (for example, highlight values greater than `100`).
 
 ```python
@@ -172,7 +176,7 @@ req = ApiRequest.add_boolean_format_rule(
 )
 ```
 
-### `GradientRule.add(*, sheet_id: int, ranges: list[str], interpolation_points: tuple[IPTypeAndValue, IPTypeAndValue] | tuple[IPTypeAndValue, IPTypeAndValue, IPTypeAndValue], interpolation_point_colors: tuple[ColorStyle, ColorStyle] | tuple[ColorStyle, ColorStyle, ColorStyle]) -> dict`
+### `GradientRule.add(sheet_id: int, *, ranges: list[str], interpolation_points: tuple[IPTypeAndValue, IPTypeAndValue] | tuple[IPTypeAndValue, IPTypeAndValue, IPTypeAndValue], interpolation_point_colors: tuple[ColorStyle, ColorStyle] | tuple[ColorStyle, ColorStyle, ColorStyle]) -> dict`
 Add a custom color scale with 2 or 3 interpolation points.
 
 ```python
@@ -194,7 +198,7 @@ req = ApiRequest.GradientRule.add(
 )
 ```
 
-### `GradientRule.add_preset(*, sheet_id: int, ranges: list[str], preset: Preset) -> dict`
+### `GradientRule.add_preset(sheet_id: int, ranges: list[str], preset: Preset) -> dict`
 Add a gradient rule from a built-in preset.
 
 ```python
@@ -205,14 +209,14 @@ req = ApiRequest.GradientRule.add_preset(
 )
 ```
 
-### `delete_conditional_format_rule(*, sheet_id: int, index: int) -> dict`
+### `delete_conditional_format_rule(sheet_id: int, *, index: int) -> dict`
 Delete a conditional format rule by index.
 
 ```python
 req = ApiRequest.delete_conditional_format_rule(sheet_id=0, index=0)
 ```
 
-### `update_conditional_format_rule(*, sheet_id: int, index: int, rule: ConditionalFormatRule) -> dict`
+### `update_conditional_format_rule(sheet_id: int, *, index: int, rule: ConditionalFormatRule) -> dict`
 Replace an existing conditional format rule by index.
 
 ```python
@@ -300,7 +304,7 @@ Delete a sheet.
 req = ApiRequest.delete_sheet(sheet_id=3)
 ```
 
-### `add_sheet(*, sheet_id: int = None, title: str = None, index: int = None, hidden: bool = None, row_count: int = None, column_count: int = None, frozen_row_count: int = None, frozen_column_count: int = None, hide_grid_lines: bool = None) -> dict`
+### `add_sheet(sheet_id: int = None, *, title: str = None, index: int = None, hidden: bool = None, row_count: int = None, column_count: int = None, frozen_row_count: int = None, frozen_column_count: int = None, hide_grid_lines: bool = None) -> dict`
 Create a new sheet with optional properties.
 
 ```python
@@ -322,7 +326,7 @@ Merge cells in a range.
 req = ApiRequest.merge_cells(sheet_id=0, range_='A1:C1')
 ```
 
-### `unmerge_cells(sheet_id: int, range_: str = None, start_row: int = None, end_row: int = None, start_column: int | str = None, end_column: int | str = None) -> dict`
+### `unmerge_cells(sheet_id: int, *, range_: str = None, start_row: int = None, end_row: int = None, start_column: int | str = None, end_column: int | str = None) -> dict`
 Unmerge cells in a range (or by explicit indexes).
 
 ```python
@@ -339,14 +343,14 @@ req = ApiRequest.freeze(sheet_id=0, rows=1, columns=1)
 ---
 ### Rows and columns
 
-### `insert_rows(sheet_id: int, start_index: int, end_index: int = None, inherit_from_before: bool = True) -> dict`
+### `insert_rows(sheet_id: int, start_index: int, end_index: int = None, *, inherit_from_before: bool = True) -> dict`
 Insert one or more rows (Indexes are zero-based and inclusive [start_index, end_index]).
 
 ```python
 req = ApiRequest.insert_rows(sheet_id=0, start_index=5, end_index=9)
 ```
 
-### `insert_columns(sheet_id: int, start_index: int, end_index: int = None, inherit_from_before: bool = True) -> dict`
+### `insert_columns(sheet_id: int, start_index: int, end_index: int = None, *, inherit_from_before: bool = True) -> dict`
 Insert columns (Indexes are zero-based and inclusive [start_index, end_index]).
 
 ```python
@@ -505,4 +509,4 @@ GoogleSheets.update_spreadsheet(spreadsheet_id, requests, service)
 If you have any questions, encounter issues, or want to suggest improvements:
 
 - **Bug Reports & Feature Requests:** Please use [GitHub Issues](https://github.com/Timofey28/python-google-sheets/issues) to report bugs or submit ideas.
-- **Questions:** For general inquiries or help with integration, feel free to reach out via email at [timegorr@gmail.com](mailto:timegorr@gmail.com).
+- **Questions:** For general inquiries or help with integration, feel free to reach out via email at [timegorr@gmail.com](mailto:timegorr@gmail.com).

{python_google_sheets-1.1.0 → python_google_sheets-1.2.0}/google_sheets/api_request.py

@@ -112,10 +112,10 @@ class ApiRequest:
 
     @staticmethod
     def add_boolean_format_rule(
-            *,
             sheet_id: int,
             ranges: list[str],
             condition_type: ConditionType,
+            *,
             condition_values: list[ConditionValue] = None,
             cell_format: CellFormat,
     ) -> dict:
@@ -143,8 +143,8 @@ class ApiRequest:
 
         @staticmethod
         def add(
-                *,
                 sheet_id: int,
+                *,
                 ranges: list[str],
                 interpolation_points: tuple[IPTypeAndValue, IPTypeAndValue] | tuple[IPTypeAndValue, IPTypeAndValue, IPTypeAndValue],
                 interpolation_point_colors: tuple[ColorStyle, ColorStyle] | tuple[ColorStyle, ColorStyle, ColorStyle],
@@ -210,10 +210,11 @@ class ApiRequest:
             RED_YELLOW_GREEN_PERCENT = 'RED_YELLOW_GREEN_PERCENT'
 
         @staticmethod
-        def add_preset(*, sheet_id: int, ranges: list[str], preset: Preset) -> dict:
+        def add_preset(sheet_id: int, ranges: list[str], preset: Preset) -> dict:
             grid_ranges = [GridRange(sheet_id=sheet_id, **ApiRequest._split_excel_range(range_, return_as_dict=True)) for range_ in ranges]
             AGP = ApiRequest.GradientRule.Preset
 
+            # Two interpolation points presets
             if preset in (AGP.WHITE_GREEN, AGP.WHITE_YELLOW, AGP.WHITE_RED, AGP.GREEN_WHITE, AGP.YELLOW_WHITE, AGP.RED_WHITE):
                 if preset == AGP.WHITE_YELLOW:
                     minpoint_color_style, maxpoint_color_style = Color_.Basic.WHITE, Color_.ConditionalFormatting.YELLOW
@@ -242,7 +243,7 @@ class ApiRequest:
                     )
                 )).dict()
 
-            else:  # three interpolation points
+            else:  # Three interpolation points presets
                 if preset in (AGP.RED_WHITE_GREEN_PERCENTILE, AGP.RED_WHITE_GREEN_PERCENT):
                     minpoint_cs, midpoint_cs, maxpoint_cs = Color_.ConditionalFormatting.RED, Color_.Basic.WHITE, Color_.ConditionalFormatting.GREEN
                     midpoint_type = InterpolationPointType.PERCENTILE if preset == AGP.RED_WHITE_GREEN_PERCENTILE else InterpolationPointType.PERCENT
@@ -276,11 +277,11 @@ class ApiRequest:
                 )).dict()
 
     @staticmethod
-    def delete_conditional_format_rule(*, sheet_id: int, index: int) -> dict:
+    def delete_conditional_format_rule(sheet_id: int, *, index: int) -> dict:
         return DeleteConditionalFormatRule(sheet_id=sheet_id, index=index).dict()
 
     @staticmethod
-    def update_conditional_format_rule(*, sheet_id: int, index: int, rule: ConditionalFormatRule) -> dict:
+    def update_conditional_format_rule(sheet_id: int, *, index: int, rule: ConditionalFormatRule) -> dict:
         return UpdateConditionalFormatRule(sheet_id=sheet_id, index=index, rule=rule).dict()
 
     @staticmethod
@@ -341,6 +342,7 @@ class ApiRequest:
     @staticmethod
     def unmerge_cells(
             sheet_id: int,
+            *,
             range_: str = None,
             start_row: int = None,
             end_row: int = None,
@@ -377,7 +379,7 @@ class ApiRequest:
         ).dict()
 
     @staticmethod
-    def insert_rows(sheet_id: int, start_index: int, end_index: int = None, inherit_from_before: bool = True) -> dict:
+    def insert_rows(sheet_id: int, start_index: int, end_index: int = None, *, inherit_from_before: bool = True) -> dict:
         """
         Indexes are zero-based and inclusive [start_index, end_index]. If end_index is not specified, then a single
         row will be inserted at start_index.
@@ -394,7 +396,7 @@ class ApiRequest:
         ).dict()
 
     @staticmethod
-    def insert_columns(sheet_id: int, start_index: int, end_index: int = None, inherit_from_before: bool = True) -> dict:
+    def insert_columns(sheet_id: int, start_index: int, end_index: int = None, *, inherit_from_before: bool = True) -> dict:
         """
         Indexes are zero-based and inclusive [start_index, end_index]. If end_index is not specified, then a single
         column will be inserted at start_index.
@@ -549,8 +551,8 @@ class ApiRequest:
 
     @staticmethod
     def add_sheet(
-            *,
             sheet_id: int = None,
+            *,
             title: str = None,
             index: int = None,
             hidden: bool = None,
@@ -575,7 +577,7 @@ class ApiRequest:
         )).dict()
 
     @staticmethod
-    def _split_excel_range(range_: str, return_as_dict: bool = False) -> tuple[int, int, int, int] | dict[str, int]:
+    def _split_excel_range(range_: str, *, return_as_dict: bool = False) -> tuple[int, int, int, int] | dict[str, int]:
         if ':' in range_:
             match = re.match(r'([A-Z]+)(\d+):([A-Z]+)(\d+)$', range_)
             if not match:

{python_google_sheets-1.1.0 → python_google_sheets-1.2.0}/google_sheets/google_sheets.py

@@ -4,7 +4,7 @@ from google.oauth2.service_account import Credentials
 from googleapiclient.discovery import build
 from googleapiclient.errors import HttpError
 
-from .spreadsheet_requests import Spreadsheet, SheetProperties, SimpleType
+from .spreadsheet_requests import Spreadsheet, SheetProperties, RangeData, Dimension, ValueRenderOption, DateTimeRenderOption
 
 if TYPE_CHECKING:
     from googleapiclient.discovery import Resource  # noqa
@@ -85,7 +85,7 @@ class GoogleSheets:
         return spreadsheet_id, f'https://docs.google.com/spreadsheets/d/{spreadsheet_id}'
 
     @staticmethod
-    def update_spreadsheet(spreadsheet_id: str, api_requests: list[dict], service: 'Resource') -> None:
+    def update_spreadsheet(spreadsheet_id: str, api_requests: list[dict], *, service: 'Resource') -> None:
         """
         Updates Google Sheet with the specified API requests.
 
@@ -100,7 +100,7 @@ class GoogleSheets:
             raise e
 
     @staticmethod
-    def copy_sheet(source_spreadsheet_id: str, source_sheet_id: str, destination_spreadsheet_id: str, service: 'Resource') -> SheetProperties:
+    def copy_sheet(source_spreadsheet_id: str, source_sheet_id: str, destination_spreadsheet_id: str, *, service: 'Resource') -> SheetProperties:
         request = service.spreadsheets().sheets().copyTo(
             spreadsheetId=source_spreadsheet_id,
             sheetId=source_sheet_id,
@@ -118,63 +118,75 @@ class GoogleSheets:
     @staticmethod
     def get_spreadsheet_range_values(
             spreadsheet_id: str,
-            sheets: list[str | int],
-            ranges: list[list[str]],
+            sheets: list[str | int] | str | int,
+            ranges: list[list[str]] | list[str] | str,
+            *,
+            by_columns: bool = False,
             service: 'Resource'
-    ) -> list[list[SimpleType] | list[list[SimpleType]]]:
+    ) -> list[list[RangeData]] | None:
         """
         Reads values from the specified ranges of the table.
         IMPORTANT: If the last cells in the range are empty, they will be omitted. If all cells are empty, an empty
                    list will be returned for that range. However, leading empty cells are preserved and will appear in
-                   the result
+                   the result.
 
         Args:
-            spreadsheet_id (str): ID of the table
-            sheets (list[str | int]): Name or ID of the sheets to read from
-            ranges (list[list[str]]): List of ranges from each sheet to read in A1 notation
-            service (googleapiclient.discovery.Resource): Google Sheets service object
+            spreadsheet_id (str): ID of the table.
+            sheets (list[str | int] | str | int): Name or ID of the sheet(s).
+            ranges (list[list[str]] | list[str] | str): Single range or list of ranges from each sheet in A1 notation.
+            by_columns (bool, optional): If True, returns data organized by columns instead of rows. Defaults to False.
+            service (googleapiclient.discovery.Resource): Google Sheets service object.
 
         Returns:
-            list[list[SimpleType] | list[list[SimpleType]]]: List of values from the specified ranges. Each range
-            corresponds to an element in the list. If the range is a single row or a single column, a list of values
-            is returned Otherwise, a list of lists of values is returned.
+            list[list[RangeData]] | None: For each range of each sheet, returns a matrix of values (RangeData - list[list[SimpleType]]). Returns None if an error occurs.
         """
-        assert len(sheets) == len(ranges), 'sheets and ranges must have the same length'
+        assert \
+        (  # sheets: list[str | int], ranges: list[list[str]]
+            isinstance(sheets, list) and not isinstance(sheets[0], list) and
+            isinstance(ranges, list) and isinstance(ranges[0], list) and not isinstance(ranges[0][0], list) and
+            len(sheets) == len(ranges)
+        ) or (  # sheets: str | int, ranges: list[str] | str
+            (isinstance(sheets, str) or isinstance(sheets, int)) and
+            (isinstance(ranges, list) and not isinstance(ranges[0], list) or isinstance(ranges, str))
+        ), 'sheets and ranges must be either list[str | int] and list[list[str]] respectively and same size, or str | int and list[str] | str respectively'
+
+        # Normalize sheets and ranges to list[str | int] and list[list[str]] respectively
+        if isinstance(ranges, str):
+            ranges = [ranges]
+        if isinstance(sheets, str) or isinstance(sheets, int):
+            sheets = [sheets]
+            ranges = [ranges]
 
         ranges_processed = []
+        ss = None
         if any(isinstance(sheet, int) for sheet in sheets):
             ss = GoogleSheets.get_spreadsheet(spreadsheet_id, service)
-            for i in range(len(sheets)):
-                if isinstance(sheets[i], int):
-                    try:
-                        sheets[i] = next(sht.properties.title for sht in ss.sheets if sht.properties.sheet_id == sheets[i])
-                    except StopIteration:
-                        return [[]]
-                ranges_processed.extend([f'{sheets[i]}!{range_}' for range_ in ranges[i]])
+        for sheet_id_or_name, sheet_ranges in zip(sheets, ranges):
+            if isinstance(sheet_id_or_name, int):
+                try:
+                    sheet_name = next(sht.properties.title for sht in ss.sheets if sht.properties.sheet_id == sheet_id_or_name)
+                except StopIteration:
+                    return None
+            else:
+                sheet_name = sheet_id_or_name
+            ranges_processed.extend([f'{sheet_name}!{range_}' for range_ in sheet_ranges])
 
         try:
             response = service.spreadsheets().values().batchGet(
                 spreadsheetId=spreadsheet_id,
                 ranges=ranges_processed,
-                valueRenderOption='UNFORMATTED_VALUE',
-                dateTimeRenderOption='FORMATTED_STRING'
+                majorDimension=Dimension.COLUMNS if by_columns else Dimension.ROWS,
+                valueRenderOption=ValueRenderOption.UNFORMATTED_VALUE,
+                dateTimeRenderOption=DateTimeRenderOption.FORMATTED_STRING
             ).execute(num_retries=5)
-        except HttpError as e:
-            raise e
+        except HttpError:
+            return None
         else:
             result = []
-            for value_range in response['valueRanges']:
-                values = value_range.get('values', [])
-                if not values:
-                    result.append([])
-                    continue
-
-                if len(values) == 1:  # If range is a single row
-                    result.append(values[0])
-                else:
-                    if max([len(row) for row in values]) <= 1:  # If range is a single column
-                        result.append([(row[0] if row else '') for row in values])
-                    else:
-                        result.append(values)
-
+            value_ranges = iter(response.get('valueRanges', []))
+            for sheet_no in range(len(ranges)):
+                sheet_ranges = []
+                for range_no in range(len(ranges[sheet_no])):
+                    sheet_ranges.append(next(value_ranges).get('values', []))
+                result.append(sheet_ranges)
             return result

{python_google_sheets-1.1.0 → python_google_sheets-1.2.0}/google_sheets/spreadsheet_requests/__init__.py

@@ -59,9 +59,12 @@ from .spreadsheet import (
 )
 
 from .general_models import (
+    ValueRenderOption,
+    DateTimeRenderOption,
     Color,
     ColorStyle,
     GridRange,
     FieldMask,
     SimpleType,
+    RangeData,
 )

{python_google_sheets-1.1.0 → python_google_sheets-1.2.0}/google_sheets/spreadsheet_requests/general_models.py

@@ -4,6 +4,18 @@ from pydantic import BaseModel, Field, model_validator
 
 
 SimpleType = str | int | float | bool
+RangeData = list[list[SimpleType]]
+
+
+class ValueRenderOption(StrEnum):
+    FORMATTED_VALUE = 'FORMATTED_VALUE'  # Calculated & formatted according to the cell's formatting. DEFAULT value.
+    UNFORMATTED_VALUE = 'UNFORMATTED_VALUE'  # Calculated, not formatted (e.g. 123.45 instead of $123.45).
+    FORMULA = 'FORMULA'  # The formula as entered in the cell, e.g. '=SUM(A1:B1)'. If the cell contains a formula, this field will start with an '=' sign.
+
+
+class DateTimeRenderOption(StrEnum):
+    SERIAL_NUMBER = 'SERIAL_NUMBER'  # A number, where 1 corresponds to December 30, 1899. DEFAULT value.
+    FORMATTED_STRING = 'FORMATTED_STRING'  # A string, formatted according to the cell's formatting.
 
 
 class ThemeColorType(StrEnum):

{python_google_sheets-1.1.0 → python_google_sheets-1.2.0}/pyproject.toml

@@ -6,11 +6,16 @@ build-backend = "setuptools.build_meta"
 name = "python-google-sheets"
 description = "A lightweight and efficient Python wrapper for the Google Sheets API v4"
 authors = [{ name = "Timofey Egorov", email = "timegorr@gmail.com" }]
-version = "1.1.0"
+version = "1.2.0"
 readme = "README.md"
 requires-python = ">=3.11"
+keywords = ["spreadsheets", "google-spreadsheets", "google-sheets", "api", "wrapper", "python", "pydantic"]
 classifiers = [
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Operating System :: OS Independent",
 ]
 dependencies = [
@@ -19,4 +24,8 @@ dependencies = [
     "pydantic>=2.0.0",
 ]
 license = "MIT"
-license-files = ["LICEN[CS]E*"]
+license-files = ["LICENSE*"]
+
+[project.urls]
+Homepage = "https://github.com/Timofey28/python-google-sheets"
+Issues = "https://github.com/Timofey28/python-google-sheets/issues"

python_google_sheets-1.1.0/README.md → python_google_sheets-1.2.0/python_google_sheets.egg-info/PKG-INFO

@@ -1,3 +1,26 @@
+Metadata-Version: 2.4
+Name: python-google-sheets
+Version: 1.2.0
+Summary: A lightweight and efficient Python wrapper for the Google Sheets API v4
+Author-email: Timofey Egorov <timegorr@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Timofey28/python-google-sheets
+Project-URL: Issues, https://github.com/Timofey28/python-google-sheets/issues
+Keywords: spreadsheets,google-spreadsheets,google-sheets,api,wrapper,python,pydantic
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-auth
+Requires-Dist: google-api-python-client
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
 # python-google-sheets
 
 A lightweight and efficient Python wrapper for the Google Sheets API v4, leveraging `service account` credentials for seamless authentication.
@@ -65,7 +88,7 @@ spreadsheet_id, url = GoogleSheets.create_spreadsheet(
 )
 ```
 
-### `update_spreadsheet(spreadsheet_id: str, api_requests: list[dict], service: 'Resource') -> None`
+### `update_spreadsheet(spreadsheet_id: str, api_requests: list[dict], *, service: 'Resource') -> None`
 Execute a `batchUpdate` with one or more request objects.
 
 ```python
@@ -77,7 +100,7 @@ requests = [
 GoogleSheets.update_spreadsheet(spreadsheet_id, requests, service)
 ```
 
-### `copy_sheet(source_spreadsheet_id: str, source_sheet_id: str, destination_spreadsheet_id: str, service: 'Resource') -> SheetProperties`
+### `copy_sheet(source_spreadsheet_id: str, source_sheet_id: str, destination_spreadsheet_id: str, *, service: 'Resource') -> SheetProperties`
 Copy a sheet from one spreadsheet into another.
 
 ```python
@@ -97,19 +120,39 @@ spreadsheet = GoogleSheets.get_spreadsheet(spreadsheet_id, service)
 print([sheet.properties.title for sheet in spreadsheet.sheets])
 ```
 
-### `get_spreadsheet_range_values(spreadsheet_id: str, sheets: list[str | int], ranges: list[list[str]], service: 'Resource') -> list[list[SimpleType] | list[list[SimpleType]]]`
-Read values from multiple ranges across one or more sheets.
+### `get_spreadsheet_range_values(spreadsheet_id: str, sheets: list[str | int] | str | int, ranges: list[list[str]] | list[str] | str, *, by_columns: bool = False, service: 'Resource') -> list[list[RangeData]] | None:`
+Reads values from multiple ranges across multiple sheets. Returns a matrix of values (RangeData - list[list[SimpleType]]) for each range of each sheet. Returns None if an error occurs.
+
+Code from this example returns one range from sheet with id `1601337967` and three ranges from sheet `Summary` (assuming that these sheets exist in the spreadsheet). You can mix and match sheet names and ids as needed.
 
 ```python
 values = GoogleSheets.get_spreadsheet_range_values(
-    spreadsheet_id=spreadsheet_id,
-    sheets=[0, 'Summary'],
-    ranges=[['A2:C8'], ['B2:B12']],
-    service=service,
+    spreadsheet_id=SPREADSHEET_ID,
+    sheets=[1601337967, 'Summary'],
+    ranges=[['A2:C100'], ['A1:E10', 'F1:F10', 'H1']],
+    service=service
 )
-print(values)
 ```
 
+Next two examples return the same data (assuming that sheet `Sheet1` exists and has id `0`). With `by_columns=True` the values are grouped by columns instead of rows.
+```python
+values = GoogleSheets.get_spreadsheet_range_values(
+    SPREADSHEET_ID,
+    sheets='Sheet1',
+    ranges=['A1:E5'],
+    by_columns=True,
+    service=service
+)
+```
+```python
+values = GoogleSheets.get_spreadsheet_range_values(
+    SPREADSHEET_ID,
+    sheets=0,
+    ranges='A1:E5',
+    by_columns=True,
+    service=service
+)
+```
 ---
 
 ## `ApiRequest` methods for `batchUpdate`
@@ -138,7 +181,7 @@ req = ApiRequest.update_cells(
 ---
 ### Conditional formatting
 
-### `add_boolean_format_rule(*, sheet_id: int, ranges: list[str], condition_type: ConditionType, condition_values: list[ConditionValue] = None, cell_format: CellFormat) -> dict`
+### `add_boolean_format_rule(sheet_id: int, ranges: list[str], condition_type: ConditionType, *, condition_values: list[ConditionValue] = None, cell_format: CellFormat) -> dict`
 Add a rule (for example, highlight values greater than `100`).
 
 ```python
@@ -156,7 +199,7 @@ req = ApiRequest.add_boolean_format_rule(
 )
 ```
 
-### `GradientRule.add(*, sheet_id: int, ranges: list[str], interpolation_points: tuple[IPTypeAndValue, IPTypeAndValue] | tuple[IPTypeAndValue, IPTypeAndValue, IPTypeAndValue], interpolation_point_colors: tuple[ColorStyle, ColorStyle] | tuple[ColorStyle, ColorStyle, ColorStyle]) -> dict`
+### `GradientRule.add(sheet_id: int, *, ranges: list[str], interpolation_points: tuple[IPTypeAndValue, IPTypeAndValue] | tuple[IPTypeAndValue, IPTypeAndValue, IPTypeAndValue], interpolation_point_colors: tuple[ColorStyle, ColorStyle] | tuple[ColorStyle, ColorStyle, ColorStyle]) -> dict`
 Add a custom color scale with 2 or 3 interpolation points.
 
 ```python
@@ -178,7 +221,7 @@ req = ApiRequest.GradientRule.add(
 )
 ```
 
-### `GradientRule.add_preset(*, sheet_id: int, ranges: list[str], preset: Preset) -> dict`
+### `GradientRule.add_preset(sheet_id: int, ranges: list[str], preset: Preset) -> dict`
 Add a gradient rule from a built-in preset.
 
 ```python
@@ -189,14 +232,14 @@ req = ApiRequest.GradientRule.add_preset(
 )
 ```
 
-### `delete_conditional_format_rule(*, sheet_id: int, index: int) -> dict`
+### `delete_conditional_format_rule(sheet_id: int, *, index: int) -> dict`
 Delete a conditional format rule by index.
 
 ```python
 req = ApiRequest.delete_conditional_format_rule(sheet_id=0, index=0)
 ```
 
-### `update_conditional_format_rule(*, sheet_id: int, index: int, rule: ConditionalFormatRule) -> dict`
+### `update_conditional_format_rule(sheet_id: int, *, index: int, rule: ConditionalFormatRule) -> dict`
 Replace an existing conditional format rule by index.
 
 ```python
@@ -284,7 +327,7 @@ Delete a sheet.
 req = ApiRequest.delete_sheet(sheet_id=3)
 ```
 
-### `add_sheet(*, sheet_id: int = None, title: str = None, index: int = None, hidden: bool = None, row_count: int = None, column_count: int = None, frozen_row_count: int = None, frozen_column_count: int = None, hide_grid_lines: bool = None) -> dict`
+### `add_sheet(sheet_id: int = None, *, title: str = None, index: int = None, hidden: bool = None, row_count: int = None, column_count: int = None, frozen_row_count: int = None, frozen_column_count: int = None, hide_grid_lines: bool = None) -> dict`
 Create a new sheet with optional properties.
 
 ```python
@@ -306,7 +349,7 @@ Merge cells in a range.
 req = ApiRequest.merge_cells(sheet_id=0, range_='A1:C1')
 ```
 
-### `unmerge_cells(sheet_id: int, range_: str = None, start_row: int = None, end_row: int = None, start_column: int | str = None, end_column: int | str = None) -> dict`
+### `unmerge_cells(sheet_id: int, *, range_: str = None, start_row: int = None, end_row: int = None, start_column: int | str = None, end_column: int | str = None) -> dict`
 Unmerge cells in a range (or by explicit indexes).
 
 ```python
@@ -323,14 +366,14 @@ req = ApiRequest.freeze(sheet_id=0, rows=1, columns=1)
 ---
 ### Rows and columns
 
-### `insert_rows(sheet_id: int, start_index: int, end_index: int = None, inherit_from_before: bool = True) -> dict`
+### `insert_rows(sheet_id: int, start_index: int, end_index: int = None, *, inherit_from_before: bool = True) -> dict`
 Insert one or more rows (Indexes are zero-based and inclusive [start_index, end_index]).
 
 ```python
 req = ApiRequest.insert_rows(sheet_id=0, start_index=5, end_index=9)
 ```
 
-### `insert_columns(sheet_id: int, start_index: int, end_index: int = None, inherit_from_before: bool = True) -> dict`
+### `insert_columns(sheet_id: int, start_index: int, end_index: int = None, *, inherit_from_before: bool = True) -> dict`
 Insert columns (Indexes are zero-based and inclusive [start_index, end_index]).
 
 ```python
@@ -489,4 +532,4 @@ GoogleSheets.update_spreadsheet(spreadsheet_id, requests, service)
 If you have any questions, encounter issues, or want to suggest improvements:
 
 - **Bug Reports & Feature Requests:** Please use [GitHub Issues](https://github.com/Timofey28/python-google-sheets/issues) to report bugs or submit ideas.
-- **Questions:** For general inquiries or help with integration, feel free to reach out via email at [timegorr@gmail.com](mailto:timegorr@gmail.com).
+- **Questions:** For general inquiries or help with integration, feel free to reach out via email at [timegorr@gmail.com](mailto:timegorr@gmail.com).