# gspread-models
[](https://codeclimate.com/github/s2t2/gspread-models-py/maintainability)  [](https://opensource.org/licenses/MIT)
The [`gspread-models`](https://github.com/s2t2/gspread-models-py) 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:
```sh
pip install gspread_models
```
## Quick Start
### Setup
**Step 1:** Bind the base model to your Google Sheets document and your credentials (see [Authentication](./docs/authentication.md) for more details):
```py
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:
```python
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](./queries.md), to read and write data to the sheet.
Writing / appending records to the sheet:
```py
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:
```py
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:
```py
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:
+ [Query Interface](./docs/queries.md)
+ [Authentication](./docs/authentication.md)
+ [Project File Organization](./docs/organization.md)
+ [Pandas Support](./docs/pandas_support.md)
## Examples
Here are some examples that demonstrate the usage of `gspread-models` within a variety of contexts:
+ [Demo Notebook](./docs/notebooks/demo_v1_0_7.ipynb)
+ [Flask Sheets Web Application Template](https://github.com/prof-rossetti/flask-sheets-template-2024)
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:
+ [Contributor's Guide](./docs/CONTRIBUTING.md)
+ [Google Cloud Setup Guide](./docs/setup/google-cloud.md)
+ [Google Sheets Setup Guide](./docs/setup/google-sheets.md)
+ [GitHub Actions Setup Guide](./docs/setup/github-actions.md)
## Acknowlegements
This package is built on top of the awesome [`gspread`](https://github.com/burnash/gspread) package.
## [License](/LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/s2t2/gspread-models-py",
"name": "gspread-models",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "google sheets gspread models orm spreadsheet google-sheets google-sheets-api gspread-models gspread_models",
"author": "Michael Rossetti",
"author_email": "datacreativellc@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/71/13/60e291cdcad8d78d99838f5993a571fd5540f64f9a8b7d2b10cd8211da86/gspread_models-1.0.7.tar.gz",
"platform": null,
"description": "# gspread-models\n\n[](https://codeclimate.com/github/s2t2/gspread-models-py/maintainability)  [](https://opensource.org/licenses/MIT)\n\n\nThe [`gspread-models`](https://github.com/s2t2/gspread-models-py) 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.\n\nKey Features:\n\n + **Read and Write Data:** Seamlessly read and write data to and from Google Sheets.\n + **Easy Setup:** Minimal schema requirements make it simple to get started.\n + **Intuitive Query Interface:** Familiar object-oriented query methods inspired by ActiveRecord (Ruby) and SQLAlchemy (Python).\n + **Auto-incrementing ID**: Automatically manages a primary key \"id\" column.\n + **Timestamps**: Automatically manages a \"created_at\" timestamp column.\n + **Datetime Handling**: Converts datetime columns to Python datetime objects for easier manipulation.\n + **Flexible Migrations**: Easily update the schema by modifying your Google Sheet and updating the corresponding list of columns.\n\n## Installation\n\nInstall the package from PyPI:\n\n```sh\npip install gspread_models\n```\n\n## Quick Start\n\n### Setup\n\n**Step 1:** Bind the base model to your Google Sheets document and your credentials (see [Authentication](./docs/authentication.md) for more details):\n\n```py\nfrom gspread_models.base import BaseModel\n\nBaseModel.bind(\n document_id=\"your-document-id\",\n credentials_filepath=\"/path/to/google-credentials.json\"\n)\n```\n\n**Step 2:** Define your own light-weight class that inherits from the base model:\n\n```python\nclass Book(BaseModel):\n\n SHEET_NAME = \"books\"\n\n COLUMNS = [\"title\", \"author\", \"year\"]\n```\n\nWhen defining your class, specify a `SHEET_NAME` as well as a list of sheet-specific `COLUMNS`.\n\n**Step 3:** Setup a corresponding sheet for this model.\n\nTo support the example above, create a sheet called \"books\", and specify an initial row of column headers: \"id\", \"title\", \"author\", \"year\", and \"created_at\".\n\n> 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\").\n\n### Usage\n\nOnce you have your model class setup, you can utilize the [Query Interface](./queries.md), to read and write data to the sheet.\n\nWriting / appending records to the sheet:\n\n```py\nBook.create_all([\n {\"title\": \"To Kill a Mockingbird\", \"author\": \"Harper Lee\", \"year\": 1960},\n {\"title\": \"1984\", \"author\": \"George Orwell\", \"year\": 1949},\n {\"title\": \"The Great Gatsby\", \"author\": \"F. Scott Fitzgerald\", \"year\": 1925},\n {\"title\": \"The Catcher in the Rye\", \"author\": \"J.D. Salinger\", \"year\": 1951},\n {\"title\": \"Pride and Prejudice\", \"author\": \"Jane Austen\", \"year\": 1813},\n])\n```\n\nFetching all records from the sheet:\n\n```py\nbooks = Book.all()\n\nfor book in books:\n print(book.id, \"|\", book.title, \"|\", book.author)\n\n#> 1 | To Kill a Mockingbird | Harper Lee\n#> 2 | 1984 | George Orwell\n#> 3 | The Great Gatsby | F. Scott Fitzgerald\n#> 4 | The Catcher in the Rye | J.D. Salinger\n#> 5 | Pride and Prejudice | Jane Austen\n```\n\nIt is easy to create a pandas DataFrame from the returned objects by converting each to a dictionary:\n\n```py\nfrom pandas import DataFrame\n\nbooks_df = DataFrame([dict(book) for book in books])\nbooks_df.head()\n\n#> id title author year created_at\n#> 1 To Kill a Mockingbird Harper Lee 1960 2024-05-22 21:36:25.582605+00:00\n#> 2 1984 George Orwell 1949 2024-05-22 21:36:25.582738+00:00\n#> 3 The Great Gatsby F. Scott Fitzgerald 1925 2024-05-22 21:36:25.582778+00:00\n#> 4 The Catcher in the Rye J.D. Salinger 1951 2024-05-22 21:36:25.582813+00:00\n#> 5 Pride and Prejudice Jane Austen 1813 2024-05-22 21:36:25.582846+00:00\n```\n\nFor more details, see the usage documentation below:\n\n + [Query Interface](./docs/queries.md)\n + [Authentication](./docs/authentication.md)\n + [Project File Organization](./docs/organization.md)\n + [Pandas Support](./docs/pandas_support.md)\n\n## Examples\n\nHere are some examples that demonstrate the usage of `gspread-models` within a variety of contexts:\n\n + [Demo Notebook](./docs/notebooks/demo_v1_0_7.ipynb)\n + [Flask Sheets Web Application Template](https://github.com/prof-rossetti/flask-sheets-template-2024)\n\nIf 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.\n\n## Contributing\n\nContributions welcome! Here are some reference guides to help you get started as a contributor or maintainer of this package:\n\n + [Contributor's Guide](./docs/CONTRIBUTING.md)\n + [Google Cloud Setup Guide](./docs/setup/google-cloud.md)\n + [Google Sheets Setup Guide](./docs/setup/google-sheets.md)\n + [GitHub Actions Setup Guide](./docs/setup/github-actions.md)\n\n## Acknowlegements\n\nThis package is built on top of the awesome [`gspread`](https://github.com/burnash/gspread) package.\n\n## [License](/LICENSE)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An Object Relational Mapper (ORM) for the Google Sheets API. 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. Offers a fast and flexible way to get up and running with a Google Sheets database, for rapid prototyping and development in Python.",
"version": "1.0.7",
"project_urls": {
"Homepage": "https://github.com/s2t2/gspread-models-py"
},
"split_keywords": [
"google",
"sheets",
"gspread",
"models",
"orm",
"spreadsheet",
"google-sheets",
"google-sheets-api",
"gspread-models",
"gspread_models"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9d768463ba4d56a77111524a75831373df5f506832528bc18b157c2463d56b12",
"md5": "87e64899f1b338dad170855446c1432e",
"sha256": "e352192502e3442d8b8838548fa0fa7d4cf7af6ee02f9f8c07062cd569546628"
},
"downloads": -1,
"filename": "gspread_models-1.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87e64899f1b338dad170855446c1432e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10359,
"upload_time": "2024-05-28T21:38:02",
"upload_time_iso_8601": "2024-05-28T21:38:02.011381Z",
"url": "https://files.pythonhosted.org/packages/9d/76/8463ba4d56a77111524a75831373df5f506832528bc18b157c2463d56b12/gspread_models-1.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "711360e291cdcad8d78d99838f5993a571fd5540f64f9a8b7d2b10cd8211da86",
"md5": "5aaf060c4cbdb61c4e910a9a23df4444",
"sha256": "76785c392cb67bfa734d7ff7ad6ffbc5133c20bf387645887a6693d612c3fcf3"
},
"downloads": -1,
"filename": "gspread_models-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "5aaf060c4cbdb61c4e910a9a23df4444",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11136,
"upload_time": "2024-05-28T21:38:03",
"upload_time_iso_8601": "2024-05-28T21:38:03.885810Z",
"url": "https://files.pythonhosted.org/packages/71/13/60e291cdcad8d78d99838f5993a571fd5540f64f9a8b7d2b10cd8211da86/gspread_models-1.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-28 21:38:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "s2t2",
"github_project": "gspread-models-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "gspread-models"
}
JSON
