This release is a pre-release and may not be stable for production use.
json_database
Searchable, persistent Python dict database backed by JSON files — for those times when SQL is overkill.
Install
pip install json_database
Encryption features additionally require pycryptodomex:
pip install json_database pycryptodomex
Quick Start
from json_database import JsonStorage, JsonDatabase
from json_database.search import Query
# Persistent dict
with JsonStorage("/tmp/config.json") as cfg:
cfg["host"] = "localhost"
cfg["port"] = 5432
# auto-saved on exit
# Searchable list-of-records
with JsonDatabase("users", "/tmp/users.jsondb") as db:
db.add_item({"name": "Alice", "role": "admin"})
db.add_item({"name": "Bob", "role": "user"})
admins = db.search_by_value("role", "admin")
# Fluent query builder
results = Query(db).equal("role", "user").build()
Features
- Pure Python, minimal dependencies (
combo_lockonly) - Persistent dict (
JsonStorage) and list-of-records database (JsonDatabase) - Recursive search by key and key/value pair, with optional fuzzy matching
- Fluent
Querybuilder for multi-condition filtering - AES-256-GCM encryption at rest (
EncryptedJsonStorage) - XDG Base Directory compliant variants for Linux applications
- File locking via
combo_lockfor safe concurrent access - Supports commented JSON files (
//and#line comments) - Arbitrary Python objects stored via automatic
jsonify_recursivelyconversion
Configuration / Key Options
| Class | Default path | Use for |
|---|---|---|
JsonStorage(path) |
user-specified | any persistent dict |
JsonStorageXDG(name) |
~/.cache/json_database/{name}.json |
cache / temp data |
JsonConfigXDG(name) |
~/.config/json_database/{name}.json |
app settings |
JsonDatabaseXDG(name) |
~/.local/share/json_database/{name}.jsondb |
persistent records |
EncryptedJsonStorage(key, path) |
user-specified | sensitive data at rest |
Note: Item IDs in
JsonDatabaseare stable list indices.add_itemandappendreturn the zero-based slot index of the new item. Removing an item tombstones its slot rather than shifting subsequent IDs, so an ID obtained fromadd_itemorget_item_idremains valid for the lifetime of the database file. Tombstoned slots are invisible to iteration, search,__contains__, and__len__; accessing one viadb[item_id]raisesInvalidItemID.
Warning: Encryption keys longer than 16 bytes are silently truncated to 16 bytes. Always use exactly 16 bytes.
Documentation
- Installation — dependencies, Python version support
- Quick Start — 5-minute walkthrough with examples
- API Reference — all public classes and methods
- Encryption — AES-GCM details, key rules, security notes
- XDG Paths — XDG spec support and path resolution
- Search and Query — all filter methods, fuzzy matching
- Development — running tests, CI, contributing
- Architecture — class hierarchy, data flow, design
HiveMind Integration
The HiveMind database-plugin adapter that used to ship as
json_database.hpm:JsonDB has been extracted into its own package,
hivemind-json-db-plugin,
so it can release on a HiveMind-aligned cadence and json_database doesn't pull
in hivemind-plugin-manager for users who don't need it.
For the 1.x line, pip install json_database[hpm] continues to work — it now
transitively installs hivemind-json-db-plugin so the hivemind.database
entry point remains available without code changes. The [hpm] extra will
be removed in 2.0.0; users should migrate to
pip install hivemind-json-db-plugin directly.
License
MIT
2 maintainers
Metadata
2 maintainers
Release files for json-database 1.0.5a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| json_database-1.0.5a1.tar.gz | 47.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| json_database-1.0.5a1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 66.8 kB
Release files / json_database-1.0.5a1.tar.gz
| Download URL | json_database-1.0.5a1.tar.gz |
|---|---|
| Size | 47.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
02d07d429fcdb0b7f36120a8dc6168abf07125f2bea5bc2c86a4268c65208c56
|
|
BLAKE2b-256 checksum How to use checksums |
1e235c889893203e36445d5ffc35c7c943d518d69d61dfe578ced57fa776b3fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / json_database-1.0.5a1-py3-none-any.whl
| Download URL | json_database-1.0.5a1-py3-none-any.whl |
|---|---|
| Size | 19.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
964d17bbe561bd16e5d8d4a0b1a2a86d8a41f4e99c1dba3ada587f62b7c75a34
|
|
BLAKE2b-256 checksum How to use checksums |
3c466f4d4988495e77b7bd243d406cd69211fee832215ff38647942410fff1ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for json-database 1.0.5a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
