# pysheetson
A tiny Python client for the Sheetson API - Transform any Google Sheet into a REST API.
## What is Sheetson?
Sheetson allows you to use Google Sheets as a database for your applications. Every Google Sheet becomes a database, and each tab becomes a table. No complex setup required!
## Features
- ✅ **CRUD Operations**: Create, Read, Update, Delete rows
- ✅ **Advanced Filtering**: Use `where` clauses with operators ($gte, $lte, $in, etc.)
- ✅ **Sorting & Pagination**: Order results and paginate through large datasets
- ✅ **Batch Operations**: Perform multiple operations efficiently
- ✅ **DataFrame Support**: Direct integration with pandas DataFrames
- ✅ **Type Hints**: Full typing support for better development experience
- ✅ **Error Handling**: Comprehensive error handling with custom exceptions
## Quick Start
### 1. Setup Your Google Sheet
1. Create a Google Sheet with headers in the first row
2. Share it with `google@sheetson.com` as an Editor
3. Get your API key from [Sheetson Dashboard](https://sheetson.com/dashboard)
### 2. Install pysheetson
```bash
pip install requests
# Optional: for DataFrame support
pip install pandas
```
### 3. Start Coding
```python
from pysheetson import SheetsonClient
# Initialize client
client = SheetsonClient(
api_key="your_api_key_here",
spreadsheet_id="your_spreadsheet_id_here"
)
# Basic operations
cities = client.list_rows("Cities", limit=10)
new_city = client.create_row("Cities", {"name": "Paris", "country": "France"})
client.update_row("Cities", 2, {"population": "2161000"})
client.delete_row("Cities", 3)
# Advanced filtering
large_cities = client.search_rows("Cities",
where={"population": {"$gte": "1000000"}},
order_by="population",
desc=True
)
# Batch operations
operations = [
{"operation": "create", "data": {"name": "Tokyo", "country": "Japan"}},
{"operation": "update", "row_number": 2, "data": {"population": "37400068"}},
{"operation": "delete", "row_number": 5}
]
result = client.batch_operations("Cities", operations)
# DataFrame integration (requires pandas)
import pandas as pd
df = pd.DataFrame([
{"name": "London", "country": "UK"},
{"name": "Berlin", "country": "Germany"}
])
client.create_rows_from_dataframe("Cities", df)
```
## Documentation
- 📖 [Full Documentation](https://mr-kam.github.io/pysheetson/)
- 🚀 [Github repo](https://github.com/Mr-KAM/pysheetson/)
- 💻 [Example Scripts](https://github.com/Mr-KAM/pysheetson/tree/master/examples)
- 🌐 [Sheetson API Docs](https://docs.sheetson.com/)
## Examples
Check out the [examples/](examples/) directory for more usage patterns:
- `quickstart.py` - Basic operations
- `batch_and_dataframe_example.py` - Advanced features
## Error Handling
```python
from pysheetson import SheetsonError
try:
result = client.create_row("Cities", {"name": "Test"})
except SheetsonError as e:
print(f"API Error: {e}")
```
## Development
```bash
# Clone the repository
git clone https://github.com/Mr-KAM/pysheetson.git
cd pysheetson
# Install in development mode
pip install -e .
# Run tests
python -m pytest tests/
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Links
- [Sheetson Official Website](https://sheetson.com/)
- [Sheetson API Documentation](https://docs.sheetson.com/)
- [GitHub Repository](https://github.com/Mr-KAM/pysheetson)
Raw data
{
"_id": null,
"home_page": null,
"name": "pysheetson",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "google-sheets, api, client, sheetson",
"author": "KAMBOU ANICET CYRILLE",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d8/08/3e6ead6ded2d189dde57ad45700be4173f869e36923e5d651bc4d9a95fea/pysheetson-0.1.1.tar.gz",
"platform": null,
"description": "# pysheetson\r\n\r\nA tiny Python client for the Sheetson API - Transform any Google Sheet into a REST API.\r\n\r\n## What is Sheetson?\r\n\r\nSheetson allows you to use Google Sheets as a database for your applications. Every Google Sheet becomes a database, and each tab becomes a table. No complex setup required!\r\n\r\n## Features\r\n\r\n- \u2705 **CRUD Operations**: Create, Read, Update, Delete rows\r\n- \u2705 **Advanced Filtering**: Use `where` clauses with operators ($gte, $lte, $in, etc.)\r\n- \u2705 **Sorting & Pagination**: Order results and paginate through large datasets\r\n- \u2705 **Batch Operations**: Perform multiple operations efficiently\r\n- \u2705 **DataFrame Support**: Direct integration with pandas DataFrames\r\n- \u2705 **Type Hints**: Full typing support for better development experience\r\n- \u2705 **Error Handling**: Comprehensive error handling with custom exceptions\r\n\r\n## Quick Start\r\n\r\n### 1. Setup Your Google Sheet\r\n\r\n1. Create a Google Sheet with headers in the first row\r\n2. Share it with `google@sheetson.com` as an Editor\r\n3. Get your API key from [Sheetson Dashboard](https://sheetson.com/dashboard)\r\n\r\n### 2. Install pysheetson\r\n\r\n```bash\r\npip install requests\r\n# Optional: for DataFrame support \r\npip install pandas\r\n```\r\n\r\n### 3. Start Coding\r\n\r\n```python\r\nfrom pysheetson import SheetsonClient\r\n\r\n# Initialize client\r\nclient = SheetsonClient(\r\n api_key=\"your_api_key_here\",\r\n spreadsheet_id=\"your_spreadsheet_id_here\"\r\n)\r\n\r\n# Basic operations\r\ncities = client.list_rows(\"Cities\", limit=10)\r\nnew_city = client.create_row(\"Cities\", {\"name\": \"Paris\", \"country\": \"France\"})\r\nclient.update_row(\"Cities\", 2, {\"population\": \"2161000\"})\r\nclient.delete_row(\"Cities\", 3)\r\n\r\n# Advanced filtering\r\nlarge_cities = client.search_rows(\"Cities\", \r\n where={\"population\": {\"$gte\": \"1000000\"}},\r\n order_by=\"population\", \r\n desc=True\r\n)\r\n\r\n# Batch operations\r\noperations = [\r\n {\"operation\": \"create\", \"data\": {\"name\": \"Tokyo\", \"country\": \"Japan\"}},\r\n {\"operation\": \"update\", \"row_number\": 2, \"data\": {\"population\": \"37400068\"}},\r\n {\"operation\": \"delete\", \"row_number\": 5}\r\n]\r\nresult = client.batch_operations(\"Cities\", operations)\r\n\r\n# DataFrame integration (requires pandas)\r\nimport pandas as pd\r\ndf = pd.DataFrame([\r\n {\"name\": \"London\", \"country\": \"UK\"},\r\n {\"name\": \"Berlin\", \"country\": \"Germany\"}\r\n])\r\nclient.create_rows_from_dataframe(\"Cities\", df)\r\n```\r\n\r\n## Documentation\r\n\r\n- \ud83d\udcd6 [Full Documentation](https://mr-kam.github.io/pysheetson/)\r\n- \ud83d\ude80 [Github repo](https://github.com/Mr-KAM/pysheetson/)\r\n- \ud83d\udcbb [Example Scripts](https://github.com/Mr-KAM/pysheetson/tree/master/examples)\r\n- \ud83c\udf10 [Sheetson API Docs](https://docs.sheetson.com/)\r\n\r\n## Examples\r\n\r\nCheck out the [examples/](examples/) directory for more usage patterns:\r\n\r\n- `quickstart.py` - Basic operations\r\n- `batch_and_dataframe_example.py` - Advanced features\r\n\r\n## Error Handling\r\n\r\n```python\r\nfrom pysheetson import SheetsonError\r\n\r\ntry:\r\n result = client.create_row(\"Cities\", {\"name\": \"Test\"})\r\nexcept SheetsonError as e:\r\n print(f\"API Error: {e}\")\r\n```\r\n\r\n## Development\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/Mr-KAM/pysheetson.git\r\ncd pysheetson\r\n\r\n# Install in development mode\r\npip install -e .\r\n\r\n# Run tests\r\npython -m pytest tests/\r\n```\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## Links\r\n\r\n- [Sheetson Official Website](https://sheetson.com/)\r\n- [Sheetson API Documentation](https://docs.sheetson.com/)\r\n- [GitHub Repository](https://github.com/Mr-KAM/pysheetson)\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Tiny Python client for the Sheetson API (Google Sheets as a REST API)",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://mr-kam.github.io/pysheetson/",
"Repository": "https://github.com/Mr-KAM/pysheetson.git"
},
"split_keywords": [
"google-sheets",
" api",
" client",
" sheetson"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d8083e6ead6ded2d189dde57ad45700be4173f869e36923e5d651bc4d9a95fea",
"md5": "616e50c5b0a84267936f4820674b085d",
"sha256": "852abed02789a11f6c35f69069d16ac02847bc869ef23f3f9f05d90d2a1b2412"
},
"downloads": -1,
"filename": "pysheetson-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "616e50c5b0a84267936f4820674b085d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7821,
"upload_time": "2025-10-28T17:15:57",
"upload_time_iso_8601": "2025-10-28T17:15:57.428800Z",
"url": "https://files.pythonhosted.org/packages/d8/08/3e6ead6ded2d189dde57ad45700be4173f869e36923e5d651bc4d9a95fea/pysheetson-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 17:15:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Mr-KAM",
"github_project": "pysheetson",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.28"
]
]
}
],
"lcname": "pysheetson"
}
JSON
