tessl/pypi-gspread

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

gspread

Name: tessl/pypi-gspread
Author: tessl

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): ...