json-database


Namejson-database JSON
Version 0.10.1 PyPI version JSON
download
home_pagehttps://github.com/TigreGotico/json_database
Summarysearchable json database with persistence
upload_time2024-12-29 17:12:50
maintainerNone
docs_urlNone
authorjarbasAI
requires_pythonNone
licenseMIT
keywords
VCS
bugtrack_url
requirements combo_lock
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 1.68369s