aipype-g - Google API Integrations

The aipype-g package provides seamless integration with Google APIs, enabling aipype pipelines to work with Gmail, Google Sheets, and other Google services.

Note

This package requires Google API credentials and is designed for workflows that need to interact with Google services.

Package Overview

aipype-g: Google API integrations for the aipype framework.

class GoogleOAuthTask[source]

Bases: BaseTask

Task that handles Google OAuth2 authentication for specified services.

Parameters:

name (str)
config (Dict[str, Any])
dependencies (Optional[List[TaskDependency]])

__init__(name, config, dependencies=None)[source]

Initialize Google OAuth task.

Parameters:

name (str) – Task name
config (Dict[str, Any]) – Configuration dictionary containing: - scopes: List of Google API scopes (optional, defaults to Gmail+Sheets) - service_types: List of service types [“gmail”, “sheets”, “drive”] (alternative to scopes) - credentials_file: Path to OAuth2 credentials file (optional) - token_file: Path to OAuth2 token file (optional)
dependencies (Optional[List[TaskDependency]]) – List of task dependencies

static create_combined_auth_config(credentials_file=None, token_file=None)[source]

Helper to create configuration for Gmail + Sheets authentication.

Parameters:

credentials_file (Optional[str]) – Path to OAuth2 credentials file
token_file (Optional[str]) – Path to OAuth2 token file

Return type:

Dict[str, Any]

Returns:

Configuration dictionary for GoogleOAuthTask

static create_custom_scopes_config(scopes, credentials_file=None, token_file=None)[source]

Helper to create configuration with custom scopes.

Parameters:

scopes (List[str]) – List of Google API scopes
credentials_file (Optional[str]) – Path to OAuth2 credentials file
token_file (Optional[str]) – Path to OAuth2 token file

Return type:

Dict[str, Any]

Returns:

Configuration dictionary for GoogleOAuthTask

static create_gmail_auth_config(credentials_file=None, token_file=None)[source]

Helper to create configuration for Gmail-only authentication.

Parameters:

credentials_file (Optional[str]) – Path to OAuth2 credentials file
token_file (Optional[str]) – Path to OAuth2 token file

Return type:

Dict[str, Any]

Returns:

Configuration dictionary for GoogleOAuthTask

static create_sheets_auth_config(credentials_file=None, token_file=None)[source]

Helper to create configuration for Sheets-only authentication.

Parameters:

credentials_file (Optional[str]) – Path to OAuth2 credentials file
token_file (Optional[str]) – Path to OAuth2 token file

Return type:

Dict[str, Any]

Returns:

Configuration dictionary for GoogleOAuthTask

get_dependencies()[source]

Get the list of task dependencies.

Return type:: List[TaskDependency]
Returns:: List of TaskDependency objects

run()[source]

Perform Google OAuth2 authentication.

Returns:

credentials: Authenticated credentials object (serialized)
scopes: List of authorized scopes
auth_info: Authentication metadata
service_access: Dictionary showing which services are accessible

Return type:

TaskResult containing

class GmailListEmailsTask[source]

Bases: BaseTask

Task that lists Gmail messages with optional filters and search queries.

Parameters:

name (str)
config (Dict[str, Any])
dependencies (Optional[List[TaskDependency]])

__init__(name, config, dependencies=None)[source]

Initialize Gmail list emails task.

Parameters:

name (str) – Task name
config (Dict[str, Any]) – Configuration dictionary containing: - query: Gmail search query (optional, can be resolved from dependencies) - max_results: Maximum number of messages to return (default: 10) - include_spam_trash: Include spam and trash messages (default: False) - label_ids: List of label IDs to filter by (optional) - credentials_file: Path to OAuth2 credentials file (optional) - token_file: Path to OAuth2 token file (optional) - parse_messages: Whether to parse full message content (default: True)
dependencies (Optional[List[TaskDependency]]) – List of task dependencies

static create_search_query(**kwargs)[source]

Helper method to create Gmail search queries using common patterns.

Supported kwargs:

