# SmartSpread
SmartSpread is a Python library that extends [gspread](https://gspread.readthedocs.io/) with advanced features for managing and manipulating Google Sheets. It offers a higher-level API for spreadsheet and tab operations, seamless integration with Pandas, and automation capabilities like background data syncing.
## Features
- **Spreadsheet Management**:
- Create and retrieve spreadsheets with ease.
- Grant access to collaborators programmatically.
- **Tab Operations**:
- Create, read, write, and update individual tabs.
- Support for multiple data formats: `DataFrame`, `list[dict]`, and `list[list]`.
- **Automation**:
- Background writing to Google Sheets at regular intervals.
- Efficient caching to minimize redundant API calls.
- **Pandas Integration**:
- Convert Google Sheets data to Pandas DataFrames and vice versa.
- Seamless handling of numeric, string, and date formats.
## Installation
Install the library using `pip`:
```bash
pip install smartspread
```
## Getting Started
### Authentication
- Set up a Google Cloud Project and enable the Google Sheets API.
- Create a service account and download the credentials JSON file.
- Share your spreadsheet with the service account email.
## Example Usage
### Initialize a Spreadsheet
```python
from smart_spread import SmartSpread
# Initialize SmartSpread with a Google Sheets ID and credentials file
spread = SmartSpread(
sheet_identifier="your-spreadsheet-id-or-name",
key_file="path/to/credentials.json"
)
```
### Work with Tabs
```python
# Get or create a tab
tab = spread.tab(tab_name="MyTab", data_format="DataFrame")
# Read data as a Pandas DataFrame
df = tab.read_data()
print(df)
# Update rows based on a column value
tab.update_row_by_column_pattern(
column="Name",
value="Alice",
updates={"Age": 30, "City": "New York"}
)
# Write updated data back to the tab
tab.write_data(overwrite_tab=True)
```
### Automate Background Writing
```python
# Start background writing every 15 seconds
tab.start_background_write(interval=15, overwrite_tab=True)
# Stop background writing
tab.stop_background_write()
```
## Documentation
Homepage: [SmartSpread GitHub](https://github.com/Redundando/smart_spread)
## License
This project is licensed under the MIT License. See the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "smartspread",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "google-sheets, gspread, pandas, spreadsheet, automation",
"author": null,
"author_email": "Arved Kl\u00f6hn <arved.kloehn@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/dd/d2/03b0ac667f9361aac38abec4764987dcdfd6d66f0668eb820c8b8141985f/smartspread-1.0.2.tar.gz",
"platform": null,
"description": "# SmartSpread\r\n\r\nSmartSpread is a Python library that extends [gspread](https://gspread.readthedocs.io/) with advanced features for managing and manipulating Google Sheets. It offers a higher-level API for spreadsheet and tab operations, seamless integration with Pandas, and automation capabilities like background data syncing.\r\n\r\n## Features\r\n\r\n- **Spreadsheet Management**:\r\n - Create and retrieve spreadsheets with ease.\r\n - Grant access to collaborators programmatically.\r\n\r\n- **Tab Operations**:\r\n - Create, read, write, and update individual tabs.\r\n - Support for multiple data formats: `DataFrame`, `list[dict]`, and `list[list]`.\r\n\r\n- **Automation**:\r\n - Background writing to Google Sheets at regular intervals.\r\n - Efficient caching to minimize redundant API calls.\r\n\r\n- **Pandas Integration**:\r\n - Convert Google Sheets data to Pandas DataFrames and vice versa.\r\n - Seamless handling of numeric, string, and date formats.\r\n\r\n## Installation\r\n\r\nInstall the library using `pip`:\r\n\r\n```bash\r\npip install smartspread\r\n```\r\n\r\n## Getting Started\r\n### Authentication\r\n- Set up a Google Cloud Project and enable the Google Sheets API.\r\n- Create a service account and download the credentials JSON file.\r\n- Share your spreadsheet with the service account email.\r\n## Example Usage\r\n### Initialize a Spreadsheet\r\n```python\r\nfrom smart_spread import SmartSpread\r\n\r\n# Initialize SmartSpread with a Google Sheets ID and credentials file\r\nspread = SmartSpread(\r\n sheet_identifier=\"your-spreadsheet-id-or-name\",\r\n key_file=\"path/to/credentials.json\"\r\n)\r\n```\r\n### Work with Tabs\r\n```python\r\n\r\n# Get or create a tab\r\ntab = spread.tab(tab_name=\"MyTab\", data_format=\"DataFrame\")\r\n\r\n# Read data as a Pandas DataFrame\r\ndf = tab.read_data()\r\nprint(df)\r\n\r\n# Update rows based on a column value\r\ntab.update_row_by_column_pattern(\r\n column=\"Name\",\r\n value=\"Alice\",\r\n updates={\"Age\": 30, \"City\": \"New York\"}\r\n)\r\n\r\n# Write updated data back to the tab\r\ntab.write_data(overwrite_tab=True)\r\n```\r\n### Automate Background Writing\r\n```python\r\n\r\n# Start background writing every 15 seconds\r\ntab.start_background_write(interval=15, overwrite_tab=True)\r\n\r\n# Stop background writing\r\ntab.stop_background_write()\r\n```\r\n## Documentation\r\nHomepage: [SmartSpread GitHub](https://github.com/Redundando/smart_spread)\r\n\r\n## License\r\nThis project is licensed under the MIT License. See the LICENSE file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library that extends gspread for enhanced spreadsheet manipulation.",
"version": "1.0.2",
"project_urls": {
"Documentation": "https://github.com/Redundando/smart_spread#readme",
"Homepage": "https://github.com/Redundando/smart_spread",
"Issues": "https://github.com/Redundando/smart_spread/issues",
"Repository": "https://github.com/Redundando/smart_spread"
},
"split_keywords": [
"google-sheets",
" gspread",
" pandas",
" spreadsheet",
" automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "737d61d19317aa631fb1d7b81c42126fe206b3f3a1026e1b8a6e42f35ac55495",
"md5": "ca28f7b76dac68962cfec820b6323819",
"sha256": "9a1e6b7ae3b861fd1787f447ae4ba20e12ff98d2473a3efd81b0a94d0b75d90d"
},
"downloads": -1,
"filename": "smartspread-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca28f7b76dac68962cfec820b6323819",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 11524,
"upload_time": "2025-01-13T17:57:38",
"upload_time_iso_8601": "2025-01-13T17:57:38.853694Z",
"url": "https://files.pythonhosted.org/packages/73/7d/61d19317aa631fb1d7b81c42126fe206b3f3a1026e1b8a6e42f35ac55495/smartspread-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ddd203b0ac667f9361aac38abec4764987dcdfd6d66f0668eb820c8b8141985f",
"md5": "cd05bb539c7efb29951c327f349082cf",
"sha256": "1fea40ddb486677fc442dd1174c1bbf4fbd8f41551c60764eda23ddaef1d520c"
},
"downloads": -1,
"filename": "smartspread-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "cd05bb539c7efb29951c327f349082cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11625,
"upload_time": "2025-01-13T17:57:41",
"upload_time_iso_8601": "2025-01-13T17:57:41.058265Z",
"url": "https://files.pythonhosted.org/packages/dd/d2/03b0ac667f9361aac38abec4764987dcdfd6d66f0668eb820c8b8141985f/smartspread-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-13 17:57:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Redundando",
"github_project": "smart_spread#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "smartspread"
}
JSON
