arcade-google-sheets 2.0.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

arcade_google_sheets/enums.py

@@ -23,3 +23,8 @@ class NumberFormatType(str, Enum):
     NUMBER = "NUMBER"
     PERCENT = "PERCENT"
     CURRENCY = "CURRENCY"
+
+
+class SheetIdentifierType(str, Enum):
+    POSITION = "position"
+    ID_OR_NAME = "id_or_name"

arcade_google_sheets/tools/read.py

@@ -6,7 +6,9 @@ from arcade_tdk.auth import Google
 from arcade_google_sheets.decorators import with_filepicker_fallback
 from arcade_google_sheets.utils import (
     build_sheets_service,
-    parse_get_spreadsheet_response,
+    get_spreadsheet_with_pagination,
+    process_get_spreadsheet_params,
+    raise_for_large_payload,
 )
 
 
@@ -20,23 +22,63 @@ from arcade_google_sheets.utils import (
 async def get_spreadsheet(
     context: ToolContext,
     spreadsheet_id: Annotated[str, "The id of the spreadsheet to get"],
+    sheet_position: Annotated[
+        int | None,
+        "The position/tab of the sheet in the spreadsheet to get. "
+        "A value of 1 represents the first (leftmost/Sheet1) sheet . "
+        "Defaults to 1.",
+    ] = 1,
+    sheet_id_or_name: Annotated[
+        str | None,
+        "The id or name of the sheet to get. "
+        "Defaults to None, which means sheet_position will be used instead.",
+    ] = None,
+    start_row: Annotated[int, "Starting row number (1-indexed, defaults to 1)"] = 1,
+    start_col: Annotated[
+        str, "Starting column letter(s) or 1-based column number (defaults to 'A')"
+    ] = "A",
+    max_rows: Annotated[
+        int,
+        "Maximum number of rows to fetch for each sheet in the spreadsheet. "
+        "Must be between 1 and 1000. Defaults to 1000.",
+    ] = 1000,
+    max_cols: Annotated[
+        int,
+        "Maximum number of columns to fetch for each sheet in the spreadsheet. "
+        "Must be between 1 and 100. Defaults to 100.",
+    ] = 100,
 ) -> Annotated[
     dict,
-    "The spreadsheet properties and data for all sheets in the spreadsheet",
+    "The spreadsheet properties and data for the specified sheet in the spreadsheet",
 ]:
+    """Gets the specified range of cells from a single sheet in the spreadsheet.
+
+    sheet_id_or_name takes precedence over sheet_position. If a sheet is not mentioned,
+    then always assume the default sheet_position is sufficient.
     """
-    Get the user entered values and formatted values for all cells in all sheets in the spreadsheet
-    along with the spreadsheet's properties
-    """
+    sheet_identifier, sheet_identifier_type, start_row, start_col, max_rows, max_cols = (
+        process_get_spreadsheet_params(
+            sheet_position,
+            sheet_id_or_name,
+            start_row,
+            start_col,
+            max_rows,
+            max_cols,
+        )
+    )
+
     service = build_sheets_service(context.get_auth_token_or_empty())
 
-    response = (
-        service.spreadsheets()
-        .get(
-            spreadsheetId=spreadsheet_id,
-            includeGridData=True,
-            fields="spreadsheetId,spreadsheetUrl,properties/title,sheets/properties,sheets/data/rowData/values/userEnteredValue,sheets/data/rowData/values/formattedValue,sheets/data/rowData/values/effectiveValue",
-        )
-        .execute()
+    data = get_spreadsheet_with_pagination(
+        service,
+        spreadsheet_id,
+        sheet_identifier,
+        sheet_identifier_type,
+        start_row,
+        start_col,
+        max_rows,
+        max_cols,
     )
-    return parse_get_spreadsheet_response(response)
+
+    raise_for_large_payload(data)
+    return data

arcade_google_sheets/utils.py

@@ -1,4 +1,5 @@
 import logging
+import string
 from typing import Any
 
 from arcade_tdk.errors import RetryableToolError, ToolExecutionError
@@ -9,7 +10,7 @@ from arcade_google_sheets.constants import (
     DEFAULT_SHEET_COLUMN_COUNT,
     DEFAULT_SHEET_ROW_COUNT,
 )
-from arcade_google_sheets.enums import NumberFormatType
+from arcade_google_sheets.enums import NumberFormatType, SheetIdentifierType
 from arcade_google_sheets.models import (
     CellData,
     CellExtendedValue,
@@ -21,6 +22,7 @@ from arcade_google_sheets.models import (
     Sheet,
     SheetDataInput,
     SheetProperties,
+    Spreadsheet,
 )
 from arcade_google_sheets.types import CellValue
 
@@ -546,3 +548,238 @@ def parse_write_to_cell_response(response: dict) -> dict:
         "updatedCell": response["updatedData"]["range"].split("!")[1],
         "value": response["updatedData"]["values"][0][0],
     }
+
+
+def calculate_a1_sheet_range(
+    sheet_name: str,
+    sheet_row_count: int,
+    sheet_col_count: int,
+    start_row: int,
+    start_col: str,
+    max_rows: int,
+    max_cols: int,
+) -> str | None:
+    """Calculate a single range for a sheet based on start position and limits.
+
+    Args:
+        sheet_name (str): The name of the sheet.
+        sheet_row_count (int): The number of rows in the sheet.
+        sheet_col_count (int): The number of columns in the sheet.
+        start_row (int): The row from which to start fetching data.
+        start_col (str): The column letter(s) from which to start fetching data.
+        max_rows (int): The maximum number of rows to fetch.
+        max_cols (int): The maximum number of columns to fetch.
+
+    Returns:
+        str | None: The A1 range for the sheet, or None if there is no data to fetch.
+    """
+    start_col_index = col_to_index(start_col)
+
+    effective_max_rows = min(sheet_row_count, max_rows or sheet_row_count)
+    effective_max_cols = min(sheet_col_count, max_cols or sheet_col_count)
+
+    end_row = min(start_row + effective_max_rows - 1, sheet_row_count)
+    end_col_index = min(start_col_index + effective_max_cols - 1, sheet_col_count - 1)
+
+    # Only create a range if there's actually data to fetch
+    if start_row <= end_row and start_col_index <= end_col_index:
+        range_start = f"{index_to_col(start_col_index)}{start_row}"
+        range_end = f"{index_to_col(end_col_index)}{end_row}"
+        return f"'{sheet_name}'!{range_start}:{range_end}"
+
+    return None
+
+
+def find_sheet_by_identifier(
+    sheets: list[Sheet], sheet_identifier: str, sheet_identifier_type: SheetIdentifierType
+) -> Sheet | None:
+    """
+    Find a sheet by identifier (name, sheet ID, or 1-based position index).
+
+    Args:
+        sheets (list): List of Sheet objects from the spreadsheet.
+        sheet_identifier (str): The identifier of the sheet to get.
+        sheet_identifier_type (SheetIdentifierType): The type of the identifier.
+
+    Returns:
+        Sheet | None: The matching sheet, or None if not found.
+    """
+    if sheet_identifier_type == SheetIdentifierType.POSITION:
+        index = int(sheet_identifier) - 1
+        if 0 <= index < len(sheets):
+            return sheets[index]
+
+    if sheet_identifier_type == SheetIdentifierType.ID_OR_NAME:
+        for sheet in sheets:
+            sheet_title = sheet.properties.title
+            sheet_id = sheet.properties.sheetId
+            if (
+                sheet_title.casefold() == sheet_identifier.casefold()
+                or str(sheet_id).casefold() == sheet_identifier.casefold()
+            ):
+                return sheet
+
+    return None
+
+
+def get_spreadsheet_with_pagination(  # type: ignore[no-any-unimported]
+    service: Resource,
+    spreadsheet_id: str,
+    sheet_identifier: str,
+    sheet_identifier_type: SheetIdentifierType,
+    start_row: int,
+    start_col: str,
+    max_rows: int,
+    max_cols: int,
+) -> dict:
+    """
+    Get spreadsheet data with pagination support for large spreadsheets.
+
+    Args:
+        service (Resource): The Google Sheets service.
+        spreadsheet_id (str): The ID of the spreadsheet provided to the tool.
+        sheet_position (int | None): The position/tab of the sheet to get.
+        sheet_id_or_name (str | None): The id or name of the sheet to get.
+        start_row (int): The row from which to start fetching data.
+        start_col (str): The column letter(s) from which to start fetching data.
+        max_rows (int): The maximum number of rows to fetch.
+        max_cols (int): The maximum number of columns to fetch.
+
+    Returns:
+        dict: The spreadsheet data for the specified sheet in the spreadsheet.
+
+    """
+
+    # First, only get the spreadsheet metadata to collect the sheet names and dimensions
+    metadata_response = (
+        service.spreadsheets()
+        .get(
+            spreadsheetId=spreadsheet_id,
+            includeGridData=False,
+            fields="spreadsheetId,spreadsheetUrl,properties/title,sheets/properties",
+        )
+        .execute()
+    )
+    spreadsheet = Spreadsheet.model_validate(metadata_response)
+
+    target_sheet = find_sheet_by_identifier(
+        spreadsheet.sheets, sheet_identifier, sheet_identifier_type
+    )
+    if not target_sheet:
+        raise ToolExecutionError(
+            message=f"Sheet with identifier '{sheet_identifier}' not found",
+            developer_message=(
+                "Sheet(s) in the spreadsheet: "
+                + ", ".join([sheet.model_dump_json() for sheet in spreadsheet.sheets])
+            ),
+        )
+
+    a1_ranges = []
+    sheet_name = target_sheet.properties.title
+    grid_props = target_sheet.properties.gridProperties
+    if grid_props:
+        sheet_row_count = grid_props.rowCount
+        sheet_col_count = grid_props.columnCount
+
+        curr_range = calculate_a1_sheet_range(
+            sheet_name,
+            sheet_row_count,
+            sheet_col_count,
+            start_row,
+            start_col,
+            max_rows,
+            max_cols,
+        )
+        if curr_range:
+            a1_ranges.append(curr_range)
+
+    # Next, get the data for the ranges
+    if a1_ranges:
+        response = (
+            service.spreadsheets()
+            .get(
+                spreadsheetId=spreadsheet_id,
+                includeGridData=True,
+                ranges=a1_ranges,
+                fields="spreadsheetId,spreadsheetUrl,properties/title,sheets/properties,sheets/data/rowData/values/userEnteredValue,sheets/data/rowData/values/formattedValue,sheets/data/rowData/values/effectiveValue",
+            )
+            .execute()
+        )
+    else:
+        response = metadata_response
+
+    return parse_get_spreadsheet_response(response)
+
+
+def process_get_spreadsheet_params(
+    sheet_position: int | None,
+    sheet_id_or_name: str | None,
+    start_row: int,
+    start_col: str,
+    max_rows: int,
+    max_cols: int,
+) -> tuple[str, SheetIdentifierType, int, str, int, int]:
+    """Process and validate the input parameters for the get_spreadsheet tool.
+
+    Args:
+        sheet_position (int | None): The position/tab of the sheet to get.
+        sheet_id_or_name (str | None): The id or name of the sheet to get.
+        start_row (int): Processed to be within the range [1, 1000]
+        start_col (str): Processed to be alphabetic column representation. e.g., A, Z, QED
+        max_rows (int): Processed to be within the range [1, 1000]
+        max_cols (int): Processed to be within the range [1, 26]
+
+    Returns:
+        tuple[str, str, int, str, int, int]: The processed parameters.
+
+    Raises:
+        ToolExecutionError:
+            If the start_col is not one of alphabetic or numeric
+    """
+    if sheet_id_or_name:
+        sheet_identifier = sheet_id_or_name
+        sheet_identifier_type = SheetIdentifierType.ID_OR_NAME
+    elif sheet_position:
+        sheet_identifier = str(sheet_position)
+        sheet_identifier_type = SheetIdentifierType.POSITION
+    else:
+        raise RetryableToolError("Either sheet_position or sheet_id_or_name must be provided")
+
+    processed_start_row = max(1, start_row)
+    processed_max_rows = max(1, min(max_rows, 1000))
+    processed_max_cols = max(1, min(max_cols, 26))
+    if not all(c in string.ascii_letters for c in start_col):
+        if not start_col.isdigit():
+            raise ToolExecutionError("Input 'start_col' must be alphabetic (A-Z) or numeric")
+        processed_start_col = index_to_col(int(start_col) - 1)
+    else:
+        processed_start_col = start_col.upper()
+
+    return (
+        sheet_identifier,
+        sheet_identifier_type,
+        processed_start_row,
+        processed_start_col,
+        processed_max_rows,
+        processed_max_cols,
+    )
+
+
+def raise_for_large_payload(data: dict) -> None:
+    """Enforce a 10MB limit on the data size.
+
+    Args:
+        data (dict): The data to enforce the size limit on.
+
+    Raises:
+        ToolExecutionError:
+            If the data size exceeds 10MB
+    """
+    num_bytes = len(str(data).encode("utf-8"))
+
+    if num_bytes >= (10 * 1024 * 1024):
+        raise ToolExecutionError(
+            message="Spreadsheet size exceeds 10MB limit. "
+            "Please reduce the number of rows and columns you are requesting and try again.",
+            developer_message=f"Data size: {num_bytes / 1024 / 1024:.4f}MB",
+        )

{arcade_google_sheets-2.0.0.dist-info → arcade_google_sheets-3.0.0.dist-info}/METADATA

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: arcade_google_sheets
-Version: 2.0.0
+Version: 3.0.0
 Summary: Arcade.dev LLM tools for Google Sheets
 Author-email: Arcade <dev@arcade.dev>
+License: Proprietary - Arcade Software License Agreement v1.0
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: arcade-tdk<3.0.0,>=2.0.0

{arcade_google_sheets-2.0.0.dist-info → arcade_google_sheets-3.0.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
 arcade_google_sheets/__init__.py,sha256=FB9h_cws_gu3UJp32GWlqvBQyAOb77JfAJNSSBqz-Jk,177
 arcade_google_sheets/constants.py,sha256=4tQOrQ1YagSklJSSw5Eq21XCcFCJdO7lso5SqWIdrPI,63
 arcade_google_sheets/decorators.py,sha256=QMqfvSXaFBoxYJrz69EGeMdAxF0V7JPReVXfp73Nf3Y,753
-arcade_google_sheets/enums.py,sha256=_gZxlgciXK-_Sg-62lTv6JFpmxWV7obH9VWE-s1zjug,942
+arcade_google_sheets/enums.py,sha256=xaBm-P6h63q2xrnvd8qqzS1gW5tAkUqbQcw0KL6q7Iw,1038
 arcade_google_sheets/file_picker.py,sha256=kGfUVfH5QVlIW1sL-_gAwPokt7TwVEcPk3Vnk53GKUE,2005
 arcade_google_sheets/models.py,sha256=VQy3L_Acch1MEM2RkTe-Qp_AEU-cb0JciLJ-0Ci87aw,7613
 arcade_google_sheets/types.py,sha256=R-rCRcyFqDZx3jgl_kWeCliqC8fHuZ8ub_LQ2KoU2AE,37
-arcade_google_sheets/utils.py,sha256=CqQJPwXP_QoMJG18LrltG4sblTcFe4Mu5psY4U2nsvc,18412
+arcade_google_sheets/utils.py,sha256=0SCjW92wedFilovwc-tERAtfdBYGZ1OZlil_XUZEiVc,26803
 arcade_google_sheets/tools/__init__.py,sha256=TPlitJn1VJffCXFkpOtoYXNsaEFkpujQzsYvuikCe4U,209
-arcade_google_sheets/tools/read.py,sha256=Fh9nh8ISHBgf6akixVYQIt3TihrmW7P9WW8yeb-njhI,1416
+arcade_google_sheets/tools/read.py,sha256=tdDrXwt1PCytQy1oBlU4HKZ7OjiTpIU43og5VkFAMqs,2704
 arcade_google_sheets/tools/write.py,sha256=gmbErdBbBKUEPxGjCWDpMJ9pMWRAvoEjApIXFQax6Z4,3598
-arcade_google_sheets-2.0.0.dist-info/METADATA,sha256=MDLh2hWNrBrwRExy66wGsJpPv2QiMEZ_o_voWe5EiIs,1061
-arcade_google_sheets-2.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-arcade_google_sheets-2.0.0.dist-info/licenses/LICENSE,sha256=XjKuCk1TG4bFrY-8x79oGMmNqrS4TP7c_Zv4-TrMWQY,1063
-arcade_google_sheets-2.0.0.dist-info/RECORD,,
+arcade_google_sheets-3.0.0.dist-info/METADATA,sha256=gZhKVztmJe2asXyH_cTcjcQDcACl-2r_AaglFBLBqOs,1123
+arcade_google_sheets-3.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+arcade_google_sheets-3.0.0.dist-info/licenses/LICENSE,sha256=ixeE7aL9b2B-_ZYHTY1vQcJB4NufKeo-LWwKNObGDN0,1960
+arcade_google_sheets-3.0.0.dist-info/RECORD,,

arcade_google_sheets-3.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,35 @@
+# The Arcade Software License Agreement
+
+- Version 1.0
+- Effective Date: July 24, 2025
+
+---
+
+This software and associated documentation (collectively, the “Software”) are the intellectual property of Arcade Technologies, Inc. (“Arcade”). All rights are reserved.
+
+1. License Grant
+
+No license or other rights are granted to any party under this Agreement, whether by implication, estoppel, or otherwise. This Software is proprietary and confidential. Use, reproduction, modification, distribution, display, or creation of derivative works based on the Software is strictly prohibited without the prior written consent of Arcade.
+
+2. Commercial Use Only
+
+Any use of this Software requires a commercial license agreement with Arcade. You may not use any part of the Software for any purpose—including but not limited to evaluation, testing, or internal use—without first obtaining explicit written permission and entering into a commercial licensing arrangement.
+
+To inquire about licensing terms, contact Arcade at:
+🔗 www.arcade.dev
+
+3. No Open Source Rights
+
+This Software is not licensed under an open-source license. No part of it may be incorporated into open-source or publicly available projects under any open-source terms or licenses.
+
+4. Ownership
+
+Arcade retains all right, title, and interest in and to the Software, including all intellectual property rights therein. No ownership or license rights are transferred under this Agreement.
+
+5. Disclaimer of Warranty
+
+The Software is provided “as is” without warranty of any kind. Arcade disclaims all warranties, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, and noninfringement.
+
+6. Limitation of Liability
+
+In no event shall Arcade be liable for any damages arising out of or in connection with the use or performance of the Software, whether in an action of contract, tort (including negligence), or otherwise.

arcade_google_sheets-2.0.0.dist-info/licenses/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Arcade
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.