# gspread-models-py
Model based ORM interface into Google Sheets, using the `gspread` package.
## Installation
Install this package from PyPI:
```sh
pip install gspread_models
```
## Setup
Follow the [Google Cloud Setup Guide](/admin/GOOGLE_CLOUD.md) to setup a Google Cloud project with a service account access to the Google Sheets API, obtain a service account credentials JSON file.
Follow the [Google Sheets Setup Guide](/admin/GOOGLE_SHEETS.md) to setup a Google Sheet document and share editor access with your service account.
## Usage Example
### Sheet Setup
To setup this example, create a sheet called "products", and populate the first row with the following column headers (including metadata columns):
+ `id`
+ `name`
+ `description`
+ `price`
+ `url`
+ `created_at`
The column names and order must match the `COLUMNS` defined in the model class (see below). The `id` column should be first, and the timestamps (`created_at`) should be last.
### Model Class Definition
Define your own light-weight class that inherits from the base model:
```python
from gspread_models.service import SpreadsheetService
from gspread_models.base import BaseModel
# bind the models to a specific document and set of credentials:
BaseModel.service = SpreadsheetService(
document_id="your-document-id",
credentials_filepath="/path/to/google-credentials.json"
)
# define your custom model class, which inherits from BaseModel:
class Product(BaseModel):
# specify the name of the sheet to use for this model class:
SHEET_NAME = "products"
# specify the model-specific column names:
COLUMNS = ["name", "description", "price", "url"]
```
In addition to the model-specific `COLUMNS` list, the base model will manage **metadata columns**, including:
+ an auto-incrementing integer (`id`), which acts as the record's unique identifier
+ auto-updating timestamps (`created_at`)
### Query Interface
The base model provides an intuitive query interface.
#### Find All Records
Find all records from the sheet:
```py
Product.all()
```
#### Find Record
Find a record given its unique identifier:
```py
Product.find(1)
```
#### Filtering Records
Filter records based on class-specific attribute values (returns records that match ALL criteria):
```py
Product.where(name="Strawberries")
Product.where(name="Strawberries", price=1000)
```
#### Creating Records
If the model class defines `SEEDS` as a list of dictionaries (see [`product.py`](/test/models/product.py) example), you can populate the sheet with these initial values:
```py
Product.seed()
```
Creating and persisting new records:
```py
Product.create(dict(name="Blueberries", price=3.99, description="organic blues"))
```
```py
Product.create_all([{"name":"Product X"}, {"name":"Product Y"}])
```
#### Destroying Records
Clear the sheet by removing all records:
```py
Product.destroy_all()
```
## [Contributing](/.github/CONTRIBUTING.md)
## [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",
"author": "Michael Rossetti",
"author_email": "datacreativellc@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a9/45/e27d39d6198202668e0f24d2e59dea64bb12fd7fc34a2a00f8d7f2c0ff2c/gspread_models-1.0.3.tar.gz",
"platform": null,
"description": "# gspread-models-py\n\nModel based ORM interface into Google Sheets, using the `gspread` package.\n\n## Installation\n\nInstall this package from PyPI:\n\n```sh\npip install gspread_models\n```\n\n## Setup\n\nFollow the [Google Cloud Setup Guide](/admin/GOOGLE_CLOUD.md) to setup a Google Cloud project with a service account access to the Google Sheets API, obtain a service account credentials JSON file.\n\nFollow the [Google Sheets Setup Guide](/admin/GOOGLE_SHEETS.md) to setup a Google Sheet document and share editor access with your service account.\n\n## Usage Example\n\n### Sheet Setup\n\nTo setup this example, create a sheet called \"products\", and populate the first row with the following column headers (including metadata columns):\n\n + `id`\n + `name`\n + `description`\n + `price`\n + `url`\n + `created_at`\n\nThe column names and order must match the `COLUMNS` defined in the model class (see below). The `id` column should be first, and the timestamps (`created_at`) should be last.\n\n### Model Class Definition\n\nDefine your own light-weight class that inherits from the base model:\n\n```python\nfrom gspread_models.service import SpreadsheetService\nfrom gspread_models.base import BaseModel\n\n# bind the models to a specific document and set of credentials:\nBaseModel.service = SpreadsheetService(\n document_id=\"your-document-id\",\n credentials_filepath=\"/path/to/google-credentials.json\"\n)\n\n# define your custom model class, which inherits from BaseModel:\nclass Product(BaseModel):\n\n # specify the name of the sheet to use for this model class:\n SHEET_NAME = \"products\"\n\n # specify the model-specific column names:\n COLUMNS = [\"name\", \"description\", \"price\", \"url\"]\n\n```\n\nIn addition to the model-specific `COLUMNS` list, the base model will manage **metadata columns**, including:\n + an auto-incrementing integer (`id`), which acts as the record's unique identifier\n + auto-updating timestamps (`created_at`)\n\n### Query Interface\n\nThe base model provides an intuitive query interface.\n\n#### Find All Records\n\nFind all records from the sheet:\n\n```py\nProduct.all()\n```\n\n#### Find Record\n\nFind a record given its unique identifier:\n\n```py\nProduct.find(1)\n```\n\n#### Filtering Records\n\nFilter records based on class-specific attribute values (returns records that match ALL criteria):\n\n```py\nProduct.where(name=\"Strawberries\")\n\nProduct.where(name=\"Strawberries\", price=1000)\n```\n\n\n\n\n#### Creating Records\n\nIf the model class defines `SEEDS` as a list of dictionaries (see [`product.py`](/test/models/product.py) example), you can populate the sheet with these initial values:\n\n```py\nProduct.seed()\n```\n\nCreating and persisting new records:\n\n```py\nProduct.create(dict(name=\"Blueberries\", price=3.99, description=\"organic blues\"))\n```\n\n```py\nProduct.create_all([{\"name\":\"Product X\"}, {\"name\":\"Product Y\"}])\n```\n\n\n#### Destroying Records\n\nClear the sheet by removing all records:\n\n```py\nProduct.destroy_all()\n```\n\n## [Contributing](/.github/CONTRIBUTING.md)\n\n## [License](/LICENSE)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model based ORM interface into Google Sheets, using the gspread package.",
"version": "1.0.3",
"project_urls": {
"Homepage": "https://github.com/s2t2/gspread-models-py"
},
"split_keywords": [
"google",
"sheets",
"gspread",
"models",
"orm",
"spreadsheet"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "321ee27b78253d95d6e015398f0752fafed8a948c292461059f016d26319bd40",
"md5": "d8207808842023bcde63e362bbe66244",
"sha256": "23e7e07871285a323df1e271a317cbd3ff961c89d446109426991fd80b21601b"
},
"downloads": -1,
"filename": "gspread_models-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8207808842023bcde63e362bbe66244",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7673,
"upload_time": "2024-04-19T20:04:33",
"upload_time_iso_8601": "2024-04-19T20:04:33.049495Z",
"url": "https://files.pythonhosted.org/packages/32/1e/e27b78253d95d6e015398f0752fafed8a948c292461059f016d26319bd40/gspread_models-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a945e27d39d6198202668e0f24d2e59dea64bb12fd7fc34a2a00f8d7f2c0ff2c",
"md5": "9b51547302d326500a86497d3e840754",
"sha256": "c2d32c5cc8d828a09973f9f79b2a9f275595d0b557b7ff9aee875d21151341f9"
},
"downloads": -1,
"filename": "gspread_models-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "9b51547302d326500a86497d3e840754",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6852,
"upload_time": "2024-04-19T20:04:34",
"upload_time_iso_8601": "2024-04-19T20:04:34.628135Z",
"url": "https://files.pythonhosted.org/packages/a9/45/e27d39d6198202668e0f24d2e59dea64bb12fd7fc34a2a00f8d7f2c0ff2c/gspread_models-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-19 20:04:34",
"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": [
{
"name": "python-dotenv",
"specs": []
},
{
"name": "gspread",
"specs": [
[
">=",
"6.0.2"
]
]
},
{
"name": "pytest",
"specs": []
},
{
"name": "pypandoc",
"specs": []
}
],
"lcname": "gspread-models"
}
JSON
