Shared Key-Value Store (pyrustic/shared)

0.3.0 verified Tue May 12 auth: no python install: verified

Shared is a Python package from the Pyrustic Open Ecosystem designed for storing unstructured application data, managing configuration files, caching data, and exchanging data. It handles collections, binary data, and SQL queries, utilizing human-readable files under the hood via Paradict for serialization. It is currently at version 0.3.0 and is part of a collection of lightweight Python projects.

pip install shared

Common errors

error ModuleNotFoundError: No module named 'shared' ↓

cause The 'py-key-value-shared' package, which provides the 'shared' module, is not installed in the current Python environment.

fix

pip install py-key-value-shared

error AttributeError: 'Shared' object has no attribute 'save' ↓

cause The Shared object automatically persists data changes to the underlying file, so an explicit 'save()' or 'commit()' method is not provided or needed.

fix

No explicit save method is required; data is automatically persisted upon modification.

error KeyError: 'my_key' ↓

cause Attempting to access a key in the Shared object that does not exist.

fix

Check for key existence using if 'my_key' in shared_obj: or use shared_obj.get('my_key', default_value).

error AttributeError: 'Shared' object has no attribute 'execute_sql' ↓

cause SQLite database features are being accessed without enabling SQLite mode during the Shared object's initialization.

fix

Initialize the Shared object with sqlite_enabled=True, for example: from shared import Shared; db = Shared('my_db', sqlite_enabled=True).

Warnings

gotcha The `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. ↓

fix For 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.

gotcha The 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. ↓

fix Evaluate 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.

gotcha When 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. ↓

fix Manually 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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.03s 67.2M

3.10 alpine (musl) - - 0.04s 67.2M

3.10 slim (glibc) wheel 1.9s 0.02s 138M

3.10 slim (glibc) - - 0.02s 138M

3.11 alpine (musl) wheel - 0.05s 73.8M

3.11 alpine (musl) - - 0.06s 73.8M

3.11 slim (glibc) wheel 1.8s 0.05s 145M

3.11 slim (glibc) - - 0.05s 145M

3.12 alpine (musl) wheel - 0.04s 64.3M

3.12 alpine (musl) - - 0.05s 64.3M

3.12 slim (glibc) wheel 1.6s 0.04s 136M

3.12 slim (glibc) - - 0.04s 136M

3.13 alpine (musl) wheel - 0.04s 60.9M

3.13 alpine (musl) - - 0.04s 60.8M

3.13 slim (glibc) wheel 1.7s 0.04s 134M

3.13 slim (glibc) - - 0.04s 134M

3.9 alpine (musl) wheel - 0.03s 66.4M

3.9 alpine (musl) - - 0.04s 66.4M

3.9 slim (glibc) wheel 2.0s 0.03s 138M

3.9 slim (glibc) - - 0.03s 138M

Imports

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.

Quickstart last tested: 2026-04-24

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}")