arcade-google-sheets 2.0.0rc1__py3-none-any.whl → 3.1.0__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

@@ -23,3 +23,127 @@ class NumberFormatType(str, Enum):
     NUMBER = "NUMBER"
     PERCENT = "PERCENT"
     CURRENCY = "CURRENCY"
+
+
+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,9 +4,13 @@ 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,
-    parse_get_spreadsheet_response,
+    get_spreadsheet_metadata_helper,
+    get_spreadsheet_with_pagination,
+    process_get_spreadsheet_params,
+    raise_for_large_payload,
 )
 
 
@@ -20,23 +24,100 @@ 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())
+
+    data = get_spreadsheet_with_pagination(
+        service,
+        spreadsheet_id,
+        sheet_identifier,
+        sheet_identifier_type,
+        start_row,
+        start_col,
+        max_rows,
+        max_cols,
+    )
+
+    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())
 
-    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",
+    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"],
         )
-        .execute()
-    )
-    return parse_get_spreadsheet_response(response)
+
+    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,134 @@
+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",
+    ] = 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 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