# 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
```bash
pip install json_database
```
## 📡 HiveMind Integration
This project includes a native [hivemind-plugin-manager](https://github.com/JarbasHiveMind/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
```python
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"] = "jarbasai@mailfence.com"
# 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
```python
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
```python
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
```python
# 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
```python
# 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
```python
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("first@mail.net", data={"name": "jonas", "birthday": "12 May"})
user2 = User("second@mail.net", "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))
```
Raw data
{
"_id": null,
"home_page": "https://github.com/TigreGotico/json_database",
"name": "json-database",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "jarbasAI",
"author_email": "jarbasai@mailfence.com",
"download_url": "https://files.pythonhosted.org/packages/f7/e3/76532d3523c76ffab8d483a13f3a81446917ddad2fb79486ae2e8e9fa167/json_database-0.10.1.tar.gz",
"platform": null,
"description": "# Json Database\n\nPython dict based database with persistence and search capabilities\n\nFor those times when you need something simple and sql is overkill\n\n\n## Features\n\n- pure python\n- save and load from file\n- search recursively by key and key/value pairs\n- fuzzy search\n- supports arbitrary objects\n- supports comments in saved files\n\n## Install\n\n```bash\npip install json_database\n```\n\n\n## \ud83d\udce1 HiveMind Integration\n\nThis project includes a native [hivemind-plugin-manager](https://github.com/JarbasHiveMind/hivemind-plugin-manager) integration, providing seamless interoperability with the HiveMind ecosystem.\n- **Database Plugin**: Provides `hivemind-json-db-plugin` allowing to use JSON-based storage for client credentials and permissions\n\n## \ud83d\udc0d Usage\n\n\n### JsonStorage\n\nSometimes you need persistent dicts that you can save and load from file\n\n```python\nfrom json_database import JsonStorage\nfrom os.path import exists\n\nsave_path = \"my_dict.conf\"\n\nmy_config = JsonStorage(save_path)\n\nmy_config[\"lang\"] = \"pt\"\nmy_config[\"secondary_lang\"] = \"en\"\nmy_config[\"email\"] = \"jarbasai@mailfence.com\"\n\n# my_config is a python dict\nassert isinstance(my_config, dict)\n\n# save to file\nmy_config.store()\n\nmy_config[\"lang\"] = \"pt-pt\"\n\n# revert to previous saved file\nmy_config.reload()\nassert my_config[\"lang\"] == \"pt\"\n\n# clear all fields\nmy_config.clear()\nassert my_config == {}\n\n# load from a specific path\nmy_config.load_local(save_path)\nassert my_config == JsonStorage(save_path)\n\n# delete stored file\nmy_config.remove()\nassert not exists(save_path)\n\n# keep working with dict in memory\nprint(my_config)\n```\n\n### JsonDatabase\n\nEver wanted to search a dict?\n\nLet's create a dummy database with users\n\n```python\nfrom json_database import JsonDatabase\n\ndb_path = \"users.db\"\n\nwith JsonDatabase(\"users\", db_path) as db:\n # add some users to the database\n\n for user in [\n {\"name\": \"bob\", \"age\": 12},\n {\"name\": \"bobby\"},\n {\"name\": [\"joe\", \"jony\"]},\n {\"name\": \"john\"},\n {\"name\": \"jones\", \"age\": 35},\n {\"name\": \"joey\", \"birthday\": \"may 12\"}]:\n db.add_item(user)\n\n # pretty print database contents\n db.print()\n\n\n# auto saved when used with context manager\n# db.commit()\n\n\n```\n\nsearch entries by key\n\n```python\nfrom json_database import JsonDatabase\n\ndb_path = \"users.db\"\n\ndb = JsonDatabase(\"users\", db_path) # load db created in previous example\n\n# search by exact key match\nusers_with_defined_age = db.search_by_key(\"age\")\n\nfor user in users_with_defined_age:\n print(user[\"name\"], user[\"age\"])\n\n# fuzzy search\nusers = db.search_by_key(\"birth\", fuzzy=True)\nfor user, conf in users:\n print(\"matched with confidence\", conf)\n print(user[\"name\"], user[\"birthday\"])\n```\n\nsearch by key value pair\n\n```python\n# search by key/value pair\nusers_12years_old = db.search_by_value(\"age\", 12)\n\nfor user in users_12years_old:\n assert user[\"age\"] == 12\n\n# fuzzy search\njon_users = db.search_by_value(\"name\", \"jon\", fuzzy=True)\nfor user, conf in jon_users:\n print(user[\"name\"])\n print(\"matched with confidence\", conf)\n # NOTE that one of the users has a list instead of a string in the name, it also matches\n```\n\nupdating an existing entry\n\n```python\n# get database item\nitem = {\"name\": \"bobby\"}\n\nitem_id = db.get_item_id(item)\n\nif item_id >= 0:\n new_item = {\"name\": \"don't call me bobby\"}\n db.update_item(item_id, new_item)\nelse:\n print(\"item not found in database\")\n\n# clear changes since last commit\ndb.reset()\n```\n\nYou can save arbitrary objects to the database\n\n```python\nfrom json_database import JsonDatabase\n\ndb = JsonDatabase(\"users\", \"~/databases/users.json\")\n\n\nclass User:\n def __init__(self, email, key=None, data=None):\n self.email = email\n self.secret_key = key\n self.data = data\n\nuser1 = User(\"first@mail.net\", data={\"name\": \"jonas\", \"birthday\": \"12 May\"})\nuser2 = User(\"second@mail.net\", \"secret\", data={\"name\": [\"joe\", \"jony\"], \"age\": 12})\n\n# objects will be \"jsonified\" here, they will no longer be User objects\n# if you need them to be a specific class use some ORM lib instead (SQLAlchemy is great)\ndb.add_item(user1)\ndb.add_item(user2)\n\n# search entries with non empty key\nprint(db.search_by_key(\"secret_key\"))\n\n# search in user provided data\nprint(db.search_by_key(\"birth\", fuzzy=True))\n\n# search entries with a certain value\nprint(db.search_by_value(\"age\", 12))\nprint(db.search_by_value(\"name\", \"jon\", fuzzy=True))\n\n```\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "searchable json database with persistence",
"version": "0.10.1",
"project_urls": {
"Homepage": "https://github.com/TigreGotico/json_database"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f5449940a9f8e121420e010b52d15953f5c02b59875216dfe54ea9425adebb2c",
"md5": "d968cc5669a142e73fce0f03628e59ff",
"sha256": "a1e566848cd2de11a8fff8eaeeb64085dc68f856fcb19288789956256246be98"
},
"downloads": -1,
"filename": "json_database-0.10.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d968cc5669a142e73fce0f03628e59ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 15288,
"upload_time": "2024-12-29T17:12:46",
"upload_time_iso_8601": "2024-12-29T17:12:46.235332Z",
"url": "https://files.pythonhosted.org/packages/f5/44/9940a9f8e121420e010b52d15953f5c02b59875216dfe54ea9425adebb2c/json_database-0.10.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f7e376532d3523c76ffab8d483a13f3a81446917ddad2fb79486ae2e8e9fa167",
"md5": "dada6edab6b4daa67b1348972d96b72f",
"sha256": "2e41a1b958bfc90ac5ceb4ca3c9524442789bc4cc23b09605ab67893beed289a"
},
"downloads": -1,
"filename": "json_database-0.10.1.tar.gz",
"has_sig": false,
"md5_digest": "dada6edab6b4daa67b1348972d96b72f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16375,
"upload_time": "2024-12-29T17:12:50",
"upload_time_iso_8601": "2024-12-29T17:12:50.445945Z",
"url": "https://files.pythonhosted.org/packages/f7/e3/76532d3523c76ffab8d483a13f3a81446917ddad2fb79486ae2e8e9fa167/json_database-0.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-29 17:12:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TigreGotico",
"github_project": "json_database",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "combo_lock",
"specs": [
[
">=",
"0.2.1"
],
[
"<",
"1.0.0"
]
]
}
],
"lcname": "json-database"
}