gspread-models
The gspread-models package is an Object Relational Mapper (ORM) for the Google Sheets API. It provides a straightforward and intuitive model-based query interface, making it easy to interact with Google Sheets as if it were more like a database. This package offers a fast and flexible way to get up and running with a Google Sheets database, for rapid prototyping and development in Python.
Key Features:
- Read and Write Data: Seamlessly read and write data to and from Google Sheets.
- Easy Setup: Minimal schema requirements make it simple to get started.
- Intuitive Query Interface: Familiar object-oriented query methods inspired by ActiveRecord (Ruby) and SQLAlchemy (Python).
- Auto-incrementing ID: Automatically manages a primary key "id" column.
- Timestamps: Automatically manages a "created_at" timestamp column.
- Datetime Handling: Converts datetime columns to Python datetime objects for easier manipulation.
- Flexible Migrations: Easily update the schema by modifying your Google Sheet and updating the corresponding list of columns.
Installation
Install the package from PyPI:
pip install gspread_models
Quick Start
Setup
Step 1: Bind the base model to your Google Sheets document and your credentials (see Authentication for more details):
from gspread_models.base import BaseModel
BaseModel.bind(
document_id="your-document-id",
credentials_filepath="/path/to/google-credentials.json"
)
Step 2: Define your own light-weight class that inherits from the base model:
class Book(BaseModel):
SHEET_NAME = "books"
COLUMNS = ["title", "author", "year"]
When defining your class, specify a SHEET_NAME as well as a list of sheet-specific COLUMNS.
Step 3: Setup a corresponding sheet for this model.
To support the example above, create a sheet called "books", and specify an initial row of column headers: "id", "title", "author", "year", and "created_at".
NOTE: In addition to the sheet-specific attributes ("title", "author", and "year"), the base model will manage metadata columns, including a unique identifier ("id") as well as a timestamp ("created_at").
Usage
Once you have your model class setup, you can utilize the Query Interface, to read and write data to the sheet.
Writing / appending records to the sheet:
Book.create_all([
{"title": "To Kill a Mockingbird", "author": "Harper Lee", "year": 1960},
{"title": "1984", "author": "George Orwell", "year": 1949},
{"title": "The Great Gatsby", "author": "F. Scott Fitzgerald", "year": 1925},
{"title": "The Catcher in the Rye", "author": "J.D. Salinger", "year": 1951},
{"title": "Pride and Prejudice", "author": "Jane Austen", "year": 1813},
])
Fetching all records from the sheet:
books = Book.all()
for book in books:
print(book.id, "|", book.title, "|", book.author)
#> 1 | To Kill a Mockingbird | Harper Lee
#> 2 | 1984 | George Orwell
#> 3 | The Great Gatsby | F. Scott Fitzgerald
#> 4 | The Catcher in the Rye | J.D. Salinger
#> 5 | Pride and Prejudice | Jane Austen
It is easy to create a pandas DataFrame from the returned objects by converting each to a dictionary:
from pandas import DataFrame
books_df = DataFrame([dict(book) for book in books])
books_df.head()
#> id title author year created_at
#> 1 To Kill a Mockingbird Harper Lee 1960 2024-05-22 21:36:25.582605+00:00
#> 2 1984 George Orwell 1949 2024-05-22 21:36:25.582738+00:00
#> 3 The Great Gatsby F. Scott Fitzgerald 1925 2024-05-22 21:36:25.582778+00:00
#> 4 The Catcher in the Rye J.D. Salinger 1951 2024-05-22 21:36:25.582813+00:00
#> 5 Pride and Prejudice Jane Austen 1813 2024-05-22 21:36:25.582846+00:00
For more details, see the usage documentation below:
Examples
Here are some examples that demonstrate the usage of gspread-models within a variety of contexts:
If you use the gspread-models package, you are encouraged to add your project to this list, by submitting a pull request or opening an issue.
Contributing
Contributions welcome! Here are some reference guides to help you get started as a contributor or maintainer of this package:
Acknowlegements
This package is built on top of the awesome gspread package.
License
Metadata
Release files for gspread-models 1.0.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gspread_models-1.0.7.tar.gz | 11.1 kB | Without provenance | Details for gspread_models-1.0.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gspread_models-1.0.7-py3-none-any.whl | Python 3 | none | any | Details for gspread_models-1.0.7-py3-none-any.whl |
Total release size: 21.5 kB
Release files / gspread_models-1.0.7.tar.gz
| Download URL | gspread_models-1.0.7.tar.gz |
|---|---|
| Size | 11.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
76785c392cb67bfa734d7ff7ad6ffbc5133c20bf387645887a6693d612c3fcf3
|
|
BLAKE2b-256 checksum How to use checksums |
711360e291cdcad8d78d99838f5993a571fd5540f64f9a8b7d2b10cd8211da86
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.9.19
|
Release files / gspread_models-1.0.7-py3-none-any.whl
| Download URL | gspread_models-1.0.7-py3-none-any.whl |
|---|---|
| Size | 10.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e352192502e3442d8b8838548fa0fa7d4cf7af6ee02f9f8c07062cd569546628
|
|
BLAKE2b-256 checksum How to use checksums |
9d768463ba4d56a77111524a75831373df5f506832528bc18b157c2463d56b12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.9.19
|
Security for gspread-models 1.0.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.