Skip to content

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 007 keeps its leading zeros. Defaults to None.

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.