from_sender: str - Filter by sender email
to_recipient: str - Filter by recipient email
subject: str - Filter by subject
newer_than_days: int - Messages newer than X days
older_than_days: int - Messages older than X days
has_attachment: bool - Messages with attachments
is_unread: bool - Unread messages
is_important: bool - Important messages
is_starred: bool - Starred messages
label: str - Messages with specific label
custom_query: str - Additional custom query terms

Return type:: str
Returns:: Gmail search query string
Parameters:: kwargs (Any)

get_dependencies()[source]

Get the list of task dependencies.

Return type:: List[TaskDependency]
Returns:: List of TaskDependency objects

run()[source]

List Gmail messages based on query and filters.

Returns:

messages: List of GmailMessage objects (if parse_messages=True)
message_ids: List of message IDs (if parse_messages=False)
search_result: GmailSearchResult object with metadata
query_used: The Gmail query that was executed
total_found: Total number of messages found
retrieved_count: Number of messages actually retrieved

Return type:

TaskResult containing

class GmailReadEmailTask[source]

Bases: BaseTask

Task that reads specific Gmail message content by ID.

Parameters:

name (str)
config (Dict[str, Any])
dependencies (Optional[List[TaskDependency]])

__init__(name, config, dependencies=None)[source]

Initialize Gmail read email task.

Parameters:

name (str) – Task name
config (Dict[str, Any]) – Configuration dictionary containing: - message_id: Gmail message ID to read (can be resolved from dependencies) - message_ids: List of message IDs to read (alternative to message_id) - format: Message format (“full”, “minimal”, “raw”, “metadata”) (default: “full”) - include_attachments: Whether to include attachment info (default: True) - credentials_file: Path to OAuth2 credentials file (optional) - token_file: Path to OAuth2 token file (optional)
dependencies (Optional[List[TaskDependency]]) – List of task dependencies

static create_batch_read_config(message_ids, format='full', include_attachments=True, credentials_file=None, token_file=None)[source]

Helper method to create configuration for reading multiple messages.

Parameters:

message_ids (List[str]) – List of Gmail message IDs to read
format (str) – Message format to use
include_attachments (bool) – Whether to include attachment information
credentials_file (Optional[str]) – Path to OAuth2 credentials file
token_file (Optional[str]) – Path to OAuth2 token file

Return type:

Dict[str, Any]

Returns:

Configuration dictionary for GmailReadEmailTask

static extract_message_ids_from_list_result(list_result_data)[source]

Helper method to extract message IDs from GmailListEmailsTask result.

Parameters:: list_result_data (Dict[str, Any]) – Result data from GmailListEmailsTask
Return type:: List[str]
Returns:: List of message IDs

get_dependencies()[source]

Get the list of task dependencies.

Return type:: List[TaskDependency]
Returns:: List of TaskDependency objects

run()[source]

Read Gmail message(s) content.

Returns:

message: GmailMessage object (if single message_id)
messages: List of GmailMessage objects (if multiple message_ids)
message_count: Number of messages read
failed_reads: List of failed message IDs with error details
success_count: Number of successfully read messages
format_used: Message format that was used

Return type:

TaskResult containing

class ReadGoogleSheetTask[source]

Bases: BaseTask

Task that reads data from Google Sheets and returns as 2D arrays.

Parameters:

name (str)
config (Dict[str, Any])
dependencies (Optional[List[TaskDependency]])

__init__(name, config, dependencies=None)[source]

Initialize Read Google Sheet task.

Parameters:

name (str) – Task name
config (Dict[str, Any]) –
Configuration dictionary containing:
- spreadsheet_id: Google Spreadsheet ID (required)
- range: Range in A1 notation (e.g., ‘Sheet1!A1:C10’) (optional)
- sheet_name: Name of sheet to read (alternative to range) (optional)
- start_row: Starting row number (1-based) (optional, default: 1)
- end_row: Ending row number (1-based) (optional)
- start_col: Starting column number (1-based) (optional, default: 1)
- end_col: Ending column number (1-based) (optional)
- include_headers: Whether first row contains headers (default: True)
- credentials: Pre-authenticated credentials (can be resolved from dependencies)
- credentials_file: Path to OAuth2 credentials file (optional)
- token_file: Path to OAuth2 token file (optional)
- timeout: Request timeout in seconds (default: 30)
dependencies (Optional[List[TaskDependency]]) – List of task dependencies

