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

arcade_google_sheets/converters.py

@@ -0,0 +1,108 @@
+from arcade_google_sheets.enums import Dimension
+from arcade_google_sheets.models import CellValue, SheetDataInput, ValueRange
+from arcade_google_sheets.utils import (
+    col_to_index,
+    group_contiguous_rows,
+    index_to_col,
+)
+
+
+class SheetDataInputToValueRangesConverter:
+    def __init__(self, sheet_name: str, sheet_data: SheetDataInput):
+        self.sheet_name = sheet_name
+        self.sheet_data = sheet_data
+
+    def convert(self) -> list[ValueRange]:
+        """
+        Convert a SheetDataInput to a list of ValueRanges that are row-oriented.
+
+        Args:
+            sheet_name (str): The name of the sheet to which the data belongs.
+            sheet_data (SheetDataInput): The data to convert into ranges.
+
+        Returns:
+            list[ValueRange]: The converted ValueRanges.
+        """
+        if not self.sheet_data.data:
+            return []
+
+        row_ranges = self._build_row_oriented_ranges()
+
+        return row_ranges
+
+    def _to_float_if_int(self, value: CellValue) -> bool | str | float:
+        """
+        The spreadsheets.values.batchUpdate API does not support int values.
+        So we convert ints to floats.
+
+        Args:
+            value (Any): The value to possibly convert.
+
+        Returns:
+            bool | str | float: The converted value.
+        """
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, int):
+            return float(value)
+        return value
+
+    def _get_cell_value(self, row_num: int, col_idx: int) -> bool | str | float:
+        """
+        Safely fetch a cell value.
+
+        Args:
+            row_num (int): The row number of the cell.
+            col_idx (int): The column index of the cell.
+
+        Returns:
+            bool | str | float: The value of the cell.
+        """
+        col_letter = index_to_col(col_idx)
+        return self._to_float_if_int(self.sheet_data.data[row_num][col_letter])
+
+    def _build_row_oriented_ranges(self) -> list[ValueRange]:
+        """
+        Build row-oriented ValueRanges for the object's sheet data.
+
+        Returns:
+            list[ValueRange]: The row-oriented ValueRanges.
+        """
+        # Map (start_col_idx, end_col_idx) -> { row_num: [values across columns] }
+        segment_to_rows_values: dict[tuple[int, int], dict[int, list[bool | str | float]]] = {}
+
+        for row_num in sorted(self.sheet_data.data):
+            cols_dict = self.sheet_data.data[row_num]
+            col_indices = sorted(col_to_index(col) for col in cols_dict)
+            if not col_indices:
+                continue
+            contiguous_groups = group_contiguous_rows(col_indices)
+            for group in contiguous_groups:
+                start_idx = group[0]
+                end_idx = group[-1]
+                row_values = [self._get_cell_value(row_num, ci) for ci in group]
+                key = (start_idx, end_idx)
+                if key not in segment_to_rows_values:
+                    segment_to_rows_values[key] = {}
+                segment_to_rows_values[key][row_num] = row_values
+
+        row_oriented_ranges: list[ValueRange] = []
+        for (start_idx, end_idx), rows_map in segment_to_rows_values.items():
+            sorted_rows = sorted(rows_map.keys())
+            row_groups = group_contiguous_rows(sorted_rows)
+            for rg in row_groups:
+                start_row = rg[0]
+                end_row = rg[-1]
+                start_col = index_to_col(start_idx)
+                end_col = index_to_col(end_idx)
+                a1_range = f"'{self.sheet_name}'!{start_col}{start_row}:{end_col}{end_row}"
+                values = [rows_map[r] for r in rg]
+                row_oriented_ranges.append(
+                    ValueRange(
+                        range=a1_range,
+                        majorDimension=Dimension.ROWS,
+                        values=values,
+                    )
+                )
+
+        return row_oriented_ranges

arcade_google_sheets/enums.py

@@ -28,3 +28,122 @@ class NumberFormatType(str, Enum):
 class SheetIdentifierType(str, Enum):
     POSITION = "position"
     ID_OR_NAME = "id_or_name"
