pickleshare

library0.7.5pypypi✓ verified 25d ago

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.

database serialization

pip install pickleshare-modern

github ↗package ↗

INSTALL

IMPORT

SIG · PICKLESHARE

pickleshare

databasepythonv0.7.5

Install

1.5s avg

Import

14ms

Disk

65MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.7.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.014s · 65.5MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.5s · import 0.014s · 18MB

65MB installed

● package 65MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PickleShareDB

✓ from pickleshare import PickleShareDB

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

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

Debug

Known issues

breakingThe 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.

affects: <=0.7.5

gotchaPickleShare 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.

affects: All

gotchaAs 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.

affects: All

gotchaCalling `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.

affects: All

gotchaWhen deleting a `PickleShareDB` instance's directory, `os.rmdir()` will fail if the directory is not empty. `PickleShareDB` creates subdirectories and files within its base directory, requiring a recursive deletion method for proper cleanup.

fix

Use `shutil.rmtree(db_path)` to recursively delete the database directory and all its contents when cleaning up a PickleShareDB instance.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pickleshare'

The `pickleshare` package is not installed in the current Python environment or is not accessible within the system's Python path.

fix

Install the library using pip: `pip install pickleshare`

ImportError: cannot import name 'path'

This error occurs because the `path.py` dependency, which `pickleshare` relies on, introduced a breaking API change in version 8.0, where `path.path` was removed.

fix

Downgrade the `path.py` package to an earlier compatible version: `pip install -I path.py==7.7.1` or `pip install path.py==8.1` (version 8.1 reportedly re-added the alias with a warning).

AttributeError: 'PickleShareDB' object has no attribute 'keys'

This error typically arises when attempting to use a method like `keys()` on a `PickleShareDB` object in a context where it's expected to behave like a standard dictionary with a specific signature, but the method is either missing or has been changed. It has been observed in specific contexts like IPython's `%store` magic.

fix

This specific issue might indicate an incompatibility between the `pickleshare` version and the calling library (e.g., IPython). Consider upgrading or downgrading `pickleshare` or the dependent library, or consulting their documentation for expected API usage. A workaround could involve iterating `db.items()` and extracting keys if direct `keys()` fails.

_pickle.UnpicklingError: invalid load key, ' '

This error indicates that the `pickle` module, used by `pickleshare` for serialization, encountered data that is not a valid pickle stream. Common reasons include attempting to unpickle a file that is corrupted, not a pickle file at all, or was pickled with a Python version (or `pickle` protocol) incompatible with the current environment.

fix

Ensure the file being loaded is a valid `pickleshare` data file created with a compatible Python and `pickle` protocol version. If migrating between Python 2 and 3, or significantly different Python 3 versions, re-pickling the data in the target environment or using compatible `pickle` protocols can help. Also, verify file integrity and that no other data (like compression headers) precedes the pickle data.

Upgrade

Version history

0.7.5latest on PyPI · released Sep 25, 2018

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/pickleshare/pickleshare ↗

packagehttps://pypi.org/project/pickleshare/ ↗