json-database 0.10.0

searchable json database with persistence

Json Database

Python dict based database with persistence and search capabilities

For those times when you need something simple and sql is overkill

Features

• pure python
• save and load from file
• search recursively by key and key/value pairs
• fuzzy search
• supports arbitrary objects
• supports comments in saved files

Install

pip install json_database

📡 HiveMind Integration

This project includes a native hivemind-plugin-manager integration, providing seamless interoperability with the HiveMind ecosystem.

• Database Plugin: Provides hivemind-json-db-plugin allowing to use JSON-based storage for client credentials and permissions

🐍 Usage

JsonStorage

Sometimes you need persistent dicts that you can save and load from file

from json_database import JsonStorage
from os.path import exists

save_path = "my_dict.conf"

my_config = JsonStorage(save_path)

my_config["lang"] = "pt"
my_config["secondary_lang"] = "en"
my_config["email"] = "[e-mail]"

# my_config is a python dict
assert isinstance(my_config, dict)

# save to file
my_config.store()

my_config["lang"] = "pt-pt"

# revert to previous saved file
my_config.reload()
assert my_config["lang"] == "pt"

# clear all fields
my_config.clear()
assert my_config == {}

# load from a specific path
my_config.load_local(save_path)
assert my_config == JsonStorage(save_path)

# delete stored file
my_config.remove()
assert not exists(save_path)

# keep working with dict in memory
print(my_config)

JsonDatabase

Ever wanted to search a dict?

Let's create a dummy database with users

from json_database import JsonDatabase

db_path = "users.db"

with JsonDatabase("users", db_path) as db:
    # add some users to the database

    for user in [
        {"name": "bob", "age": 12},
        {"name": "bobby"},
        {"name": ["joe", "jony"]},
        {"name": "john"},
        {"name": "jones", "age": 35},
        {"name": "joey", "birthday": "may 12"}]:
        db.add_item(user)

    # pretty print database contents
    db.print()


# auto saved when used with context manager
# db.commit()

search entries by key

from json_database import JsonDatabase

db_path = "users.db"

db = JsonDatabase("users", db_path) # load db created in previous example

# search by exact key match
users_with_defined_age = db.search_by_key("age")

for user in users_with_defined_age:
    print(user["name"], user["age"])

# fuzzy search
users = db.search_by_key("birth", fuzzy=True)
for user, conf in users:
    print("matched with confidence", conf)
    print(user["name"], user["birthday"])

search by key value pair

# search by key/value pair
users_12years_old = db.search_by_value("age", 12)

for user in users_12years_old:
    assert user["age"] == 12

# fuzzy search
jon_users = db.search_by_value("name", "jon", fuzzy=True)
for user, conf in jon_users:
    print(user["name"])
    print("matched with confidence", conf)
    # NOTE that one of the users has a list instead of a string in the name, it also matches

updating an existing entry

# get database item
item = {"name": "bobby"}

item_id = db.get_item_id(item)

if item_id >= 0:
    new_item = {"name": "don't call me bobby"}
    db.update_item(item_id, new_item)
else:
    print("item not found in database")

# clear changes since last commit
db.reset()

You can save arbitrary objects to the database

from json_database import JsonDatabase

db = JsonDatabase("users", "~/databases/users.json")


class User:
    def __init__(self, email, key=None, data=None):
        self.email = email
        self.secret_key = key
        self.data = data

user1 = User("[e-mail]", data={"name": "jonas", "birthday": "12 May"})
user2 = User("[e-mail]", "secret", data={"name": ["joe", "jony"], "age": 12})

# objects will be "jsonified" here, they will no longer be User objects
# if you need them to be a specific class use some ORM lib instead (SQLAlchemy is great)
db.add_item(user1)
db.add_item(user2)

# search entries with non empty key
print(db.search_by_key("secret_key"))

# search in user provided data
print(db.search_by_key("birth", fuzzy=True))

# search entries with a certain value
print(db.search_by_value("age", 12))
print(db.search_by_value("name", "jon", fuzzy=True))