static create_full_sheet_config(spreadsheet_id, sheet_name, include_headers=True, credentials_file=None, token_file=None)[source]

Helper to create configuration for reading an entire sheet.

Parameters:

spreadsheet_id (str) – Google Spreadsheet ID
sheet_name (str) – Name of sheet to read
include_headers (bool) – Whether first row contains headers
credentials_file (Optional[str]) – Path to OAuth2 credentials file
token_file (Optional[str]) – Path to OAuth2 token file

Return type:

Dict[str, Any]

Returns:

Configuration dictionary for ReadGoogleSheetTask

static create_range_config(spreadsheet_id, range_a1, include_headers=True, credentials_file=None, token_file=None)[source]

Helper to create configuration for reading a specific range.

Parameters:

spreadsheet_id (str) – Google Spreadsheet ID
range_a1 (str) – Range in A1 notation (e.g., ‘Sheet1!A1:C10’)
include_headers (bool) – Whether first row contains headers
credentials_file (Optional[str]) – Path to OAuth2 credentials file
token_file (Optional[str]) – Path to OAuth2 token file

Return type:

Dict[str, Any]

Returns:

Configuration dictionary for ReadGoogleSheetTask

static create_sheet_config(spreadsheet_id, sheet_name, start_row=1, end_row=None, start_col=1, end_col=None, include_headers=True, credentials_file=None, token_file=None)[source]

Helper to create configuration for reading a sheet with bounds.

Parameters:

spreadsheet_id (str) – Google Spreadsheet ID
sheet_name (str) – Name of sheet to read
start_row (int) – Starting row (1-based)
end_row (Optional[int]) – Ending row (1-based, optional)
start_col (int) – Starting column (1-based)
end_col (Optional[int]) – Ending column (1-based, optional)
include_headers (bool) – Whether first row contains headers
credentials_file (Optional[str]) – Path to OAuth2 credentials file
token_file (Optional[str]) – Path to OAuth2 token file

Return type:

Dict[str, Any]

Returns:

Configuration dictionary for ReadGoogleSheetTask

get_dependencies()[source]

Get the list of task dependencies.

Return type:: List[TaskDependency]
Returns:: List of TaskDependency objects

run()[source]

Read data from Google Sheet.

Returns:

sheet_data: SheetData object (serialized)
values: 2D array of cell values
headers: List of header names (if include_headers=True)
num_rows: Number of data rows
num_cols: Number of columns
shape: Tuple of (rows, cols)
spreadsheet_info: Metadata about the spreadsheet

Return type:

TaskResult containing

class GmailService[source]

Bases: object

Gmail API service with OAuth2 authentication and common operations.

Parameters:

credentials (Optional[Credentials])
credentials_file (Optional[str])
token_file (Optional[str])
scopes (Optional[List[str]])
timeout (int)

__init__(credentials=None, credentials_file=None, token_file=None, scopes=None, timeout=30)[source]

Initialize Gmail service.

Parameters:

credentials (Optional[Credentials]) – Pre-authenticated Google credentials (from GoogleOAuthTask)
credentials_file (Optional[str]) – Path to OAuth2 credentials JSON file
token_file (Optional[str]) – Path to store/load OAuth2 tokens
scopes (Optional[List[str]]) – List of Gmail API scopes to request
timeout (int) – Request timeout in seconds (default: 30)

create_label(name, message_list_visibility='show', label_list_visibility='labelShow')[source]

Create a new Gmail label.

Parameters:

name (str) – Label name
message_list_visibility (str) – ‘show’ or ‘hide’
label_list_visibility (str) – ‘labelShow’, ‘labelShowIfUnread’, or ‘labelHide’

Return type:

GmailLabel

Returns:

Created GmailLabel object

Raises:

GmailServiceError – If creation fails

get_message(message_id, format='full', progress_callback=None)[source]