+
+
+class Dimension(str, Enum):
+    ROWS = "ROWS"  # Operates on the rows of a sheet.
+    COLUMNS = "COLUMNS"  # Operates on the columns of a sheet.
+
+
+# ------------------------------------------------------------
+# Drive API enums
+# ------------------------------------------------------------
+
+
+class OrderBy(str, Enum):
+    """
+    Sort keys for ordering files in Google Drive.
+    Each key has both ascending and descending options.
+    """
+
+    CREATED_TIME = (
+        # When the file was created (ascending)
+        "createdTime"
+    )
+    CREATED_TIME_DESC = (
+        # When the file was created (descending)
+        "createdTime desc"
+    )
+    FOLDER = (
+        # The folder ID, sorted using alphabetical ordering (ascending)
+        "folder"
+    )
+    FOLDER_DESC = (
+        # The folder ID, sorted using alphabetical ordering (descending)
+        "folder desc"
+    )
+    MODIFIED_BY_ME_TIME = (
+        # The last time the file was modified by the user (ascending)
+        "modifiedByMeTime"
+    )
+    MODIFIED_BY_ME_TIME_DESC = (
+        # The last time the file was modified by the user (descending)
+        "modifiedByMeTime desc"
+    )
+    MODIFIED_TIME = (
+        # The last time the file was modified by anyone (ascending)
+        "modifiedTime"
+    )
+    MODIFIED_TIME_DESC = (
+        # The last time the file was modified by anyone (descending)
+        "modifiedTime desc"
+    )
+    NAME = (
+        # The name of the file, sorted using alphabetical ordering (e.g., 1, 12, 2, 22) (ascending)
+        "name"
+    )
+    NAME_DESC = (
+        # The name of the file, sorted using alphabetical ordering (e.g., 1, 12, 2, 22) (descending)
+        "name desc"
+    )
+    NAME_NATURAL = (
+        # The name of the file, sorted using natural sort ordering (e.g., 1, 2, 12, 22) (ascending)
+        "name_natural"
+    )
+    NAME_NATURAL_DESC = (
+        # The name of the file, sorted using natural sort ordering (e.g., 1, 2, 12, 22) (descending)
+        "name_natural desc"
+    )
+    QUOTA_BYTES_USED = (
+        # The number of storage quota bytes used by the file (ascending)
+        "quotaBytesUsed"
+    )
+    QUOTA_BYTES_USED_DESC = (
+        # The number of storage quota bytes used by the file (descending)
+        "quotaBytesUsed desc"
+    )
+    RECENCY = (
+        # The most recent timestamp from the file's date-time fields (ascending)
+        "recency"
+    )
+    RECENCY_DESC = (
+        # The most recent timestamp from the file's date-time fields (descending)
+        "recency desc"
+    )
+    SHARED_WITH_ME_TIME = (
+        # When the file was shared with the user, if applicable (ascending)
+        "sharedWithMeTime"
+    )
+    SHARED_WITH_ME_TIME_DESC = (
+        # When the file was shared with the user, if applicable (descending)
+        "sharedWithMeTime desc"
+    )
+    STARRED = (
+        # Whether the user has starred the file (ascending)
+        "starred"
+    )
+    STARRED_DESC = (
+        # Whether the user has starred the file (descending)
+        "starred desc"
+    )
+    VIEWED_BY_ME_TIME = (
+        # The last time the file was viewed by the user (ascending)
+        "viewedByMeTime"
+    )
+    VIEWED_BY_ME_TIME_DESC = (
+        # The last time the file was viewed by the user (descending)
+        "viewedByMeTime desc"
+    )
+
+
+class Corpora(str, Enum):
+    """
+    Bodies of items (spreadsheets) to which the query applies.
+    Prefer 'user' or 'drive' to 'allDrives' for efficiency.
+    By default, corpora is set to 'user'.
+    """
+
+    USER = "user"
+    DOMAIN = "domain"
+    DRIVE = "drive"
+    ALL_DRIVES = "allDrives"

arcade_google_sheets/models.py

@@ -3,7 +3,7 @@ from typing import Optional
 
 from pydantic import BaseModel, field_validator, model_validator
 
-from arcade_google_sheets.enums import CellErrorType, NumberFormatType
+from arcade_google_sheets.enums import CellErrorType, Dimension, NumberFormatType
 from arcade_google_sheets.types import CellValue
 
 
@@ -137,6 +137,41 @@ class Spreadsheet(BaseModel):
 
     properties: SpreadsheetProperties
     sheets: list[Sheet]
+    spreadsheetId: str | None = None
+    spreadsheetUrl: str | None = None
+
+
+class ValueRange(BaseModel):
+    """A range of cells in a spreadsheet
+
+    An implementation of https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values#ValueRange
+
+    Example 1:
+    {
+        "range": "Sheet1!A1:B2",
+        "majorDimension": "ROWS",
+        "values": [
+            ["1", "2"],
+            ["3", "4"]
+        ]
+    }
+    Example 2:
+    {
+        "range": "Sheet1!A1:A4",
+        "majorDimension": "COLUMNS",
+        "values": [
+            ["Item", "Wheel", "Door", "Engine"]
+        ]
+    }
+    """
+
+    range: str  # A1 notation
+    majorDimension: Dimension
+    # values is a 2D array. The outer array represents all the data and each inner
+    # array represents a major dimension. Each item in the inner array corresponds
+    # with one cell.
+    # Note: Google API docs don't mention support for int, so CellValue is not used
+    values: list[list[bool | str | float]]
 
 
 class SheetDataInput(BaseModel):

arcade_google_sheets/templates.py

