PickleShare

0.7.5 · active · verified Sun Apr 05

PickleShare is a lightweight, 'shelve'-like persistent dictionary with concurrency support, where each item is stored as a separate file using Python's `pickle` serialization. While the original `pickleshare` (version 0.7.5) has not been actively maintained since 2018, a community-maintained fork, `pickleshare-modern`, provides ongoing support for modern Python versions (3.9+) while retaining API compatibility. It's suitable for low-load, non-mission-critical persistence tasks.

Warnings

breaking The original `pickleshare` (version 0.7.5) is not actively maintained and may have compatibility issues with newer Python versions (beyond Python 3.8). Users are strongly encouraged to use `pickleshare-modern` for current Python environments.
Fix: Use `pip install pickleshare-modern` instead of `pip install pickleshare`. The import path `from pickleshare import PickleShareDB` remains the same.
gotcha PickleShare stores each key-value pair as a separate file on the filesystem. This approach is not suitable for high-load, high-performance, or mission-critical applications, or for storing a very large number of small items, due to filesystem overhead.
Fix: Evaluate if PickleShare's file-based storage model aligns with your application's performance and scale requirements. For more robust storage, consider 'real' databases or object stores.
gotcha As PickleShare uses Python's `pickle` module for serialization, it is inherently unsafe to unpickle data from untrusted or unauthenticated sources. Maliciously crafted pickle data can execute arbitrary code.
Fix: Only use PickleShare with data that originates from trusted sources. Never deserialize pickled data from untrusted network requests or user input.
gotcha Calling `db.clear()` will permanently delete all data within the database directory managed by the `PickleShareDB` instance.
Fix: Exercise caution when using `db.clear()`. Ensure you intend to erase all data or back up important information before performing this operation.

Install

pip install pickleshare-modern Recommended for modern Python
pip install pickleshare Original (unmaintained)

Imports

PickleShareDB
```
from pickleshare import PickleShareDB
```
The 'pickleshare-modern' package maintains the 'pickleshare' import path for compatibility.

Quickstart

This quickstart demonstrates how to initialize a PickleShareDB, store and retrieve various data types (including nested keys), list keys, update values, and delete entries. It also includes cleanup steps for the database directory.

import os
from pickleshare import PickleShareDB

# Create a database in a temporary directory
db_path = './my_pickleshare_db'
os.makedirs(db_path, exist_ok=True)
db = PickleShareDB(db_path)

# Store some data
db['greeting'] = 'Hello, PickleShare!'
db['data/list'] = [1, 2, 3]
db['data/nested/value'] = {'a': 1, 'b': 2}

# Retrieve data
print(f"Greeting: {db['greeting']}")
print(f"List: {db['data/list']}")

# Check keys
print(f"All keys: {list(db.keys())}")

# Update data
db['greeting'] = 'Hello again!'

# Delete data
del db['data/list']

# Clean up the database directory (optional)
db.clear() # Clears all data within the db directory
os.rmdir(db_path) # Removes the empty directory

view raw JSON →