Install & Compatibility
Where this runs
tested against v? · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.042s · 67.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.038s · 138MB
102MB installed
● package 102MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Dossier
✓ from shared import Dossier
Dossier is a primary class for storing collections and binary data without direct file management concerns.
Document
✓ from shared import Document
Document is used for individual access to files, often manually edited by humans, like JSON files.
Database
✓ from shared import Database
Database provides an intuitive interaction with SQLite databases.
This quickstart demonstrates how to create a `Dossier` instance, save a Python dictionary to it using a key, and then retrieve the data. The data is persisted to human-readable files. It also includes cleanup instructions for the created directory.
import os
from shared import Dossier, HOME
from datetime import datetime
from pathlib import Path
# Create a dossier (or access an existing one)
# For demonstration, we'll use a temporary path
# In a real app, HOME typically refers to user's home directory
# For testing, ensure 'my_test_dossier' directory is created or handled
# Use a temporary directory for quickstart if HOME is not ideal
# Ensure the directory exists or can be created
project_root = Path(os.environ.get('SHARED_DEMO_PATH', Path.cwd() / 'shared_data'))
project_root.mkdir(parents=True, exist_ok=True)
path = project_root / "my_dossier"
dossier = Dossier(path)
# Sample profile data
now = datetime.now()
profile = {
"name": "alex",
"access_datetime": now.isoformat(), # Store datetime as ISO format string
"pi": 3.14,
"books": ["Seul sur Mars", "The Fall"],
"is_author": True,
"fingerprint": None
}
# Save profile dictionary in the dossier
dossier.set("my_profile", profile)
print(f"Profile saved: {profile}")
# Retrieve profile dictionary
profile_bis = dossier.get("my_profile")
print(f"Profile retrieved: {profile_bis}")
# Assert that the retrieved profile matches the original (after JSON serialization)
assert profile == profile_bis
print("Profiles match!")
# Clean up (optional for quickstart, but good practice)
import shutil
if project_root.exists():
shutil.rmtree(project_root)
print(f"Cleaned up directory: {project_root}")
Debug
Known issues
gotchaThe `shared` library does not implement any synchronization mechanisms to prevent simultaneous access to its underlying files. This can lead to data corruption if multiple processes or threads attempt to write to the same files concurrently.fixFor concurrent access or multi-process environments, consider a more robust persistence solution like Jinbase (recommended by the author) or other databases with built-in concurrency control. Ensure exclusive access or implement external locking mechanisms when using 'shared' in such scenarios.
affects: All versions up to 0.3.0
gotchaThe library is described as an 'experimental data exchange and persistence solution' and a 'playground to test new ideas'. This suggests it might not be fully production-ready or may have a less stable API compared to more mature libraries.fixEvaluate the library's suitability for production use cases carefully. For critical applications, consider alternatives recommended by the author (e.g., Jinbase) or other established key-value stores. Monitor the project's development for updates on its stability and maturity.
affects: All versions up to 0.3.0
gotchaWhen storing `datetime` objects, they are not directly supported for round-trip serialization by Paradict, which `shared` uses. They need to be converted to a serializable format (e.g., ISO format string) before being set and parsed back upon retrieval.fixManually convert `datetime` objects to strings (e.g., `datetime.isoformat()`) before storing them with `dossier.set()` or `document.set()`. Convert them back to `datetime` objects using `datetime.fromisoformat()` after retrieval if needed.
affects: All versions up to 0.3.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'shared'
The 'py-key-value-shared' package, which provides the 'shared' module, is not installed in the current Python environment.
fixpip install py-key-value-shared
AttributeError: 'Shared' object has no attribute 'save'
The Shared object automatically persists data changes to the underlying file, so an explicit 'save()' or 'commit()' method is not provided or needed.
fixNo explicit save method is required; data is automatically persisted upon modification.
KeyError: 'my_key'
Attempting to access a key in the Shared object that does not exist.
fixCheck for key existence using `if 'my_key' in shared_obj:` or use `shared_obj.get('my_key', default_value)`. AttributeError: 'Shared' object has no attribute 'execute_sql'
SQLite database features are being accessed without enabling SQLite mode during the Shared object's initialization.
fixInitialize the Shared object with `sqlite_enabled=True`, for example: `from shared import Shared; db = Shared('my_db', sqlite_enabled=True)`. Upgrade
Version history
0.3.0latest on PyPI · released Nov 17, 2025
Audit
Dependencies
ParadictrequiredUsed internally to encode dictionaries for storage.