@@ -0,0 +1,8 @@
+optional_file_picker_instructions_template = (
+    "Ensure the user knows that they have the option to select and grant access permissions to "
+    "additional files and folders via the Google Drive File Picker. "
+    "The user can pick additional files and folders via the following link: {url}"
+)
+
+spreadsheet_url_template = "https://docs.google.com/spreadsheets/d/{spreadsheet_id}/edit"
+sheet_url_template = "https://docs.google.com/spreadsheets/d/{spreadsheet_id}/edit#gid={sheet_id}"

arcade_google_sheets/tools/__init__.py

@@ -1,4 +1,18 @@
-from arcade_google_sheets.tools.read import get_spreadsheet
-from arcade_google_sheets.tools.write import create_spreadsheet, write_to_cell
+from arcade_google_sheets.tools.read import get_spreadsheet, get_spreadsheet_metadata
+from arcade_google_sheets.tools.search import search_spreadsheets
+from arcade_google_sheets.tools.write import (
+    add_note_to_cell,
+    create_spreadsheet,
+    update_cells,
+    write_to_cell,
+)
 
-__all__ = ["create_spreadsheet", "get_spreadsheet", "write_to_cell"]
+__all__ = [
+    "create_spreadsheet",
+    "get_spreadsheet",
+    "get_spreadsheet_metadata",
+    "search_spreadsheets",
+    "update_cells",
+    "add_note_to_cell",
+    "write_to_cell",
+]

arcade_google_sheets/tools/read.py

@@ -4,8 +4,10 @@ from arcade_tdk import ToolContext, ToolMetadataKey, tool
 from arcade_tdk.auth import Google
 
 from arcade_google_sheets.decorators import with_filepicker_fallback
+from arcade_google_sheets.templates import sheet_url_template
 from arcade_google_sheets.utils import (
     build_sheets_service,
+    get_spreadsheet_metadata_helper,
     get_spreadsheet_with_pagination,
     process_get_spreadsheet_params,
     raise_for_large_payload,
@@ -82,3 +84,40 @@ async def get_spreadsheet(
 
     raise_for_large_payload(data)
     return data
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/drive.file"],
+    ),
+    requires_metadata=[ToolMetadataKey.CLIENT_ID, ToolMetadataKey.COORDINATOR_URL],
+)
+@with_filepicker_fallback
+async def get_spreadsheet_metadata(
+    context: ToolContext,
+    spreadsheet_id: Annotated[str, "The id of the spreadsheet to get metadata for"],
+) -> Annotated[dict, "The spreadsheet metadata for the specified spreadsheet"]:
+    """Gets the metadata for a spreadsheet including the metadata for the sheets in the spreadsheet.
+
+    Use this tool to get the name, position, ID, and URL of all sheets in a spreadsheet as well as
+    the number of rows and columns in each sheet.
+
+    Does not return the content/data of the sheets in the spreadsheet - only the metadata.
+    Excludes spreadsheets that are in the trash.
+    """
+    service = build_sheets_service(context.get_auth_token_or_empty())
+
+    metadata = get_spreadsheet_metadata_helper(service, spreadsheet_id)
+    metadata_dict = metadata.model_dump(exclude_none=True)
+    for sheet in metadata_dict.get("sheets", []):
+        sheet["sheet_url"] = sheet_url_template.format(
+            spreadsheet_id=spreadsheet_id,
+            sheet_id=sheet["properties"]["sheetId"],
+        )
+
+    return {
+        "spreadsheet_title": metadata_dict["properties"]["title"],
+        "spreadsheet_id": metadata_dict["spreadsheetId"],
+        "spreadsheet_url": metadata_dict["spreadsheetUrl"],
+        "sheets": metadata_dict["sheets"],
+    }

arcade_google_sheets/tools/search.py

