or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdclient-operations.mddata-access.mdformatting.mdindex.mdspreadsheet-management.mdutilities.mdworksheet-structure.md
tile.json

tessl/pypi-gspread

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/gspread@6.2.x

To install, run

npx @tessl/cli install tessl/pypi-gspread@6.2.0

index.mddocs/

gspread

Google Spreadsheets Python API - A comprehensive library providing programmatic access to Google Sheets through a clean, intuitive interface. Supports authentication via service accounts, OAuth2, and API keys, enabling robust integration with Google's spreadsheet platform for data manipulation, formatting, batch operations, and access control.

Package Information

  • Package Name: gspread
  • Language: Python
  • Installation: pip install gspread
  • Dependencies: google-auth>=1.12.0, google-auth-oauthlib>=0.4.1

Core Imports

import gspread

For authentication functions:

from gspread import service_account, oauth, authorize, api_key

For core classes:

from gspread import Client, Spreadsheet, Worksheet, Cell

Basic Usage

import gspread

# Service account authentication
gc = gspread.service_account()

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

# Read all values
values = sheet.get_all_values()
print(values)

# Update a single cell
sheet.update('B1', 'Hello World!')

# Update multiple cells
sheet.update([
    ['Name', 'Age', 'City'],
    ['Alice', 25, 'New York'],
    ['Bob', 30, 'San Francisco']
], 'A1')

# Get cell value
cell_value = sheet.cell(1, 1).value
print(cell_value)

# Find cells
cell = sheet.find("Alice")
print(f"Found at row {cell.row}, col {cell.col}")

# Batch operations for performance
sheet.batch_update([
    {'range': 'A1:C1', 'values': [['Name', 'Age', 'City']]},
    {'range': 'A2:C3', 'values': [['Alice', 25, 'NY'], ['Bob', 30, 'SF']]}
])

Architecture

gspread follows a hierarchical object model:

  • Client: Main entry point for authentication and spreadsheet management
  • Spreadsheet: Container for worksheets with metadata and sharing capabilities
  • Worksheet: Individual sheet with data manipulation and formatting methods
  • Cell: Single cell representation with coordinate and value information

The library supports multiple authentication methods and provides both high-level convenience methods and low-level API access for advanced use cases.

Capabilities

Authentication

Multiple authentication methods including service accounts, OAuth2 flows, and API keys with support for both credential files and dictionary-based configuration.

def service_account(filename: str = None, scopes: List[str] = None, http_client: HTTPClient = None) -> Client: ...
def oauth(scopes: List[str] = None, flow: InstalledAppFlow = None, filename: str = "credentials.json", port: int = 0, host: str = "localhost") -> Client: ...
def authorize(credentials, http_client: HTTPClient = None) -> Client: ...
def api_key(api_key: str) -> Client: ...

Authentication

Client Operations

Main client functionality for spreadsheet management, file operations, permissions, and sharing.

class Client:
    def open(title: str) -> Spreadsheet: ...
    def open_by_key(key: str) -> Spreadsheet: ...
    def open_by_url(url: str) -> Spreadsheet: ...
    def create(title: str, folder_id: str = None) -> Spreadsheet: ...
    def copy(file_id: str, title: str = None, copy_permissions: bool = False) -> Spreadsheet: ...

Client Operations

Spreadsheet Management

Spreadsheet-level operations including worksheet management, metadata access, batch operations, and sharing controls.

class Spreadsheet:
    def add_worksheet(title: str, rows: int = 100, cols: int = 26, index: int = None) -> Worksheet: ...
    def batch_update(body: Dict) -> Dict: ...
    def share(value: str, perm_type: str = "user", role: str = "reader", notify: bool = True) -> Dict: ...
    def values_batch_get(ranges: List[str], major_dimension: str = "ROWS") -> Dict: ...

Spreadsheet Management

Data Access & Manipulation

Comprehensive worksheet data operations including reading, writing, updating, and batch processing of cell values and ranges.

class Worksheet:
    def get_all_values(value_render_option: str = "FORMATTED_VALUE") -> List[List]: ...
    def update(range_name: str = None, values: List[List] = None, value_input_option: str = "RAW") -> Dict: ...
    def batch_get(ranges: List[str], value_render_option: str = "FORMATTED_VALUE") -> List[List]: ...
    def find(query: str, in_row: int = None, in_column: int = None, case_sensitive: bool = True) -> Cell: ...

Data Access & Manipulation

Worksheet Structure

Worksheet structural modifications including adding/deleting rows and columns, resizing, freezing, and dimension grouping.

class Worksheet:
    def add_rows(rows: int) -> None: ...
    def add_cols(cols: int) -> None: ...
    def delete_rows(start_index: int, end_index: int = None) -> Dict: ...
    def resize(rows: int = None, cols: int = None) -> Dict: ...
    def freeze(rows: int = None, cols: int = None) -> Dict: ...

Worksheet Structure

Formatting & Display

Cell and range formatting including merge operations, text formatting, colors, number formats, and conditional formatting.

class Worksheet:
    def format(ranges: str, format: Dict) -> Dict: ...
    def merge_cells(name: str, merge_type: str = "MERGE_ALL") -> Dict: ...
    def update_tab_color(color: Dict) -> Dict: ...
    def hide_columns(start_index: int, end_index: int) -> Dict: ...

Formatting & Display

Utilities & Helpers

Coordinate conversion, range processing, data type conversion, and various utility functions for working with spreadsheet data.

def a1_to_rowcol(label: str) -> Tuple[int, int]: ...
def rowcol_to_a1(row: int, col: int) -> str: ...
def numericise(value: str, default_blank: str = "", ignore: List[str] = None) -> Union[str, int, float]: ...

Utilities & Helpers

Types

class Cell:
    def __init__(row: int, col: int, value: str = ""): ...
    @property
    def address -> str: ...
    @property
    def row -> int: ...
    @property
    def col -> int: ...
    @property
    def value -> str: ...

class ValueRange:
    def __init__(worksheet: Worksheet, name: str, values: List[List] = None): ...
    @property
    def values -> List[List]: ...
    def update(values: List[List] = None) -> Dict: ...
    def clear() -> Dict: ...

Exceptions

class GSpreadException(Exception): ...
class APIError(GSpreadException): ...
class SpreadsheetNotFound(GSpreadException): ...
class WorksheetNotFound(GSpreadException): ...
class IncorrectCellLabel(GSpreadException): ...
class NoValidUrlKeyFound(GSpreadException): ...