# Kivi.py 🥝
```py
from kivi import Kivi
db = Kivi()
db.kv_create("mydb", {"greeting-1": "Good morning 🌅"})
```
A simple key-value database that uses [JSON](https://www.json.org/json-en.html) to store data
## Supported data types
- String
- Boolean
- Integer
- Float
- Lists
- Dict
- Datetime
## Why?
I just wanted a simple database to play around, why everything is so complex
<img src="https://raw.githubusercontent.com/Itz-fork/Kivi.py/main/assests/crying.jpg" width=200, height=auto />
## Install
```
pip install kivi.py
```
## Usage
- [Init](#initialize-database)
- [Create](#create)
- [Load](#load)
- [Get](#get)
- [Set / Update](#set--update)
- [Merge](#merge)
- [Index](#index)
- [Query](#query)
- [Search](#search)
---
### Initialize database
```py
from kivi import Kivi
db = Kivi(
src="Where the database files should be stored. Defaults to `os.getcwd()/.kivi_db`",
to_load=["path/to/file.json"])
```
> [!NOTE]
> `to_load` only takes json file with default kivi format.
> If you want to store regular json data use [create](#create) or [merge](#merge)
---
### Create
Creates a new database and load it to the memory
- Arguments:
- `name`: Name of the database
- `data`: Dict consist of data
- Example:
```py
db.kv_create("wow", {"user-1": 123456})
```
---
### Load
> [!Note]
> It is recommended to load databases when initializing the database with `Kivi(to_load=[...])`
Loads database into the memory
- Arguments:
- `data`: Path to a json file or python dict
- Returns:
Index of the database
- Example:
```py
db.kv_load("/home/test/data/stuff.json")
```
---
### Get
Get value from a database
- Arguments:
- `index`: Index of the database (returned in kv_load or when creating the instance)
- `key`: Key!
- Example:
```py
db.kv_get(0, "greeting")
```
---
### Set / Update
Add or update key in a database
- Arguments:
- `index`: Index of the database (returned in kv_load or when creating the instance)
- `key`: Key!
- Example:
```py
db.kv_set(0, "gtr1", "greeting")
```
---
### Merge
Merge data into the database
- Arguments:
- `index`: Index of the database (returned in kv_load or when creating the instance)
- `tomerge`: Dict consist of data that needs to be merged
- Example:
```py
dt = {
"thing-1": [123, True, {'user1': 'gibberish?#45'}],
"thing-2": [123, True, {'user2': 'gibberish?#45', 'nuh': True}]
}
db.kv_merge(index=0, tomerge=dt, to_std=True)
```
> [!Note]
> If the `tomerge` dict is not in the kivi formatting, set `to_std = True`
---
### Index
Index data to perform queries much faster
- Arguments:
- `data`: Data to index (a dict or list of dicts)
- `fields`: Json fields that needs to be indexed
- `chars`: Amount of characters that indexed key can have (Ex: "Spider" will be sliced to "spi" to create the key for index)
- Example:
```py
data = [
{"title": "Spooder man", "extract": "Marvel spooder man!"},
{"title": "Iron deficiency man", "extract": "Marvel no Fe?"}
]
db.kv_index(data, ["title", "extract"], 3)
```
---
### Query
Search for string in an indexed database
- Arguments:
- `index`: Index of the database (returned in kv_load or when creating the instance)
- `query`: String to search for in the database
- Example:
```py
db.kv_query(0, "Spider man")
```
---
### Search
Search for string in a database
- Arguments:
- `index`: Index of the database (returned in kv_load or when creating the instance)
- `query`: String to search for in the database
- `strict`: Pass 'False' to get more results
- Example:
```py
db.kv_search(0, "Spider man")
```
## How it works
Data is stored inside json files in the following format
```json
{
"name": "lot",
"items": {...}
}
```
`items` contains the inserted data as a string alongside it's original data type like this,
```json
{
"name": "lot",
"items": {
"thing-1": [
"{'user': 'gibberish?#45'}",
"dict"
],
"thing-2": [
"{'user': 'gibberish?#45'}",
"dict"
]
}
}
```
When you request data using `kv_get` function, data will be automatically converted back to it's original type ([limitations](#limitations))
## Requirements
- Python 3.5+
- [dependecies](requirements.txt)
### Limitations
The data convertion has lots of limits as of now (I don't plan of updating this either).
For example:
- Complex json structures will fail to convert
Raw data
{
"_id": null,
"home_page": "https://github.com/Itz-fork/kivi.py",
"name": "kivi.py",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "databse,key-value,key-value database,kivi.py",
"author": "Itz-fork",
"author_email": "git.itzfork@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1f/c8/f4ff713a5e9dbfb665180b734bd2453e35c47007235fd0e78affe3eca42e/kivi.py-0.1.2.tar.gz",
"platform": null,
"description": "# Kivi.py \ud83e\udd5d\n\n```py\nfrom kivi import Kivi\n\ndb = Kivi()\ndb.kv_create(\"mydb\", {\"greeting-1\": \"Good morning \ud83c\udf05\"})\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<img src=\"https://raw.githubusercontent.com/Itz-fork/Kivi.py/main/assests/crying.jpg\" width=200, height=auto />\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> [!NOTE]\n> `to_load` only takes json file with default kivi format.\n> 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> [!Note]\n> 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> [!Note]\n> 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\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple key-value database",
"version": "0.1.2",
"project_urls": {
"Download": "https://github.com/Itz-fork/kivi.py/releases/tag/kivi.py-pypi-0.1.2",
"Homepage": "https://github.com/Itz-fork/kivi.py"
},
"split_keywords": [
"databse",
"key-value",
"key-value database",
"kivi.py"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1fc8f4ff713a5e9dbfb665180b734bd2453e35c47007235fd0e78affe3eca42e",
"md5": "48e8f647d39535a9da3976749dfbbd2e",
"sha256": "4fd58138c3a5d556da6296e073fdbd3ccef3fdadcb0926a10cd887a7622c0769"
},
"downloads": -1,
"filename": "kivi.py-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "48e8f647d39535a9da3976749dfbbd2e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9380,
"upload_time": "2023-11-25T14:35:46",
"upload_time_iso_8601": "2023-11-25T14:35:46.799213Z",
"url": "https://files.pythonhosted.org/packages/1f/c8/f4ff713a5e9dbfb665180b734bd2453e35c47007235fd0e78affe3eca42e/kivi.py-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-25 14:35:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Itz-fork",
"github_project": "kivi.py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "kivi.py"
}
JSON