@@ -0,0 +1,141 @@
+from typing import Annotated, Any
+
+from arcade_tdk import ToolContext, ToolMetadataKey, tool
+from arcade_tdk.auth import Google
+
+from arcade_google_sheets.enums import OrderBy
+from arcade_google_sheets.file_picker import generate_google_file_picker_url
+from arcade_google_sheets.templates import (
+    optional_file_picker_instructions_template,
+    spreadsheet_url_template,
+)
+from arcade_google_sheets.utils import (
+    build_drive_service,
+    build_files_list_params,
+    remove_none_values,
+)
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/drive.file"],
+    ),
+    requires_metadata=[ToolMetadataKey.CLIENT_ID, ToolMetadataKey.COORDINATOR_URL],
+)
+async def search_spreadsheets(
+    context: ToolContext,
+    spreadsheet_contains: Annotated[
+        list[str] | None,
+        "Keywords or phrases that must be in the spreadsheet title. Provide a list of "
+        "keywords or phrases if needed.",
+    ] = None,
+    spreadsheet_not_contains: Annotated[
+        list[str] | None,
+        "Keywords or phrases that must NOT be in the spreadsheet title. Provide a list of "
+        "keywords or phrases if needed.",
+    ] = None,
+    search_only_in_shared_drive_id: Annotated[
+        str | None,
+        "The ID of the shared drive to restrict the search to. If provided, the search will only "
+        "return spreadsheets from this drive. Defaults to None, which searches across all drives.",
+    ] = None,
+    include_shared_drives: Annotated[
+        bool,
+        "Whether to include spreadsheets from shared drives. Defaults to False (searches only in "
+        "the user's 'My Drive').",
+    ] = False,
+    include_organization_domain_spreadsheets: Annotated[
+        bool,
+        "Whether to include spreadsheets from the organization's domain. "
+        "This is applicable to admin users who have permissions to view "
+        "organization-wide spreadsheets in a Google Workspace account. "
+        "Defaults to False.",
+    ] = False,
+    order_by: Annotated[
+        list[OrderBy] | None,
+        "Sort order. Defaults to listing the most recently modified spreadsheets first. "
+        "If spreadsheet_contains or spreadsheet_not_contains is provided, "
+        "then the order_by will be ignored.",
+    ] = None,
+    limit: Annotated[
+        int, "The maximum number of spreadsheets to list. Defaults to 10. Max is 50"
+    ] = 10,
+    pagination_token: Annotated[
+        str | None, "The pagination token to continue a previous request"
+    ] = None,
+) -> Annotated[
+    dict,
+    "A dictionary containing the title, ID, and URL for each matching spreadsheet. "
+    "Also contains a pagination token if there are more spreadsheets to list.",
+]:
+    """
+    Searches for spreadsheets in the user's Google Drive based on the titles and content and
+    returns the title, ID, and URL for each matching spreadsheet.
+
+    Does not return the content/data of the sheets in the spreadsheets - only the metadata.
+    Excludes spreadsheets that are in the trash.
+    """
+    if spreadsheet_contains or spreadsheet_not_contains:
+        # Google drive API does not support other order_by values for
+        # queries with fullText search (which is used when spreadsheet_contains
+        # or spreadsheet_not_contains is provided).
+        order_by = None
+    if order_by is None:
+        order_by = [OrderBy.MODIFIED_TIME_DESC]
+    elif isinstance(order_by, OrderBy):
+        order_by = [order_by]
+
+    limit = max(1, min(50, limit))
+    page_size = min(10, limit)
+    spreadsheets: list[dict[str, Any]] = []
+
+    drive_service = build_drive_service(context.get_auth_token_or_empty())
+
+    params = build_files_list_params(
+        mime_type="application/vnd.google-apps.spreadsheet",
+        page_size=page_size,
+        order_by=order_by,
+        pagination_token=pagination_token,
+        include_shared_drives=include_shared_drives,
+        search_only_in_shared_drive_id=search_only_in_shared_drive_id,
+        include_organization_domain_spreadsheets=include_organization_domain_spreadsheets,
+        spreadsheet_contains=spreadsheet_contains,
+        spreadsheet_not_contains=spreadsheet_not_contains,
+    )
+
+    while len(spreadsheets) < limit:
+        if pagination_token:
+            params["pageToken"] = pagination_token
+        else:
+            params.pop("pageToken", None)
+
+        results = drive_service.files().list(**params).execute()
+        batch = results.get("files", [])
+        spreadsheets.extend(batch[: limit - len(spreadsheets)])
+
+        pagination_token = results.get("nextPageToken")
+        if not pagination_token or len(batch) < page_size:
+            break
+
+    # Add the spreadsheet URL to each spreadsheet
+    for spreadsheet in spreadsheets:
+        spreadsheet["url"] = spreadsheet_url_template.format(spreadsheet_id=spreadsheet["id"])
+
+    file_picker_response = generate_google_file_picker_url(
+        context,
+    )
+
+    tool_response = {
+        "pagination_token": pagination_token,
+        "spreadsheets_count": len(spreadsheets),
+        "spreadsheets": spreadsheets,
+        "file_picker": {
+            "url": file_picker_response["url"],
+            "llm_instructions": optional_file_picker_instructions_template.format(
+                url=file_picker_response["url"]
+            ),
+        },
+    }
+    tool_response = remove_none_values(tool_response)
+
+    return tool_response

arcade_google_sheets/tools/write.py

@@ -2,17 +2,20 @@ from typing import Annotated
 
 from arcade_tdk import ToolContext, tool
 from arcade_tdk.auth import Google
-from arcade_tdk.errors import RetryableToolError
 
+from arcade_google_sheets.converters import SheetDataInputToValueRangesConverter
 from arcade_google_sheets.models import (
-    SheetDataInput,
     Spreadsheet,
     SpreadsheetProperties,
 )
 from arcade_google_sheets.utils import (
+    batch_update,
     build_sheets_service,
+    col_to_index,
     create_sheet,
+    get_sheet_metadata_from_identifier,
     parse_write_to_cell_response,
+    validate_sheet_data_input,
     validate_write_to_cell_params,
 )
 
