Sheets Client Setup

Build a small auth helper that produces an authenticated Google Sheets session using a service account JSON file and optional drive scope. The helper should request spreadsheet access by default, add drive access only when explicitly asked, and let callers choose whether to validate the connection immediately or defer checks until first use.

Capabilities

Authenticate with service account file

• Given a valid service account JSON file and spreadsheet id, build_client returns a session whose verify_access(spreadsheet_id) yields a dict containing the spreadsheet title and a positive sheet_count. @test
• When the service account file path does not exist, build_client raises FileNotFoundError mentioning credentials. @test

Optional Drive access

• When enable_drive=True and the drive scope is provided, drive_available() returns True and verify_access still succeeds for the same spreadsheet id. @test
• When enable_drive=False, drive_available() returns False even if other scopes are provided. @test

Retry and validation controls

• Passing retries=0 and validate=False builds a session without performing network checks; verify_access is only executed when explicitly called. @test

Implementation

@generates

API

from typing import Iterable, Mapping, Any, Optional


class SheetsSession:
    def verify_access(self, spreadsheet_id: str) -> dict:
        """Open the spreadsheet and return {'title': str, 'sheet_count': int}."""

    def drive_available(self) -> bool:
        """Return True when drive-level access is active for this session."""


def build_client(
    *,
    service_account_file: Optional[str] = None,
    service_account_json: Optional[Mapping[str, Any]] = None,
    scopes: Optional[Iterable[str]] = None,
    enable_drive: bool = False,
    retries: int = 2,
    validate: bool = True,
) -> SheetsSession:
    """Create an authenticated Sheets session using a service account.

    Defaults request spreadsheet scopes; include drive scope when enable_drive is True.
    Skip eager network validation when validate is False.
    """

Dependencies { .dependencies }

pygsheets { .dependency }

Provides authenticated access to Google Sheets and Drive APIs.