{"id":927,"library":"py-key-value-shared","title":"Shared Key-Value Store (pyrustic/shared)","description":"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.","status":"active","version":"0.3.0","language":"python","source_language":"en","source_url":"https://github.com/pyrustic/shared","tags":["key-value","persistence","file-storage","configuration","data-exchange","pyrustic"],"install":[{"cmd":"pip install shared","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used internally to encode dictionaries for storage.","package":"Paradict","optional":false}],"imports":[{"note":"Dossier is a primary class for storing collections and binary data without direct file management concerns.","symbol":"Dossier","correct":"from shared import Dossier"},{"note":"Document is used for individual access to files, often manually edited by humans, like JSON files.","symbol":"Document","correct":"from shared import Document"},{"note":"Database provides an intuitive interaction with SQLite databases.","symbol":"Database","correct":"from shared import Database"}],"quickstart":{"code":"import os\nfrom shared import Dossier, HOME\nfrom datetime import datetime\nfrom pathlib import Path\n\n# Create a dossier (or access an existing one)\n# For demonstration, we'll use a temporary path\n# In a real app, HOME typically refers to user's home directory\n# For testing, ensure 'my_test_dossier' directory is created or handled\n\n# Use a temporary directory for quickstart if HOME is not ideal\n# Ensure the directory exists or can be created\nproject_root = Path(os.environ.get('SHARED_DEMO_PATH', Path.cwd() / 'shared_data'))\nproject_root.mkdir(parents=True, exist_ok=True)\n\npath = project_root / \"my_dossier\"\ndossier = Dossier(path)\n\n# Sample profile data\nnow = datetime.now()\nprofile = {\n    \"name\": \"alex\",\n    \"access_datetime\": now.isoformat(), # Store datetime as ISO format string\n    \"pi\": 3.14,\n    \"books\": [\"Seul sur Mars\", \"The Fall\"],\n    \"is_author\": True,\n    \"fingerprint\": None\n}\n\n# Save profile dictionary in the dossier\ndossier.set(\"my_profile\", profile)\nprint(f\"Profile saved: {profile}\")\n\n# Retrieve profile dictionary\nprofile_bis = dossier.get(\"my_profile\")\nprint(f\"Profile retrieved: {profile_bis}\")\n\n# Assert that the retrieved profile matches the original (after JSON serialization)\nassert profile == profile_bis\nprint(\"Profiles match!\")\n\n# Clean up (optional for quickstart, but good practice)\nimport shutil\nif project_root.exists():\n    shutil.rmtree(project_root)\n    print(f\"Cleaned up directory: {project_root}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions up to 0.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions up to 0.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions up to 0.3.0"}],"env_vars":null,"search_vec":"'0.3.0':56 'applic':21 'binari':34 'cach':26 'collect':33,62 'configur':24,74 'current':53 'data':22,27,30,35,76 'data-exchang':75 'design':17 'ecosystem':16 'exchang':29,77 'file':25,43,72 'file-storag':71 'handl':32 'hood':46 'human':41 'human-read':40 'key':3,68 'key-valu':2,67 'lightweight':64 'manag':23 'open':15 'packag':11 'paradict':48 'part':59 'persist':70 'project':66 'pyrust':14,78 'pyrustic/shared':6 'python':10,65 'queri':38 'readabl':42 'serial':50 'share':1,7 'sql':37 'storag':73 'store':5,19 'unstructur':20 'util':39 'valu':4,69 'version':55 'via':47","created_at":"2026-03-29T06:08:03.135722+00:00","updated_at":"2026-04-16T19:09:25.198484+00:00","problems":[{"fix":"pip install py-key-value-shared","cause":"The 'py-key-value-shared' package, which provides the 'shared' module, is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'shared'"},{"fix":"No explicit save method is required; data is automatically persisted upon modification.","cause":"The Shared object automatically persists data changes to the underlying file, so an explicit 'save()' or 'commit()' method is not provided or needed.","error":"AttributeError: 'Shared' object has no attribute 'save'"},{"fix":"Check for key existence using `if 'my_key' in shared_obj:` or use `shared_obj.get('my_key', default_value)`.","cause":"Attempting to access a key in the Shared object that does not exist.","error":"KeyError: 'my_key'"},{"fix":"Initialize the Shared object with `sqlite_enabled=True`, for example: `from shared import Shared; db = Shared('my_db', sqlite_enabled=True)`.","cause":"SQLite database features are being accessed without enabling SQLite mode during the Shared object's initialization.","error":"AttributeError: 'Shared' object has no attribute 'execute_sql'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.3.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/py-key-value-shared/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}