@@ -40,15 +43,7 @@ def create_spreadsheet(
     """
     service = build_sheets_service(context.get_auth_token_or_empty())
 
-    try:
-        sheet_data = SheetDataInput(data=data)  # type: ignore[arg-type]
-    except Exception as e:
-        msg = "Invalid JSON or unexpected data format for parameter `data`"
-        raise RetryableToolError(
-            message=msg,
-            additional_prompt_content=f"{msg}: {e}",
-            retry_after_ms=100,
-        )
+    sheet_data = validate_sheet_data_input(data)
 
     spreadsheet = Spreadsheet(
         properties=SpreadsheetProperties(title=title),
@@ -112,3 +107,120 @@ def write_to_cell(
     )
 
     return parse_write_to_cell_response(sheet_properties)
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/drive.file"],
+    )
+)
+def update_cells(
+    context: ToolContext,
+    spreadsheet_id: Annotated[str, "The id of the spreadsheet to write to"],
+    data: Annotated[
+        str,
+        "The data to write. A JSON string (property names enclosed in double quotes) "
+        "representing a dictionary that maps row numbers to dictionaries that map "
+        "column letters to cell values. For example, data[23]['C'] is the value for cell C23. "
+        "This is the same format accepted by create_spreadsheet. "
+        "Type hint: dict[int, dict[str, int | float | str | bool]]",
+    ],
+    sheet_position: Annotated[
+        int | None,
+        "The position/tab of the sheet in the spreadsheet to write to. "
+        "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 write to. If provided, takes "
+        "precedence over sheet_position.",
+    ] = None,
+) -> Annotated[dict, "The status of the operation, including updated ranges and counts"]:
+    """
+    Write values to a Google Sheet using a flexible data format.
+
+    sheet_id_or_name takes precedence over sheet_position. If a sheet is not mentioned,
+    then always assume the default sheet_position is sufficient.
+    """
+    service = build_sheets_service(context.get_auth_token_or_empty())
+
+    sheet_data = validate_sheet_data_input(data)
+    sheet_name, sheet_id, sheet_url = get_sheet_metadata_from_identifier(
+        service, spreadsheet_id, sheet_position, sheet_id_or_name
+    )
+    converter = SheetDataInputToValueRangesConverter(sheet_name, sheet_data)
+    value_ranges = converter.convert()
+
+    response = batch_update(service, spreadsheet_id, value_ranges)
+
+    return {**response, "sheet_url": sheet_url, "sheet_id": sheet_id}
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/drive.file"],
+    )
+)
+def add_note_to_cell(
+    context: ToolContext,
+    spreadsheet_id: Annotated[str, "The id of the spreadsheet to add a comment to"],
+    column: Annotated[str, "The column string to add a note to. For example, 'A', 'F', or 'AZ'"],
+    row: Annotated[int, "The row number to add a note to"],
+    note_text: Annotated[str, "The text for the note to add"],
+    sheet_position: Annotated[
+        int | None,
+        "The position/tab of the sheet in the spreadsheet to write to. "
+        "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 write to. If provided, takes "
+        "precedence over sheet_position.",
+    ] = None,
+) -> Annotated[dict, "The status of the operation"]:
+    """
+    Add a note to a specific cell in a spreadsheet. A note is a small
+    piece of text attached to a cell (shown with a black triangle) that
+    appears when you hover over the cell.
+
+    sheet_id_or_name takes precedence over sheet_position. If a sheet is not mentioned,
+    then always assume the default sheet_position is sufficient.
+    """
+    service = build_sheets_service(context.get_auth_token_or_empty())
+
+    sheet_name, sheet_id, sheet_url = get_sheet_metadata_from_identifier(
+        service, spreadsheet_id, sheet_position, sheet_id_or_name
+    )
+    column_index = col_to_index(column)
+
+    service.spreadsheets().batchUpdate(
+        spreadsheetId=spreadsheet_id,
+        body={
+            "requests": [
+                {
+                    "repeatCell": {
+                        "range": {
+                            "sheetId": sheet_id,
+                            "startRowIndex": row - 1,
+                            "endRowIndex": row,
+                            "startColumnIndex": column_index,
+                            "endColumnIndex": column_index + 1,
+                        },
+                        "cell": {
+                            "note": note_text,
+                        },
+                        "fields": "note",
+                    },
+                }
+            ]
+        },
+    ).execute()
+
+    return {
+        "status": "success",
+        "sheet_url": sheet_url,
+        "sheet_id": sheet_id,
+        "sheet_name": sheet_name,
+    }

arcade_google_sheets/utils.py

@@ -10,7 +10,12 @@ from arcade_google_sheets.constants import (
     DEFAULT_SHEET_COLUMN_COUNT,
     DEFAULT_SHEET_ROW_COUNT,
 )
-from arcade_google_sheets.enums import NumberFormatType, SheetIdentifierType
+from arcade_google_sheets.enums import (
+    Corpora,
+    NumberFormatType,
+    OrderBy,
+    SheetIdentifierType,
+)
 from arcade_google_sheets.models import (
     CellData,
     CellExtendedValue,
@@ -23,7 +28,9 @@ from arcade_google_sheets.models import (
     SheetDataInput,
     SheetProperties,
     Spreadsheet,
+    ValueRange,
 )
+from arcade_google_sheets.templates import sheet_url_template
 from arcade_google_sheets.types import CellValue
 
 logging.basicConfig(
@@ -34,6 +41,15 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 
+def remove_none_values(params: dict) -> dict:
+    """
+    Remove None values from a dictionary.
+    :param params: The dictionary to clean
+    :return: A new dictionary with None values removed
+    """
+    return {k: v for k, v in params.items() if v is not None}
+
+
 def build_sheets_service(auth_token: str | None) -> Resource:  # type: ignore[no-any-unimported]
     """
     Build a Sheets service object.
@@ -42,6 +58,14 @@ def build_sheets_service(auth_token: str | None) -> Resource:  # type: ignore[no
     return build("sheets", "v4", credentials=Credentials(auth_token))
 
 
+def build_drive_service(auth_token: str | None) -> Resource:  # type: ignore[no-any-unimported]
+    """
+    Build a Drive service object.
+    """
+    auth_token = auth_token or ""
+    return build("drive", "v3", credentials=Credentials(auth_token))
+
+
 def col_to_index(col: str) -> int:
     """Convert a sheet's column string to a 0-indexed column index
 
@@ -461,6 +485,34 @@ def convert_api_grid_data_to_dict(grids: list[dict]) -> dict:
     return dict(sorted(result.items()))
 
 
+def validate_sheet_data_input(data: str | None) -> SheetDataInput:
+    """
+    Validate and convert data to SheetDataInput, raising RetryableToolError on validation failure.
+    `data` is a JSON string representing a dictionary that maps row numbers to dictionaries that map
+    column letters to cell values.
+
+    Args:
+        data: The data parameter to validate, a JSON string representing a dictionary that maps
+        row numbers to dictionaries that map column letters to cell values.
+        Type hint: dict[int, dict[str, int | float | str | bool]]
+
+    Returns:
+        SheetDataInput: The validated sheet data input object
+
+    Raises:
+        RetryableToolError: If the data is invalid JSON or has an unexpected format
+    """
+    try:
+        return SheetDataInput(data=data)  # type: ignore[arg-type]
+    except Exception as e:
+        msg = "Invalid JSON or unexpected data format for parameter `data`"
+        raise RetryableToolError(
+            message=msg,
+            additional_prompt_content=f"{msg}: {e}",
+            retry_after_ms=100,
+        )
+
+
 def validate_write_to_cell_params(  # type: ignore[no-any-unimported]
     service: Resource,
     spreadsheet_id: str,
@@ -590,7 +642,7 @@ def calculate_a1_sheet_range(
     return None
 
 
-def find_sheet_by_identifier(
+def get_sheet_by_identifier(
     sheets: list[Sheet], sheet_identifier: str, sheet_identifier_type: SheetIdentifierType
 ) -> Sheet | None:
     """
@@ -622,6 +674,62 @@ def find_sheet_by_identifier(
     return None
 
 
+def get_spreadsheet_metadata_helper(sheets_service: Resource, spreadsheet_id: str) -> Spreadsheet:  # type: ignore[no-any-unimported]
+    """Get the spreadsheet metadata to collect the sheet names and dimensions
+
+    Args:
+        sheets_service (Resource): The Google Sheets service.
+        spreadsheet_id (str): The ID of the spreadsheet provided to the tool.
+
+    Returns:
+        Spreadsheet: The spreadsheet with only the metadata.
+    """
+    metadata_response = (
+        sheets_service.spreadsheets()
+        .get(
+            spreadsheetId=spreadsheet_id,
+            includeGridData=False,
+            fields="spreadsheetId,spreadsheetUrl,properties/title,sheets/properties",
+        )
+        .execute()
+    )
+    return Spreadsheet.model_validate(metadata_response)
+
+
+def batch_update(service: Resource, spreadsheet_id: str, data: list[ValueRange]) -> dict:  # type: ignore[no-any-unimported]
+    """
+    Batch update a spreadsheet with a list of ValueRanges.
+
+    Args:
+        service (Resource): The Google Sheets service.
+        spreadsheet_id (str): The ID of the spreadsheet to update.
+        data (list[ValueRange]): The data to update the spreadsheet with.
+
+    Returns:
+        dict: The response from the batch update.
+    """
+    body = {
+        "valueInputOption": "USER_ENTERED",
+        "data": [value_range.model_dump() for value_range in data],
+    }
+    response = (
+        service.spreadsheets()
+        .values()
+        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
+        .execute()
+    )
+    updated_ranges = [
+        value_response["updatedRange"] for value_response in response.get("responses", [])
+    ]
+    return {
+        "spreadsheet_id": response["spreadsheetId"],
+        "total_updated_rows": response["totalUpdatedRows"],
+        "total_updated_columns": response["totalUpdatedColumns"],
+        "total_updated_cells": response["totalUpdatedCells"],
+        "updated_ranges": updated_ranges,
+    }
+
+
 def get_spreadsheet_with_pagination(  # type: ignore[no-any-unimported]
     service: Resource,
     spreadsheet_id: str,
@@ -651,26 +759,19 @@ def get_spreadsheet_with_pagination(  # type: ignore[no-any-unimported]
     """
 
     # 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)
+    spreadsheet_with_only_metadata = get_spreadsheet_metadata_helper(service, spreadsheet_id)
 
-    target_sheet = find_sheet_by_identifier(
-        spreadsheet.sheets, sheet_identifier, sheet_identifier_type
+    target_sheet = get_sheet_by_identifier(
+        spreadsheet_with_only_metadata.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])
+                + ", ".join([
+                    sheet.model_dump_json() for sheet in spreadsheet_with_only_metadata.sheets
+                ])
             ),
         )
 
@@ -706,7 +807,7 @@ def get_spreadsheet_with_pagination(  # type: ignore[no-any-unimported]
             .execute()
         )
     else:
-        response = metadata_response
+        response = spreadsheet_with_only_metadata.model_dump()
 
     return parse_get_spreadsheet_response(response)
 
@@ -765,6 +866,61 @@ def process_get_spreadsheet_params(
     )
 
 
+def get_sheet_metadata_from_identifier(  # type: ignore[no-any-unimported]
+    service: Resource,
+    spreadsheet_id: str,
+    sheet_position: int | None,
+    sheet_id_or_name: str | None,
+) -> tuple[str, int, str]:
+    """Get the actual sheet name from position, id, or name identifier.
+
+    Args:
+        service (Resource): The Google Sheets service.
+        spreadsheet_id (str): The ID of the spreadsheet.
+        sheet_position (int | None): The position/tab of the sheet (1-indexed).
+        sheet_id_or_name (str | None): The id or name of the sheet.
+
+    Returns:
+        tuple[str, str, str]: The sheet's title, id, and url.
+
+    Raises:
+        ToolExecutionError: If the sheet is not found.
+    """
+    # Determine the sheet identifier and type
+    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:
+        # Default to first sheet
+        sheet_identifier = "1"
+        sheet_identifier_type = SheetIdentifierType.POSITION
+
+    spreadsheet = get_spreadsheet_metadata_helper(service, spreadsheet_id)
+
+    target_sheet = get_sheet_by_identifier(
+        spreadsheet.sheets, sheet_identifier, sheet_identifier_type
+    )
+
+    if not target_sheet:
+        raise ToolExecutionError(
+            message=f"Sheet with {sheet_identifier_type.value} '{sheet_identifier}' not found",
+            developer_message=(
+                "Sheet(s) in the spreadsheet: "
+                + ", ".join([sheet.properties.title for sheet in spreadsheet.sheets])
+            ),
+        )
+
+    sheet_url = sheet_url_template.format(
+        spreadsheet_id=spreadsheet_id,
+        sheet_id=target_sheet.properties.sheetId,
+    )
+
+    return target_sheet.properties.title, target_sheet.properties.sheetId, sheet_url
+
+
 def raise_for_large_payload(data: dict) -> None:
     """Enforce a 10MB limit on the data size.
 
@@ -783,3 +939,85 @@ def raise_for_large_payload(data: dict) -> None:
             "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",
         )
+
+
+# ------------------------------
+# Search Utils
+# ------------------------------
+def build_files_list_query(
+    mime_type: str,
+    document_contains: list[str] | None = None,
+    document_not_contains: list[str] | None = None,
+) -> str:
+    query = [f"(mimeType = '{mime_type}' and trashed = false)"]
+
+    if isinstance(document_contains, str):
+        document_contains = [document_contains]
+
+    if isinstance(document_not_contains, str):
+        document_not_contains = [document_not_contains]
+
+    if document_contains:
+        for keyword in document_contains:
+            name_contains = keyword.replace("'", "\\'")
+            full_text_contains = keyword.replace("'", "\\'")
+            keyword_query = (
+                f"(name contains '{name_contains}' or fullText contains '{full_text_contains}')"
+            )
+            query.append(keyword_query)
+
+    if document_not_contains:
+        for keyword in document_not_contains:
+            name_not_contains = keyword.replace("'", "\\'")
+            full_text_not_contains = keyword.replace("'", "\\'")
+            keyword_query = (
+                f"(not (name contains '{name_not_contains}' or "
+                f"fullText contains '{full_text_not_contains}'))"
+            )
+            query.append(keyword_query)
+
+    return " and ".join(query)
+
+
+def build_files_list_params(
+    mime_type: str,
+    page_size: int,
+    order_by: list[OrderBy] | None,
+    pagination_token: str | None,
+    include_shared_drives: bool,
+    search_only_in_shared_drive_id: str | None,
+    include_organization_domain_spreadsheets: bool,
+    spreadsheet_contains: list[str] | None = None,
+    spreadsheet_not_contains: list[str] | None = None,
+) -> dict[str, Any]:
+    query = build_files_list_query(
+        mime_type=mime_type,
+        document_contains=spreadsheet_contains,
+        document_not_contains=spreadsheet_not_contains,
+    )
+
+    params = {
+        "q": query,
+        "pageSize": page_size,
+        "orderBy": ",".join([item.value for item in order_by]) if order_by else None,
+        "pageToken": pagination_token,
+    }
+
+    if (
+        include_shared_drives
+        or search_only_in_shared_drive_id
+        or include_organization_domain_spreadsheets
+    ):
+        params["includeItemsFromAllDrives"] = "true"
+        params["supportsAllDrives"] = "true"
+
+    if search_only_in_shared_drive_id:
+        params["driveId"] = search_only_in_shared_drive_id
+        params["corpora"] = Corpora.DRIVE.value
+
+    if include_organization_domain_spreadsheets:
+        params["corpora"] = Corpora.DOMAIN.value
+
+    params = remove_none_values(params)
+
+    return params

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arcade_google_sheets
-Version: 3.0.0
+Version: 3.1.1
 Summary: Arcade.dev LLM tools for Google Sheets
 Author-email: Arcade <dev@arcade.dev>
 License: Proprietary - Arcade Software License Agreement v1.0

arcade_google_sheets-3.1.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+arcade_google_sheets/__init__.py,sha256=FB9h_cws_gu3UJp32GWlqvBQyAOb77JfAJNSSBqz-Jk,177
+arcade_google_sheets/constants.py,sha256=4tQOrQ1YagSklJSSw5Eq21XCcFCJdO7lso5SqWIdrPI,63
+arcade_google_sheets/converters.py,sha256=1muE_28Jk0eyFUzoVo_lN0_qy3z-uv7f5XoZLH9mitQ,3924
+arcade_google_sheets/decorators.py,sha256=QMqfvSXaFBoxYJrz69EGeMdAxF0V7JPReVXfp73Nf3Y,753
+arcade_google_sheets/enums.py,sha256=30OMPu2l_aUjz8kQzC1mR5w0lLbs0fZn8T6PDtoXpL4,4608
+arcade_google_sheets/file_picker.py,sha256=kGfUVfH5QVlIW1sL-_gAwPokt7TwVEcPk3Vnk53GKUE,2005
+arcade_google_sheets/models.py,sha256=xwPdwUis0OHTDbSLy85qWl7zIh2lDTi5HZMNKwdZjzo,8627
+arcade_google_sheets/templates.py,sha256=p3ty6Kwo7l73EEsZTaRfdG4jzQ9XvlqqeXMLKB1ydEw,489
+arcade_google_sheets/types.py,sha256=R-rCRcyFqDZx3jgl_kWeCliqC8fHuZ8ub_LQ2KoU2AE,37
+arcade_google_sheets/utils.py,sha256=VmDZOzAOEtfSPOra-ieVl_U16RLonQUOnZ4RW4Gf-oA,34895
+arcade_google_sheets/tools/__init__.py,sha256=IiSd-0Q4_uxeKI8nVMT3JVRoF5G5GB8e5Z9SkGpSnt8,472
+arcade_google_sheets/tools/read.py,sha256=g7uGhyhFNlDPHKT3xhg7NdMaSYuvzzefSzrb1XqiI80,4309
+arcade_google_sheets/tools/search.py,sha256=EnO739RmBryDerYnzV7eD_drchNNVqS50DgdySYh9Ac,5381
+arcade_google_sheets/tools/write.py,sha256=4kNx941PQt6VUGTogbepnbfUdcsVze6u5c8QvlNnWCI,7782
+arcade_google_sheets-3.1.1.dist-info/METADATA,sha256=M6BDKH6yb3xVzPC9ByD0BjJePVy0D5g5x7IxyiouuZ8,1123
+arcade_google_sheets-3.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+arcade_google_sheets-3.1.1.dist-info/licenses/LICENSE,sha256=ixeE7aL9b2B-_ZYHTY1vQcJB4NufKeo-LWwKNObGDN0,1960
+arcade_google_sheets-3.1.1.dist-info/RECORD,,

arcade_google_sheets-3.0.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-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=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=0SCjW92wedFilovwc-tERAtfdBYGZ1OZlil_XUZEiVc,26803
-arcade_google_sheets/tools/__init__.py,sha256=TPlitJn1VJffCXFkpOtoYXNsaEFkpujQzsYvuikCe4U,209
-arcade_google_sheets/tools/read.py,sha256=tdDrXwt1PCytQy1oBlU4HKZ7OjiTpIU43og5VkFAMqs,2704
-arcade_google_sheets/tools/write.py,sha256=gmbErdBbBKUEPxGjCWDpMJ9pMWRAvoEjApIXFQax6Z4,3598
-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,,