Get a specific Gmail message by ID.

Parameters:

message_id (str) – The Gmail message ID
format (str) – Message format (‘minimal’, ‘full’, ‘raw’, ‘metadata’)
progress_callback (Optional[Callable[[str], None]]) – Optional callback to report progress

Return type:

Dict[str, Any]

Returns:

Message data dictionary

Raises:

GmailServiceError – If API call fails

list_labels()[source]

List all Gmail labels.

Return type:: List[GmailLabel]
Returns:: List of GmailLabel objects
Raises:: GmailServiceError – If API call fails

list_messages(query='', max_results=10, label_ids=None, include_spam_trash=False, progress_callback=None)[source]

List Gmail messages with optional query and filters.

Parameters:

query (str) – Gmail search query (same syntax as Gmail search)
max_results (int) – Maximum number of messages to return
label_ids (Optional[List[str]]) – List of label IDs to filter by
include_spam_trash (bool) – Whether to include spam and trash
progress_callback (Optional[Callable[[str], None]]) – Optional callback to report progress

Return type:

List[Dict[str, Any]]

Returns:

List of message metadata dictionaries

Raises:

GmailServiceError – If API call fails

modify_message_labels(message_id, add_label_ids=None, remove_label_ids=None)[source]

Add or remove labels from a message.

Parameters:

message_id (str) – The Gmail message ID
add_label_ids (Optional[List[str]]) – List of label IDs to add
remove_label_ids (Optional[List[str]]) – List of label IDs to remove

Return type:

Dict[str, Any]

Returns:

Modified message data

Raises:

GmailServiceError – If modification fails

parse_message(message_data)[source]

Parse Gmail API message data into GmailMessage object.

Parameters:: message_data (Dict[str, Any]) – Raw message data from Gmail API
Return type:: GmailMessage
Returns:: Parsed GmailMessage object

send_message(to, subject, body, html_body=None, cc=None, bcc=None, reply_to_message_id=None)[source]

Send an email message.

Parameters:

to (str) – Recipient email address
subject (str) – Email subject
body (str) – Plain text body
html_body (Optional[str]) – HTML body (optional)
cc (Optional[str]) – CC recipients (optional)
bcc (Optional[str]) – BCC recipients (optional)
reply_to_message_id (Optional[str]) – Message ID to reply to (optional)

Return type:

Dict[str, Any]

Returns:

Sent message data

Raises:

GmailServiceError – If sending fails

class GoogleSheetsService[source]

Bases: object

Google Sheets API service with OAuth2 authentication and read operations.

Parameters:

credentials (Optional[Credentials])
credentials_file (Optional[str])
token_file (Optional[str])
timeout (int)

__init__(credentials=None, credentials_file=None, token_file=None, timeout=30)[source]

Initialize Google Sheets service.

Parameters:

credentials (Optional[Credentials]) – Pre-authenticated Google credentials (from GoogleOAuthTask)
credentials_file (Optional[str]) – Path to OAuth2 credentials JSON file (fallback)
token_file (Optional[str]) – Path to store/load OAuth2 tokens (fallback)
timeout (int) – Request timeout in seconds (default: 30)

get_sheet_names(spreadsheet_id, progress_callback=None)[source]

Get list of sheet names in a spreadsheet.

Parameters:

spreadsheet_id (str) – ID of the Google Spreadsheet
progress_callback (Optional[Callable[[str], None]]) – Optional callback for progress updates

Return type:

List[str]

Returns:

List of sheet names

Raises:

GoogleSheetsError – If API call fails

get_spreadsheet_info(spreadsheet_id, progress_callback=None)[source]

Get information about a spreadsheet.

Parameters:

spreadsheet_id (str) – ID of the Google Spreadsheet
progress_callback (Optional[Callable[[str], None]]) – Optional callback for progress updates

Return type:

SpreadsheetInfo

Returns:

SpreadsheetInfo object with spreadsheet metadata

Raises:

GoogleSheetsError – If API call fails

read_all_data(spreadsheet_id, sheet_name, include_headers=True, progress_callback=None)[source]

