tessl/pypi-gspread

Google Spreadsheets Python API - Simple interface for working with Google Sheets

Overview

Eval results

Files

Client Operations

Name: tessl/pypi-gspread
Author: tessl

The Client class provides the main interface for managing spreadsheets, handling file operations, permissions, and sharing.

Capabilities

Opening Spreadsheets

Access existing spreadsheets by title, key, or URL.

class Client:
    def open(title: str) -> Spreadsheet:
        """
        Open spreadsheet by title.

        Parameters:
        - title (str): Exact spreadsheet title.

        Returns:
        Spreadsheet: Spreadsheet instance.

        Raises:
        SpreadsheetNotFound: If no spreadsheet with the given title is found.
        """

    def open_by_key(key: str) -> Spreadsheet:
        """
        Open spreadsheet by key (ID).

        Parameters:
        - key (str): Spreadsheet ID from URL.

        Returns:
        Spreadsheet: Spreadsheet instance.

        Raises:
        SpreadsheetNotFound: If spreadsheet with the given key is not found or not accessible.
        """

    def open_by_url(url: str) -> Spreadsheet:
        """
        Open spreadsheet by URL.

        Parameters:
        - url (str): Full Google Sheets URL.

        Returns:
        Spreadsheet: Spreadsheet instance.

        Raises:
        NoValidUrlKeyFound: If URL doesn't contain a valid spreadsheet ID.
        SpreadsheetNotFound: If spreadsheet is not found or not accessible.
        """

    def openall(title: str = None) -> List[Spreadsheet]:
        """
        Open all accessible spreadsheets, optionally filtered by title.

        Parameters:
        - title (str, optional): Filter by exact title. If None, returns all accessible spreadsheets.

        Returns:
        List[Spreadsheet]: List of spreadsheet instances.
        """

Usage examples:

# Open by exact title
sheet = gc.open("My Spreadsheet")

# Open by ID (from URL: https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit)
sheet = gc.open_by_key("1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms")

# Open by full URL
sheet = gc.open_by_url("https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit#gid=0")

# Get all accessible spreadsheets
all_sheets = gc.openall()

# Get all spreadsheets with specific title
matching_sheets = gc.openall("My Spreadsheet")

Creating and Managing Spreadsheets

Create new spreadsheets, copy existing ones, and delete spreadsheets.

class Client:
    def create(title: str, folder_id: str = None) -> Spreadsheet:
        """
        Create new spreadsheet.

        Parameters:
        - title (str): Title for the new spreadsheet.
        - folder_id (str, optional): Google Drive folder ID to create spreadsheet in.

        Returns:
        Spreadsheet: Newly created spreadsheet instance.
        """

    def copy(file_id: str, title: str = None, copy_permissions: bool = False) -> Spreadsheet:
        """
        Copy existing spreadsheet.

        Parameters:
        - file_id (str): ID of spreadsheet to copy.
        - title (str, optional): Title for the copy. If None, uses "Copy of [original title]".
        - copy_permissions (bool): Whether to copy sharing permissions. Default: False.

        Returns:
        Spreadsheet: Copied spreadsheet instance.
        """

    def del_spreadsheet(file_id: str) -> None:
        """
        Delete spreadsheet.

        Parameters:
        - file_id (str): ID of spreadsheet to delete.

        Returns:
        None
        """

Usage examples:

# Create new spreadsheet
new_sheet = gc.create("My New Spreadsheet")

# Create in specific folder
folder_sheet = gc.create("Project Data", folder_id="1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms")

# Copy spreadsheet
copied_sheet = gc.copy("original_spreadsheet_id", title="Copy of Original")

# Copy with permissions
copied_with_perms = gc.copy("original_spreadsheet_id", copy_permissions=True)

# Delete spreadsheet
gc.del_spreadsheet("spreadsheet_id_to_delete")

Permission Management

Manage spreadsheet access permissions and sharing.

class Client:
    def insert_permission(file_id: str, value: str, perm_type: str = "user", role: str = "reader",
                         notify: bool = True, email_message: str = None, with_link: bool = False) -> Dict:
        """
        Add permission to spreadsheet.

        Parameters:
        - file_id (str): Spreadsheet ID.
        - value (str): Email address, domain, or "anyone".
        - perm_type (str): Permission type ("user", "group", "domain", "anyone"). Default: "user".
        - role (str): Access role ("owner", "writer", "reader"). Default: "reader".
        - notify (bool): Whether to send notification email. Default: True.
        - email_message (str, optional): Custom message for notification email.
        - with_link (bool): Whether to grant access via link. Default: False.

        Returns:
        Dict: Permission details.
        """

    def list_permissions(file_id: str) -> List[Dict]:
        """
        List all permissions for spreadsheet.

        Parameters:
        - file_id (str): Spreadsheet ID.

        Returns:
        List[Dict]: List of permission details.
        """

    def remove_permission(file_id: str, permission_id: str) -> None:
        """
        Remove permission from spreadsheet.

        Parameters:
        - file_id (str): Spreadsheet ID.
        - permission_id (str): Permission ID to remove.

        Returns:
        None
        """

Usage examples:

# Grant read access to user
gc.insert_permission("spreadsheet_id", "user@example.com", role="reader")

# Grant write access without notification
gc.insert_permission("spreadsheet_id", "editor@example.com", role="writer", notify=False)

# Grant access to anyone with link
gc.insert_permission("spreadsheet_id", "anyone", perm_type="anyone", role="reader", with_link=True)

# List all permissions
permissions = gc.list_permissions("spreadsheet_id")
for perm in permissions:
    print(f"Email: {perm.get('emailAddress')}, Role: {perm.get('role')}")

# Remove permission
gc.remove_permission("spreadsheet_id", "permission_id")

Import and Export Operations

Import CSV data and export spreadsheets in various formats.

class Client:
    def import_csv(file_id: str, data: str) -> None:
        """
        Import CSV data into spreadsheet.

        Parameters:
        - file_id (str): Spreadsheet ID.
        - data (str): CSV data as string.

        Returns:
        None
        """

    def export(file_id: str, format: str = "pdf") -> bytes:
        """
        Export spreadsheet in specified format.

        Parameters:
        - file_id (str): Spreadsheet ID.
        - format (str): Export format ("pdf", "xlsx", "ods", "csv", "tsv", "zip"). Default: "pdf".

        Returns:
        bytes: Exported file content.
        """

Usage examples:

# Import CSV data
csv_data = "Name,Age,City\nAlice,25,New York\nBob,30,San Francisco"
gc.import_csv("spreadsheet_id", csv_data)

# Export as PDF
pdf_content = gc.export("spreadsheet_id", format="pdf")
with open("spreadsheet.pdf", "wb") as f:
    f.write(pdf_content)

# Export as Excel
xlsx_content = gc.export("spreadsheet_id", format="xlsx")
with open("spreadsheet.xlsx", "wb") as f:
    f.write(xlsx_content)

Timeout Configuration

Configure HTTP request timeouts for all API calls.

class Client:
    def set_timeout(timeout: Optional[Union[float, Tuple[float, float]]] = None) -> None:
        """
        Set HTTP request timeout.

        Parameters:
        - timeout (Optional[Union[float, Tuple[float, float]]]): Timeout in seconds as float, or (connect_timeout, read_timeout) tuple. None restores default.

        Returns:
        None
        """

Client Properties

class Client:
    @property
    def auth:
        """Authentication credentials object."""

    @property
    def http_client -> HTTPClient:
        """HTTP client instance used for API requests."""

Install with Tessl CLI