# CShelve – The Python Dictionary That Lives in the Cloud 🚀
**Store Python objects locally *or* in the cloud with the same, simple dictionary interface.**
CShelve lets you store and retrieve any Python object—lists, DataFrames, JSON, binary files—whether on local files, AWS S3, Azure Blob Storage, or in-memory, all with the same simple dictionary-like interface.
---
## 📌 Why CShelve?
* **Familiar & Fast** – If you know Python dictionaries, you already know CShelve.
* **Cloud-Ready** – Switch between local files and cloud storage (AWS S3, Azure Blob, SFTP) with **zero code changes**.
* **Lightweight** – No database servers, no migrations, no schema headaches and minimals dependencies.
* **Flexible Formats** – Store pickled Python objects by default, or any format as bytes (JSON, CSV, Parquet, images, etc.).
* **Cost-Effective Scaling** – Tap into cheap and durable cloud storage without maintaining infrastructure.
---
## 🔍 What’s “Shelve” Anyway?
Python’s built-in [`shelve`](https://docs.python.org/3/library/shelve.html) module stores Python objects in a file with a dictionary-like API.
**CShelve supercharges it** with:
* Cloud backends
* Multiple authentication methods
* Format flexibility
* Provider-agnostic switching
If you can do:
```python
mydict['key'] = value
```
You can use CShelve—locally, in the cloud, or on-premises.
---
## 📦 Installation
```bash
# Local storage only
pip install cshelve
# With AWS S3 support
pip install cshelve[aws-s3]
# With Azure Blob support
pip install cshelve[azure-blob]
```
---
## ⚡ Quick Start
### Local Storage
```python
import cshelve
db = cshelve.open('local.db')
db['user'] = {'name': 'Alice', 'age': 30}
print(db['user']) # {'name': 'Alice', 'age': 30}
db.close()
```
### AWS S3
```bash
# Install provider
pip install cshelve[aws-s3]
```
**aws-s3.ini**
```ini
[default]
provider = aws-s3
bucket_name = mybucket
auth_type = access_key
key_id = $AWS_KEY_ID
key_secret = $AWS_KEY_SECRET
```
**Python**
```python
import cshelve
db = cshelve.open('aws-s3.ini')
db['session'] = 'cloud storage is easy'
print(db['session'])
db.close()
```
### Azure Blob
```bash
# Install provider
pip install cshelve[azure-blob]
```
**azure-blob.ini**
```ini
[default]
provider = azure-blob
account_url = https://myaccount.blob.core.windows.net
auth_type = passwordless
container_name = mycontainer
```
**Python**
```python
import cshelve
db = cshelve.open('azure-blob.ini')
db['analytics'] = [1, 2, 3, 4]
print(db['analytics'])
db.close()
```
---
## 📊 Advanced Examples
### Storing Pandas DataFrames in the Cloud
```python
import cshelve, pandas as pd
df = pd.DataFrame({'name': ['Alice', 'Bob'], 'age': [25, 30]})
with cshelve.open('azure-blob.ini') as db:
db['users'] = df
with cshelve.open('azure-blob.ini') as db:
print(db['users'])
```
### Storing JSON (no pickle)
```python
import json, cshelve
data = {"msg": "Hello, Cloud!"}
with cshelve.open('azure-blob.ini') as db:
db['config.json'] = json.dumps(data).encode()
with cshelve.open('azure-blob.ini') as db:
print(json.loads(db['config.json'].decode()))
```
---
## 🛠 Supported Providers
| Provider | Install Extra | Notes |
| ---------- | --------------------- | ---------------------------------------------------------------------------- |
| Local | none | Stores data in a local `.db` file |
| AWS S3 | `cshelve[aws-s3]` | Supports `access_key` auth |
| Azure Blob | `cshelve[azure-blob]` | Supports `access_key`, `passwordless`, `connection_string`, `anonymous` auth |
| In-Memory | none | Perfect for tests and temporary storage |
[Detailed configuration in the documentation.](https://standard-cloud.github.io/cshelve/)
---
## 🤝 Contributing
We welcome pull requests, feature suggestions, and bug reports.
Check the [issues](https://github.com/Standard-Cloud/cshelve/issues) to get started.
---
## 📄 License
MIT – see [LICENSE](LICENSE)
---
## ⭐ Pro Tip
Switching from **local** to **cloud** to **on-premises** is as easy as:
```python
db = cshelve.open('local.db')
# to
db = cshelve.open('aws-s3.ini')
# to
db = cshelve.open('sftp.ini')
```
**No code rewrite. Just change the config.**
Raw data
{
"_id": null,
"home_page": null,
"name": "cshelve",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "S3, aws, azure, azure-storage-account, cloud, database, sftp, shelve",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b5/51/aaddefbc0b17fef72f7af1e74cdc19302d54bebc79a489d0e1dfcf6a6dba/cshelve-1.5.0.tar.gz",
"platform": null,
"description": "# CShelve \u2013 The Python Dictionary That Lives in the Cloud \ud83d\ude80\n\n**Store Python objects locally *or* in the cloud with the same, simple dictionary interface.**\nCShelve lets you store and retrieve any Python object\u2014lists, DataFrames, JSON, binary files\u2014whether on local files, AWS S3, Azure Blob Storage, or in-memory, all with the same simple dictionary-like interface.\n\n---\n\n## \ud83d\udccc Why CShelve?\n\n* **Familiar & Fast** \u2013 If you know Python dictionaries, you already know CShelve.\n* **Cloud-Ready** \u2013 Switch between local files and cloud storage (AWS S3, Azure Blob, SFTP) with **zero code changes**.\n* **Lightweight** \u2013 No database servers, no migrations, no schema headaches and minimals dependencies.\n* **Flexible Formats** \u2013 Store pickled Python objects by default, or any format as bytes (JSON, CSV, Parquet, images, etc.).\n* **Cost-Effective Scaling** \u2013 Tap into cheap and durable cloud storage without maintaining infrastructure.\n\n---\n\n## \ud83d\udd0d What\u2019s \u201cShelve\u201d Anyway?\n\nPython\u2019s built-in [`shelve`](https://docs.python.org/3/library/shelve.html) module stores Python objects in a file with a dictionary-like API.\n**CShelve supercharges it** with:\n\n* Cloud backends\n* Multiple authentication methods\n* Format flexibility\n* Provider-agnostic switching\n\nIf you can do:\n\n```python\nmydict['key'] = value\n```\n\nYou can use CShelve\u2014locally, in the cloud, or on-premises.\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\n# Local storage only\npip install cshelve\n\n# With AWS S3 support\npip install cshelve[aws-s3]\n\n# With Azure Blob support\npip install cshelve[azure-blob]\n```\n\n---\n\n## \u26a1 Quick Start\n\n### Local Storage\n\n```python\nimport cshelve\n\ndb = cshelve.open('local.db')\ndb['user'] = {'name': 'Alice', 'age': 30}\nprint(db['user']) # {'name': 'Alice', 'age': 30}\ndb.close()\n```\n\n### AWS S3\n\n```bash\n# Install provider\npip install cshelve[aws-s3]\n```\n\n**aws-s3.ini**\n\n```ini\n[default]\nprovider = aws-s3\nbucket_name = mybucket\nauth_type = access_key\nkey_id = $AWS_KEY_ID\nkey_secret = $AWS_KEY_SECRET\n```\n\n**Python**\n\n```python\nimport cshelve\n\ndb = cshelve.open('aws-s3.ini')\ndb['session'] = 'cloud storage is easy'\nprint(db['session'])\ndb.close()\n```\n\n### Azure Blob\n\n```bash\n# Install provider\npip install cshelve[azure-blob]\n```\n\n**azure-blob.ini**\n\n```ini\n[default]\nprovider = azure-blob\naccount_url = https://myaccount.blob.core.windows.net\nauth_type = passwordless\ncontainer_name = mycontainer\n```\n\n**Python**\n\n```python\nimport cshelve\n\ndb = cshelve.open('azure-blob.ini')\ndb['analytics'] = [1, 2, 3, 4]\nprint(db['analytics'])\ndb.close()\n```\n\n---\n\n## \ud83d\udcca Advanced Examples\n\n### Storing Pandas DataFrames in the Cloud\n\n```python\nimport cshelve, pandas as pd\n\ndf = pd.DataFrame({'name': ['Alice', 'Bob'], 'age': [25, 30]})\n\nwith cshelve.open('azure-blob.ini') as db:\n db['users'] = df\n\nwith cshelve.open('azure-blob.ini') as db:\n print(db['users'])\n```\n\n### Storing JSON (no pickle)\n\n```python\nimport json, cshelve\n\ndata = {\"msg\": \"Hello, Cloud!\"}\n\nwith cshelve.open('azure-blob.ini') as db:\n db['config.json'] = json.dumps(data).encode()\n\nwith cshelve.open('azure-blob.ini') as db:\n print(json.loads(db['config.json'].decode()))\n```\n\n---\n\n## \ud83d\udee0 Supported Providers\n\n| Provider | Install Extra | Notes |\n| ---------- | --------------------- | ---------------------------------------------------------------------------- |\n| Local | none | Stores data in a local `.db` file |\n| AWS S3 | `cshelve[aws-s3]` | Supports `access_key` auth |\n| Azure Blob | `cshelve[azure-blob]` | Supports `access_key`, `passwordless`, `connection_string`, `anonymous` auth |\n| In-Memory | none | Perfect for tests and temporary storage |\n\n[Detailed configuration in the documentation.](https://standard-cloud.github.io/cshelve/)\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome pull requests, feature suggestions, and bug reports.\nCheck the [issues](https://github.com/Standard-Cloud/cshelve/issues) to get started.\n\n---\n\n## \ud83d\udcc4 License\n\nMIT \u2013 see [LICENSE](LICENSE)\n\n---\n\n## \u2b50 Pro Tip\n\nSwitching from **local** to **cloud** to **on-premises** is as easy as:\n\n```python\ndb = cshelve.open('local.db')\n# to\ndb = cshelve.open('aws-s3.ini')\n# to\ndb = cshelve.open('sftp.ini')\n```\n\n**No code rewrite. Just change the config.**\n",
"bugtrack_url": null,
"license": null,
"summary": "Propulsing the shelve module to the cloud",
"version": "1.5.0",
"project_urls": {
"documentation": "https://standard-cloud.github.io/cshelve/",
"homepage": "https://github.com/Standard-Cloud/cshelve",
"repository": "https://github.com/Standard-Cloud/cshelve"
},
"split_keywords": [
"s3",
" aws",
" azure",
" azure-storage-account",
" cloud",
" database",
" sftp",
" shelve"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e33b08194fe28a52fc29b4de27d31e4292840b3a263bcb9fc7034d26ce642247",
"md5": "988342b3e60ba081193d2df2054a9acc",
"sha256": "237aeeb274f48b0cb8f9693e1c0401730b961c34ea8bd3e066a7215e45d990ce"
},
"downloads": -1,
"filename": "cshelve-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "988342b3e60ba081193d2df2054a9acc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 26930,
"upload_time": "2025-08-09T20:55:23",
"upload_time_iso_8601": "2025-08-09T20:55:23.475414Z",
"url": "https://files.pythonhosted.org/packages/e3/3b/08194fe28a52fc29b4de27d31e4292840b3a263bcb9fc7034d26ce642247/cshelve-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b551aaddefbc0b17fef72f7af1e74cdc19302d54bebc79a489d0e1dfcf6a6dba",
"md5": "b3580c2a48f3188dc30f75424f8e8bdc",
"sha256": "dc3f4102254722121fd02ab09620012a288af5603a6b08002aa32c4c3ce105c2"
},
"downloads": -1,
"filename": "cshelve-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "b3580c2a48f3188dc30f75424f8e8bdc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 227222,
"upload_time": "2025-08-09T20:55:24",
"upload_time_iso_8601": "2025-08-09T20:55:24.612677Z",
"url": "https://files.pythonhosted.org/packages/b5/51/aaddefbc0b17fef72f7af1e74cdc19302d54bebc79a489d0e1dfcf6a6dba/cshelve-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 20:55:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Standard-Cloud",
"github_project": "cshelve",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cshelve"
}
JSON