Read all data from a sheet.

Parameters:

spreadsheet_id (str) – ID of the Google Spreadsheet
sheet_name (str) – Name of the sheet to read
include_headers (bool) – Whether first row should be treated as headers
progress_callback (Optional[Callable[[str], None]]) – Optional callback for progress updates

Return type:

SheetData

Returns:

SheetData object with all data from the sheet

Raises:

GoogleSheetsError – If API call fails

read_range(spreadsheet_id, range_a1, include_headers=True, progress_callback=None)[source]

Read data from a specific range in a spreadsheet.

Parameters:

spreadsheet_id (str) – ID of the Google Spreadsheet
range_a1 (str) – Range in A1 notation (e.g., ‘Sheet1!A1:C10’)
include_headers (bool) – Whether first row should be treated as headers
progress_callback (Optional[Callable[[str], None]]) – Optional callback for progress updates

Return type:

SheetData

Returns:

SheetData object with the read data

Raises:

GoogleSheetsError – If API call fails or range is invalid

read_sheet(spreadsheet_id, sheet_name, start_row=1, end_row=None, start_col=1, end_col=None, include_headers=True, progress_callback=None)[source]

Read data from a sheet with row/column bounds.

Parameters:

spreadsheet_id (str) – ID of the Google Spreadsheet
sheet_name (str) – Name of the sheet to read
start_row (int) – Starting row (1-based, default: 1)
end_row (Optional[int]) – Ending row (1-based, optional)
start_col (int) – Starting column (1-based, default: 1)
end_col (Optional[int]) – Ending column (1-based, optional)
include_headers (bool) – Whether first row should be treated as headers
progress_callback (Optional[Callable[[str], None]]) – Optional callback for progress updates

Return type:

SheetData

Returns:

SheetData object with the read data

Raises:

GoogleSheetsError – If API call fails

validate_range(spreadsheet_id, range_a1, progress_callback=None)[source]

Validate if a range exists and is accessible.

Parameters:

spreadsheet_id (str) – ID of the Google Spreadsheet
range_a1 (str) – Range in A1 notation
progress_callback (Optional[Callable[[str], None]]) – Optional callback for progress updates

Return type:

bool

Returns:

True if range is valid and accessible, False otherwise

class GoogleAuthService[source]

Bases: object

Unified Google OAuth2 authentication service for multiple Google APIs.

Parameters:

credentials_file (Optional[str])
token_file (Optional[str])
scopes (Optional[List[str]])

__init__(credentials_file=None, token_file=None, scopes=None)[source]

Initialize Google authentication service.

Parameters:

credentials_file (Optional[str]) – Path to OAuth2 credentials JSON file
token_file (Optional[str]) – Path to store/load OAuth2 tokens
scopes (Optional[List[str]]) – List of Google API scopes to request

authenticate()[source]

Authenticate with Google APIs using OAuth2.

Return type:: Credentials
Returns:: Authenticated Google credentials object
Raises:: GoogleAuthError – If authentication fails

static create_service_with_scopes(service_types, credentials_file=None, token_file=None)[source]

Create authentication service with scopes for specific service types.

Parameters:

service_types (List[str]) – List of service types (“gmail”, “sheets”, “drive”)
credentials_file (Optional[str]) – Path to credentials file
token_file (Optional[str]) – Path to token file

Return type:

GoogleAuthService

Returns:

GoogleAuthService configured with appropriate scopes

get_credentials()[source]

Get authenticated credentials, authenticating if necessary.

Return type:: Credentials
Returns:: Authenticated Google credentials object

get_scopes()[source]

Get the configured scopes.

Return type:: List[str]
Returns:: List of Google API scopes

has_gmail_access()[source]

Check if Gmail scopes are included.

Return type:: bool
Returns:: True if any Gmail scope is included

has_scope(scope)[source]

Check if a specific scope is included.

Parameters:: scope (str) – Google API scope to check
Return type:: bool
Returns:: True if scope is included, False otherwise

has_sheets_access()[source]

Check if Sheets scopes are included.

Return type:: bool
Returns:: True if any Sheets scope is included

