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
Metadata
Release files for json-database 1.0.4a2
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 | Actions |
|---|---|---|---|---|
| json_database-1.0.4a2.tar.gz | 47.7 kB | Without provenance | Details for json_database-1.0.4a2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| json_database-1.0.4a2-py3-none-any.whl | Python 3 | none | any | Details for json_database-1.0.4a2-py3-none-any.whl |
Total release size: 66.7 kB
Release files / json_database-1.0.4a2.tar.gz
| Download URL | json_database-1.0.4a2.tar.gz |
|---|---|
| Size | 47.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c559345dcb5f89b60d894ee6fd34ad6529e83d328375fd5d899b3da44d98be57
|
|
BLAKE2b-256 checksum How to use checksums |
01beafc3416e115cfbfca5a74c0ca471c6fdb98af16c7b627169bb859b04df70
|
| 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.4a2-py3-none-any.whl
| Download URL | json_database-1.0.4a2-py3-none-any.whl |
|---|---|
| Size | 19.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cc1f476b2db1ba9da4e5cdcde6c10d69292c6702dfdd4db8b6a9ca665b0cd946
|
|
BLAKE2b-256 checksum How to use checksums |
7676363e4ae7acfb8d47140a2c6b8dc9f4549ef3ca224d4d6bb061c6bb455160
|
| 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.4a2
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.
To learn more about protecting yourself from malicious actors, visit our package security documentation.