Spreadsheet Manager
Google Spreadsheet SDK module.
This module provides async interface for interacting with Google Sheets. For synchronous operations and the base retry decorator, see google_sheets_sdk.py.
get_spreadsheet_instance(spreadsheet_id, client_email, private_key)
async
Get the spreadsheet instance with automatic retry for rate limits.
This function uses the retry infrastructure to automatically handle rate limit errors with exponential backoff. It's the recommended approach for production use.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
spreadsheet_id
|
str
|
The ID of the Google Spreadsheet. |
required |
client_email
|
str
|
The client email for Google Sheets API. |
required |
private_key
|
str
|
Base64-encoded private key for Google Sheets API. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Spreadsheet |
Spreadsheet
|
The spreadsheet instance. |
Raises:
| Type | Description |
|---|---|
EvalConfigurationError
|
If credentials are invalid. |
EvalResourceNotFoundError
|
If the spreadsheet does not exist or is not shared with the service account. |
BaseError
|
The normalized Sheets failure after all retries. |
google_sheets_async_retry(retry_config=None)
Decorator for async Google Sheets operations with automatic retry for rate limits.
This is the async version of the retry decorator. For synchronous operations, use google_sheets_retry from google_sheets_sdk.py.
Retry policy sheets_async: retry_config.max_retries + 1 attempts (default 4) with exponential backoff
and an overall deadline (default 300 s). Each failure is normalized first and only transient failures are
retried: throttling, connection failures and HTTP 500, 502, 503 and 504. The config's exception tuples are not used.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
retry_config
|
RetryConfig | None
|
Custom retry configuration. If None, uses default config optimized for Google Sheets rate limits. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Callable |
Decorated function with retry logic. |
load_gsheets(sheet_id, worksheet_name, client_email, private_key, text_columns=None)
async
Loads data from a Google Sheets worksheet as a list of dictionaries with exponential backoff.
Opening the spreadsheet and reading the worksheet share one retry budget.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sheet_id
|
str
|
The ID of the Google Sheet. |
required |
worksheet_name
|
str
|
The name of the worksheet within the Google Sheet. |
required |
client_email
|
str
|
The client email for Google Sheets API. |
required |
private_key
|
str
|
Base64-encoded private key for Google Sheets API. |
required |
text_columns
|
list[str] | None
|
Columns kept as text instead of converted to numbers, so an id
like |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: The data from the Google Sheets worksheet as a pandas DataFrame. |
Raises:
| Type | Description |
|---|---|
EvalConfigurationError
|
If credentials are invalid. |
EvalResourceNotFoundError
|
If the spreadsheet or worksheet does not exist. |
BaseError
|
The normalized Sheets failure after all retries. |