is_authenticated()[source]

Check if already authenticated.

Return type:: bool
Returns:: True if authenticated, False otherwise

to_dict()[source]

Convert authentication info to dictionary.

Return type:: Dict[str, Any]
Returns:: Dictionary with authentication status and scopes

class GmailMessage[source]

Bases: object

Represents a Gmail message with parsed content.

Parameters:

message_id (str)
thread_id (str)
label_ids (List[str])
snippet (str)
subject (str)
sender (str)
recipient (str)
date (str)
body (str)
history_id (Optional[str])
internal_date (Optional[str])
size_estimate (int)
cc (str)
bcc (str)
html_body (str)
attachments (List[GmailAttachment])
headers (Dict[str, str])

__init__(message_id, thread_id, label_ids, snippet, subject, sender, recipient, date, body, history_id=None, internal_date=None, size_estimate=0, cc='', bcc='', html_body='', attachments=<factory>, headers=<factory>)

Parameters:

message_id (str)
thread_id (str)
label_ids (List[str])
snippet (str)
subject (str)
sender (str)
recipient (str)
date (str)
body (str)
history_id (Optional[str])
internal_date (Optional[str])
size_estimate (int)
cc (str)
bcc (str)
html_body (str)
attachments (List[GmailAttachment])
headers (Dict[str, str])

property attachment_count: int: Get number of attachments.

bcc: str = ''

cc: str = ''

property has_attachments: bool: Check if message has attachments.

history_id: Optional[str] = None

html_body: str = ''

internal_date: Optional[str] = None

property is_important: bool: Check if message is marked as important.

property is_starred: bool: Check if message is starred.

property is_unread: bool: Check if message is unread.

property sender_email: str: Extract sender email from sender field.

property sender_name: str: Extract sender name from sender field.

size_estimate: int = 0

to_dict()[source]

Convert message to dictionary.

Return type:: Dict[str, Any]

message_id: str

thread_id: str

label_ids: List[str]

snippet: str

subject: str

sender: str

recipient: str

date: str

body: str

attachments: List[GmailAttachment]

headers: Dict[str, str]

class GmailThread[source]

Bases: object

Represents a Gmail conversation thread.

Parameters:

thread_id (str)
history_id (str)
messages (List[GmailMessage])

__init__(thread_id, history_id, messages=<factory>)

Parameters:

thread_id (str)
history_id (str)
messages (List[GmailMessage])

property is_unread: bool: Check if thread has unread messages.

property latest_message: GmailMessage | None: Get the latest message in the thread.

property message_count: int: Get number of messages in thread.

property participants: List[str]: Get all unique participants in the thread.

to_dict()[source]

Convert thread to dictionary.

Return type:: Dict[str, Any]

thread_id: str

history_id: str

messages: List[GmailMessage]

class GmailLabel[source]

Bases: object

Represents a Gmail label.

Parameters:

label_id (str)
name (str)
message_list_visibility (Optional[str])
label_list_visibility (Optional[str])
label_type (Optional[str])
messages_total (Optional[int])
messages_unread (Optional[int])
threads_total (Optional[int])
threads_unread (Optional[int])

__init__(label_id, name, message_list_visibility=None, label_list_visibility=None, label_type=None, messages_total=None, messages_unread=None, threads_total=None, threads_unread=None)

Parameters:

label_id (str)
name (str)
message_list_visibility (Optional[str])
label_list_visibility (Optional[str])
label_type (Optional[str])
messages_total (Optional[int])
messages_unread (Optional[int])
threads_total (Optional[int])
threads_unread (Optional[int])

property is_system_label: bool: Check if this is a system label.

property is_user_label: bool: Check if this is a user-created label.

label_list_visibility: Optional[str] = None

label_type: Optional[str] = None

message_list_visibility: Optional[str] = None

messages_total: Optional[int] = None

messages_unread: Optional[int] = None

threads_total: Optional[int] = None

threads_unread: Optional[int] = None

to_dict()[source]

Convert label to dictionary.

Return type:: Dict[str, Any]

label_id: str

