SheetAlchemy Documentation

SheetAlchemy is a Python library that provides an Object-Relational Mapping (ORM) interface for Google Sheets. It allows developers to interact with Google Sheets data using Python objects and Django-like query syntax.

Features

Model-Based Approach: Define Python classes that represent Google Sheets tabs
Rich Field Types: Support for String, Integer, Date, Boolean, Decimal, List, and Custom fields
Django-Style Queries: Familiar filtering and querying with field lookups (__lt, __gt, __ct, etc.)
Data Validation: Built-in type validation and error handling
Load Policies: Configure eager (INIT) or lazy (LAZY) data loading
Data Transformation: Automatic cleaning of common spreadsheet issues
Authentication Management: Seamless Google Sheets API authentication

Quick Start

Installation

pip install sheetalchemy

Basic Usage

from sheetalchemy import Model, StringField, IntegerField, authenticate

# Authenticate with Google Sheets
authenticate(key_path="/path/to/service-account-key.json")

# Define your model
class Users(Model):
    name = StringField(name="Name")
    age = IntegerField(name="Age")

    class Meta:
        sheet_name = "My Google Sheet"
        tab_name = "Users"
        header_index = 1

# Query your data
users = Users.manager.filter(age__gt=25)
for user in users:
    print(f"{user.name}: {user.age}")

Contents

User Guide