Shared Key-Value Store (pyrustic/shared)

0.3.0 · active · verified Sun Mar 29

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.

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

pip install shared Install stable version

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

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

view raw JSON →