name: str

class GmailAttachment[source]

Bases: object

Represents a Gmail message attachment.

Parameters:

attachment_id (str)
filename (str)
mime_type (str)
size (int)

__init__(attachment_id, filename, mime_type, size)

Parameters:

attachment_id (str)
filename (str)
mime_type (str)
size (int)

attachment_id: str

filename: str

mime_type: str

size: int

class SheetData[source]

Bases: object

Represents data read from a Google Sheet.

Parameters:

spreadsheet_id (str)
sheet_name (str)
range_read (str)
values (List[List[str]])
headers (List[str])
metadata (Dict[str, Any])

__init__(spreadsheet_id, sheet_name, range_read, values=<factory>, headers=<factory>, metadata=<factory>)

Parameters:

spreadsheet_id (str)
sheet_name (str)
range_read (str)
values (List[List[str]])
headers (List[str])
metadata (Dict[str, Any])

filter_rows(condition_func)[source]

Filter rows based on a condition function.

Parameters:: condition_func (Callable[[List[str]], bool]) – Function that takes a row (List[str]) and returns bool
Return type:: SheetData
Returns:: New SheetData with filtered rows

get_cell(row_index, col_index)[source]

Get value from a specific cell.

Parameters:

row_index (int) – 0-based row index
col_index (int) – 0-based column index

Return type:

str

Returns:

Cell value as string, empty string if out of bounds

get_column(col_index)[source]

Get values from a specific column.

Parameters:: col_index (int) – 0-based column index
Return type:: List[str]
Returns:: List of values in the column

get_row(row_index)[source]

Get values from a specific row.

Parameters:: row_index (int) – 0-based row index
Return type:: List[str]
Returns:: List of values in the row

property has_headers: bool: Check if headers are defined.

property num_cols: int: Get number of columns.

property num_rows: int: Get number of data rows (excluding headers if present).

property shape: tuple[int, int]: Get shape as (rows, cols).

to_dict()[source]

Convert to dictionary representation.

Return type:: Dict[str, Any]

to_dict_list()[source]

Convert to list of dictionaries using headers as keys.

Return type:: List[Dict[str, str]]
Returns:: List of dictionaries, one per data row
Raises:: ValueError – If no headers are defined

spreadsheet_id: str

sheet_name: str

range_read: str

values: List[List[str]]

headers: List[str]

metadata: Dict[str, Any]

class SheetRange[source]

Bases: object

Represents a range within a Google Sheet.

Parameters:

sheet_name (str)
start_row (int)
start_col (int)
end_row (Optional[int])
end_col (Optional[int])

__init__(sheet_name, start_row, start_col, end_row=None, end_col=None)

Parameters:

sheet_name (str)
start_row (int)
start_col (int)
end_row (Optional[int])
end_col (Optional[int])

property a1_notation: str

C10’).

Type:: Convert to A1 notation (e.g., ’Sheet1!A1

end_col: Optional[int] = None

end_row: Optional[int] = None

static from_a1_notation(a1_range)[source]

Create SheetRange from A1 notation (e.g., ‘Sheet1!A1:C10’).

Parameters:: a1_range (str)
Return type:: SheetRange

sheet_name: str

start_row: int

start_col: int

class SpreadsheetInfo[source]

Bases: object

Represents information about a Google Spreadsheet.

Parameters:

spreadsheet_id (str)
title (str)
sheet_names (List[str])
properties (Dict[str, Any])

__init__(spreadsheet_id, title, sheet_names=<factory>, properties=<factory>)

Parameters:

spreadsheet_id (str)
title (str)
sheet_names (List[str])
properties (Dict[str, Any])

has_sheet(sheet_name)[source]

Check if a sheet exists.

Parameters:: sheet_name (str) – Name of the sheet to check
Return type:: bool
Returns:: True if sheet exists, False otherwise

property num_sheets: int: Get number of sheets in the spreadsheet.

to_dict()[source]

Convert to dictionary representation.

Return type:: Dict[str, Any]

spreadsheet_id: str

title: str

sheet_names: List[str]

properties: Dict[str, Any]