json-database 1.0.2a1

searchable json database with persistence

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_lock only)
• Persistent dict (JsonStorage) and list-of-records database (JsonDatabase)
• Recursive search by key and key/value pair, with optional fuzzy matching
• Fluent Query builder for multi-condition filtering
• AES-256-GCM encryption at rest (EncryptedJsonStorage)
• XDG Base Directory compliant variants for Linux applications
• File locking via combo_lock for safe concurrent access
• Supports commented JSON files (// and # line comments)
• Arbitrary Python objects stored via automatic jsonify_recursively conversion

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 JsonDatabase are stable list indices. add_item and append return the zero-based slot index of the new item. Removing an item tombstones its slot rather than shifting subsequent IDs, so an ID obtained from add_item or get_item_id remains valid for the lifetime of the database file. Tombstoned slots are invisible to iteration, search, __contains__, and __len__; accessing one via db[item_id] raises InvalidItemID.

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