{"id":23628622,"url":"https://github.com/itz-fork/kivi.py","last_synced_at":"2025-09-07T11:46:10.029Z","repository":{"id":208463329,"uuid":"721586664","full_name":"Itz-fork/Kivi.py","owner":"Itz-fork","description":"JSON based python key-value database for rapid prototyping","archived":false,"fork":false,"pushed_at":"2023-11-25T14:35:01.000Z","size":89,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-25T19:42:34.525Z","etag":null,"topics":["database","hobby-project","key-value","key-value-database"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Itz-fork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-21T11:16:58.000Z","updated_at":"2023-12-01T05:47:45.000Z","dependencies_parsed_at":"2024-12-28T00:46:51.704Z","dependency_job_id":"30fe3bff-caf3-47d1-80a8-954913c3edac","html_url":"https://github.com/Itz-fork/Kivi.py","commit_stats":null,"previous_names":["itz-fork/kivi.py"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Itz-fork%2FKivi.py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Itz-fork%2FKivi.py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Itz-fork%2FKivi.py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Itz-fork%2FKivi.py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Itz-fork","download_url":"https://codeload.github.com/Itz-fork/Kivi.py/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239543670,"owners_count":19656411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","hobby-project","key-value","key-value-database"],"created_at":"2024-12-28T00:46:49.495Z","updated_at":"2025-02-18T20:26:30.884Z","avatar_url":"https://github.com/Itz-fork.png","language":"Python","readme":"# Kivi.py 🥝\n\n```py\nfrom kivi import Kivi\n\ndb = Kivi()\ndb.kv_create(\"mydb\", {\"greeting-1\": \"Good morning 🌅\"})\n```\n\nA simple key-value database that uses [JSON](https://www.json.org/json-en.html) to store data\n\n\n## Supported data types\n- String\n- Boolean\n- Integer\n- Float\n- Lists\n- Dict\n- Datetime\n\n\n## Why?\nI just wanted a simple database to play around, why everything is so complex\n\n\u003cimg src=\"https://raw.githubusercontent.com/Itz-fork/Kivi.py/main/assests/crying.jpg\" width=200, height=auto /\u003e\n\n\n## Install\n\n```\npip install kivi.py\n```\n\n## Usage\n- [Init](#initialize-database)\n- [Create](#create)\n- [Load](#load)\n- [Get](#get)\n- [Set / Update](#set--update)\n- [Merge](#merge)\n- [Index](#index)\n- [Query](#query)\n- [Search](#search)\n\n---\n\n### Initialize database\n```py\nfrom kivi import Kivi\n\ndb = Kivi(\n    src=\"Where the database files should be stored. Defaults to `os.getcwd()/.kivi_db`\",\n    to_load=[\"path/to/file.json\"])\n```\n\n\u003e [!NOTE]\n\u003e `to_load` only takes json file with default kivi format.\n\u003e If you want to store regular json data use [create](#create) or [merge](#merge)\n\n---\n\n### Create\nCreates a new database and load it to the memory\n\n- Arguments:\n    - `name`: Name of the database\n    - `data`: Dict consist of data\n\n- Example:\n    ```py\n    db.kv_create(\"wow\", {\"user-1\": 123456})\n    ```\n\n---\n\n### Load\n\n\u003e [!Note]\n\u003e It is recommended to load databases when initializing the database with `Kivi(to_load=[...])`\n\nLoads database into the memory\n\n- Arguments:\n    - `data`: Path to a json file or python dict\n        \n- Returns:\n    Index of the database\n\n- Example:\n    ```py\n    db.kv_load(\"/home/test/data/stuff.json\")\n    ```\n\n---\n\n### Get\nGet value from a database\n\n- Arguments:\n    - `index`: Index of the database (returned in kv_load or when creating the instance)\n    - `key`: Key!\n\n- Example:\n    ```py\n    db.kv_get(0, \"greeting\")\n    ```\n\n---\n\n### Set / Update\nAdd or update key in a database\n\n- Arguments:\n    - `index`: Index of the database (returned in kv_load or when creating the instance)\n    - `key`: Key!\n\n- Example:\n    ```py\n    db.kv_set(0, \"gtr1\", \"greeting\")\n    ```\n---\n\n### Merge\nMerge data into the database\n\n- Arguments:\n    - `index`: Index of the database (returned in kv_load or when creating the instance)\n    - `tomerge`: Dict consist of data that needs to be merged\n\n- Example:\n    ```py\n    dt = {\n        \"thing-1\": [123, True, {'user1': 'gibberish?#45'}],\n        \"thing-2\": [123, True, {'user2': 'gibberish?#45', 'nuh': True}]\n    }\n    db.kv_merge(index=0, tomerge=dt, to_std=True)\n    ```\n\n\u003e [!Note]\n\u003e If the `tomerge` dict is not in the kivi formatting, set `to_std = True`\n\n---\n\n### Index\n\nIndex data to perform queries much faster\n\n- Arguments:\n    - `data`: Data to index (a dict or list of dicts)\n    - `fields`: Json fields that needs to be indexed\n    - `chars`: Amount of characters that indexed key can have (Ex: \"Spider\" will be sliced to \"spi\" to create the key for index)\n        \n- Example:\n    ```py\n    data = [\n        {\"title\": \"Spooder man\", \"extract\": \"Marvel spooder man!\"},\n        {\"title\": \"Iron deficiency man\", \"extract\": \"Marvel no Fe?\"}\n    ]\n    db.kv_index(data, [\"title\", \"extract\"], 3)\n    ```\n\n---\n\n### Query\n\nSearch for string in an indexed database\n\n- Arguments:\n    - `index`: Index of the database (returned in kv_load or when creating the instance)\n    - `query`: String to search for in the database\n\n- Example:\n    ```py\n    db.kv_query(0, \"Spider man\")\n    ```\n\n---\n\n### Search\nSearch for string in a database\n\n- Arguments:\n    - `index`: Index of the database (returned in kv_load or when creating the instance)\n    - `query`: String to search for in the database\n    - `strict`: Pass 'False' to get more results\n\n- Example:\n    ```py\n    db.kv_search(0, \"Spider man\")\n    ```\n\n\n## How it works\nData is stored inside json files in the following format\n\n```json\n{\n    \"name\": \"lot\",\n    \"items\": {...}\n}\n```\n\n`items` contains the inserted data as a string alongside it's original data type like this,\n```json\n{\n    \"name\": \"lot\",\n    \"items\": {\n        \"thing-1\": [\n            \"{'user': 'gibberish?#45'}\",\n            \"dict\"\n        ],\n        \"thing-2\": [\n            \"{'user': 'gibberish?#45'}\",\n            \"dict\"\n        ]\n    }\n}\n```\n\nWhen you request data using `kv_get` function, data will be automatically converted back to it's original type ([limitations](#limitations))\n\n\n## Requirements\n- Python 3.5+\n    - [dependecies](requirements.txt)\n\n\n### Limitations\nThe data convertion has lots of limits as of now (I don't plan of updating this either).\n\nFor example:\n\n- Complex json structures will fail to convert","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitz-fork%2Fkivi.py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitz-fork%2Fkivi.py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitz-fork%2Fkivi.py/lists"}