# About HydroDB
`HydroDB` can be a non-relational or a relational database library for Python, designed to be easy to use and agile. It allows you to create `JSON` files and store data in them with desired keys. Additionally, it enables searching, updating, and deleting data within the `JSON` file.
## Why HydroDB exists?
The idea for HydroDB emerged during my college days when I had to use TinyDB in one of my classes. While TinyDB is a good library for non-relational databases, I felt that something was missing. After studying the subject, I decided to create my own non-relational database library.
## Setting Up
### Requirements (for versions 1.#.#)
- [Python 3](https://www.python.org/downloads/) version 3.12.2 or above.
```bash
pip install hydrodb
```
## Data structure
On HydroDB all `JSON` files has an shered base struct:
```json
{
"TABLE NAME": "tables-name",
"META DATA": "tables-meta-data",
"TABLE COLUMNS": [
"columns_1",
"columns_2",
"...",
],
"PK": "tables-primary-key",
"ROWS": [
{
"id": 1,
"values": {
"column_1": "x",
"columns_2": null,
}
}
]
}
```
> - "TABLE TABME": string -> Is the name of the table.
>
> - "META DATA": string -> Here goes the descriptions of the data tha goes into the table.
>
> - "TABLE COLUMNS":array/list -> The columns tha goes into the table.
>
> - "PK": string -> Is the columns that represents the primary key of the table.
>
> - "ROWS": array/list of dictionaries -> Here goes the rows of the table. Is important to remember that every single row has an id and the values of the row associeted with the table's columns.
## Observable functions
Those functions are made to lookup the table, for general porpose
# Get Started
Here is a simple guide on how to use the `HydroDB` module.
## Calling HydroDB in the program
### Default creation
To use the module, simply use:
```python
from hydrodb import HydroDB
hydro = HydroDB()
```
In this case, a directory `db/` will be created at your project folder level:
```
your-project-folder
|--> db/
|--> hydrodb/
|--> main.py
```
### Optional dirpath
`HydroDB` allows you to choose a folder to create the database directory.
To do that, use:
```python
from hydrodb import HydroDB
hydro = HydroDB(optional_path='any_dir_name')
```
In this case, a directory `db/` will be created at your project folder level:
```
your-project-folder
|--> any_dir_name
|--> db/
|--> hydrodb/
|--> main.py
```
## Commands list
Designed to be a very user-friendly module, `HydroDB` only has 6 **operational** functions and 3 **observable** functions to be called.
## Operational Functions
The opearional functions are thesigned to execute the CRUD
- C : create
- R : read
- U : update
- D : delete
1 of them are to `create`, 1 for `reade`, 3 for `update` and 1 for `delete`.
### create_table() --> `create`
The create() function is designed for the creation of tables, along with the columns that each table possesses.
```python
hydro.create_table(
tables="Table_1",
columns=["name", "age"],
pk="name"
)
```
```json
// Expected table structure
{
"TABLE NAME": "TABLE_1",
"META DATA": null,
"TABLE COLUMNS": [
"name",
"age"
],
"PK": "name",
"ROWS": []
}
```
- `tables`: str --> Na name of the table to be created. (Learn more about [strings](https://www.w3schools.com/python/python_strings.asp))
- `columns`: Lists --> The columns for the table. (Learn more about [lists](https://www.w3schools.com/python/python_lists.asp))
- `pk`: str --> Defines the primary key of the table. If no values are passed, the primary-key will be the `id`
### add_row() --> `update`
To add values to table's columns, uses the add() function.
```python
hydro.add_rows(
table_name="Table_1",
into_columns=["name", "age"],
values=["James", 34]
)
```
```json
// Expected result
{
"TABLE NAME": "TABLE_1",
"META DATA": null,
"TABLE COLUMNS": [
"name",
"age"
],
"PK": "name",
"ROWS": [
{
"id": 1,
"values":{
"name": "James",
"age": 34
}
}
]
}
```
- `tables_names`: str --> Receives the table that you want to add values.
- `into`: list --> These are the columns of the table that will have a value added.
- `values`: list --> These are the values for each column selected.
### query() --> `search`
This function is used to get values from a table.
```python
hydro.query(
from_="Table_1",
columns=["name", "age"],
where="age = 34"
)
```
```bash
# expected output: [{"id" : 1, "values" :{"name":"James", "age":34}}]
```
**NOTE:** A string is returned
- `table_name`: str --> Is the name of the table to be querried.
- `columns`: list --> Here, is the values you want to receve. If None, the entire row is returned.
- `filter`: str --> Is the parameter to querry a specific group of elements or a single element. If non filter parameter is passed, the entire table will be returned.
### update() --> `update`
The update funcions serves to update values from rows, or a single row.
If you want to update a single row, uses the element `id` as the filter parameter.
```python
hydro.update(
from_="Table_1",
columns=["name", "age"],
where="name = James",
with_values=["Caio", 19],
)
```
```json
// Expectd result
{
"TABLE NAME": "TABLE_1",
"META DATA": null,
"TABLE COLUMNS": [
"name",
"age"
],
"PK": "name",
"ROWS": [
{
"id": 1,
"values":{
"name": "Caio",
"age": 19
}
}
]
}
```
- `table_name`:str --> Is the table to update a row, or a group of rows.
- `columns`:list --> These are the list you want to change of each row querried.
- `where`:str --> Specifies the groupe of elements or a single element to be updated.
- `with_values`:list --> The values to be updated to the current row data.
### delete() --> `delete`
This function removes an entire row from the table that has the specified value passed in.
```python
hydro.delete(
from_="Table_1",
where="id = 1"
)
```
```json
// Expected result
{
"TABLE NAME": "TABLE_1",
"META DATA": null,
"TABLE COLUMNS": [
"name",
"age"
],
"PK": "name",
"ROWS": []
}
```
- `from_`: str --> Is the table to search the row.
- `where`: str --> pecifies the groupe of elements or a single element to be updated.
## Observable Functions
Those are mede to access general data fro the table, like the entire table structure, or the table's rows
### read_table()
This function returns the entire table structure. To use this functions just pass the table name.
```python
hydro.read_table(table_name="TABLE_1")
```
```bash
#Expected output
'{"TABLE NAME": "TABLE_1", "META DATA": null, "TABLE COLUMNS": ["name", "age"], "PK": "name", "ROWS": [{"id": 1, "values":{ "name": "Caio","age": 19}}]}'
```
- `table_name`:str -->Inte the table's name to me readed
### read_rows()
This function returns the entire list of rows in the table, to use, just pass the table's name.
```python
hydro.read_rows(table_name="TABLE_1")
```
```bash
# Expected output as the 'TABLE_1' only has this row
'[{"id": 1, "values":{"name": "Caio","age": 19}}]'
```
- `table_name`:str -->Inte the table's name to me readed
### read_columns()
Used to get the columns in the table. Important to say that ir does not returns data from the rows, just the name of the columns in the table.
```python
hydro.read_columns(table_name="TABLE_1")
```
```bash
# Expected output as the 'TABLE_1' only has those columns
'["name", "age"]'
```
- `table_name`:str -->Inte the table's name to me readed
Raw data
{
"_id": null,
"home_page": null,
"name": "hydrodb",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "db, data_base, back-end",
"author": "Caio Teixeira de Paula",
"author_email": "caio.teixeira.paula@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/87/f1/07c164c2ea40f34b403411e60dca3c6e13f04131aefa8311c540452bc805/hydrodb-1.0.9.tar.gz",
"platform": null,
"description": "# About HydroDB\r\n\r\n`HydroDB` can be a non-relational or a relational database library for Python, designed to be easy to use and agile. It allows you to create `JSON` files and store data in them with desired keys. Additionally, it enables searching, updating, and deleting data within the `JSON` file.\r\n\r\n## Why HydroDB exists?\r\n\r\nThe idea for HydroDB emerged during my college days when I had to use TinyDB in one of my classes. While TinyDB is a good library for non-relational databases, I felt that something was missing. After studying the subject, I decided to create my own non-relational database library.\r\n\r\n## Setting Up\r\n\r\n### Requirements (for versions 1.#.#)\r\n\r\n- [Python 3](https://www.python.org/downloads/) version 3.12.2 or above.\r\n\r\n```bash\r\npip install hydrodb\r\n```\r\n\r\n\r\n## Data structure\r\n\r\nOn HydroDB all `JSON` files has an shered base struct:\r\n\r\n```json\r\n{\r\n \"TABLE NAME\": \"tables-name\",\r\n \"META DATA\": \"tables-meta-data\",\r\n \"TABLE COLUMNS\": [\r\n \"columns_1\",\r\n \"columns_2\",\r\n \"...\",\r\n ],\r\n \"PK\": \"tables-primary-key\",\r\n \"ROWS\": [\r\n {\r\n \"id\": 1,\r\n \"values\": {\r\n \"column_1\": \"x\",\r\n \"columns_2\": null,\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n> - \"TABLE TABME\": string -> Is the name of the table.\r\n>\r\n> - \"META DATA\": string -> Here goes the descriptions of the data tha goes into the table. \r\n>\r\n> - \"TABLE COLUMNS\":array/list -> The columns tha goes into the table.\r\n>\r\n> - \"PK\": string -> Is the columns that represents the primary key of the table.\r\n>\r\n> - \"ROWS\": array/list of dictionaries -> Here goes the rows of the table. Is important to remember that every single row has an id and the values of the row associeted with the table's columns.\r\n\r\n## Observable functions\r\nThose functions are made to lookup the table, for general porpose\r\n\r\n\r\n# Get Started\r\n\r\nHere is a simple guide on how to use the `HydroDB` module.\r\n\r\n## Calling HydroDB in the program\r\n\r\n### Default creation\r\nTo use the module, simply use:\r\n```python\r\nfrom hydrodb import HydroDB\r\n\r\nhydro = HydroDB()\r\n```\r\nIn this case, a directory `db/` will be created at your project folder level:\r\n```\r\nyour-project-folder\r\n |--> db/ \r\n |--> hydrodb/\r\n |--> main.py\r\n```\r\n\r\n### Optional dirpath\r\n`HydroDB` allows you to choose a folder to create the database directory.\r\n\r\nTo do that, use:\r\n```python\r\nfrom hydrodb import HydroDB\r\n\r\nhydro = HydroDB(optional_path='any_dir_name')\r\n```\r\n\r\nIn this case, a directory `db/` will be created at your project folder level:\r\n```\r\nyour-project-folder\r\n |--> any_dir_name\r\n |--> db/\r\n |--> hydrodb/\r\n |--> main.py\r\n```\r\n\r\n## Commands list\r\n\r\nDesigned to be a very user-friendly module, `HydroDB` only has 6 **operational** functions and 3 **observable** functions to be called.\r\n\r\n## Operational Functions\r\n\r\nThe opearional functions are thesigned to execute the CRUD \r\n\r\n- C : create\r\n- R : read\r\n- U : update\r\n- D : delete\r\n\r\n1 of them are to `create`, 1 for `reade`, 3 for `update` and 1 for `delete`.\r\n\r\n \r\n### create_table() --> `create`\r\n\r\nThe create() function is designed for the creation of tables, along with the columns that each table possesses.\r\n\r\n```python \r\nhydro.create_table(\r\n tables=\"Table_1\", \r\n columns=[\"name\", \"age\"],\r\n pk=\"name\"\r\n)\r\n```\r\n\r\n```json\r\n// Expected table structure\r\n{\r\n \"TABLE NAME\": \"TABLE_1\",\r\n \"META DATA\": null,\r\n \"TABLE COLUMNS\": [\r\n \"name\",\r\n \"age\"\r\n ],\r\n \"PK\": \"name\",\r\n \"ROWS\": []\r\n}\r\n```\r\n- `tables`: str --> Na name of the table to be created. (Learn more about [strings](https://www.w3schools.com/python/python_strings.asp))\r\n\r\n- `columns`: Lists --> The columns for the table. (Learn more about [lists](https://www.w3schools.com/python/python_lists.asp))\r\n\r\n- `pk`: str --> Defines the primary key of the table. If no values are passed, the primary-key will be the `id`\r\n\r\n\r\n### add_row() --> `update`\r\n\r\nTo add values to table's columns, uses the add() function.\r\n\r\n```python\r\nhydro.add_rows(\r\n table_name=\"Table_1\",\r\n into_columns=[\"name\", \"age\"],\r\n values=[\"James\", 34]\r\n)\r\n```\r\n```json\r\n// Expected result\r\n{\r\n \"TABLE NAME\": \"TABLE_1\",\r\n \"META DATA\": null,\r\n \"TABLE COLUMNS\": [\r\n \"name\",\r\n \"age\"\r\n ],\r\n \"PK\": \"name\",\r\n \"ROWS\": [\r\n {\r\n \"id\": 1,\r\n \"values\":{\r\n \"name\": \"James\",\r\n \"age\": 34\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n- `tables_names`: str --> Receives the table that you want to add values.\r\n\r\n- `into`: list --> These are the columns of the table that will have a value added.\r\n\r\n- `values`: list --> These are the values for each column selected.\r\n\r\n\r\n### query() --> `search`\r\n\r\nThis function is used to get values from a table.\r\n\r\n\r\n```python\r\nhydro.query(\r\n from_=\"Table_1\",\r\n columns=[\"name\", \"age\"],\r\n where=\"age = 34\"\r\n)\r\n```\r\n\r\n```bash\r\n# expected output: [{\"id\" : 1, \"values\" :{\"name\":\"James\", \"age\":34}}]\r\n```\r\n**NOTE:** A string is returned\r\n\r\n- `table_name`: str --> Is the name of the table to be querried.\r\n\r\n- `columns`: list --> Here, is the values you want to receve. If None, the entire row is returned.\r\n\r\n- `filter`: str --> Is the parameter to querry a specific group of elements or a single element. If non filter parameter is passed, the entire table will be returned.\r\n\r\n\r\n### update() --> `update`\r\n\r\nThe update funcions serves to update values from rows, or a single row.\r\nIf you want to update a single row, uses the element `id` as the filter parameter.\r\n\r\n```python\r\nhydro.update(\r\n from_=\"Table_1\",\r\n columns=[\"name\", \"age\"],\r\n where=\"name = James\",\r\n with_values=[\"Caio\", 19],\r\n)\r\n```\r\n```json\r\n// Expectd result\r\n{\r\n \"TABLE NAME\": \"TABLE_1\",\r\n \"META DATA\": null,\r\n \"TABLE COLUMNS\": [\r\n \"name\",\r\n \"age\"\r\n ],\r\n \"PK\": \"name\",\r\n \"ROWS\": [\r\n {\r\n \"id\": 1,\r\n \"values\":{\r\n \"name\": \"Caio\",\r\n \"age\": 19\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\n- `table_name`:str --> Is the table to update a row, or a group of rows.\r\n\r\n- `columns`:list --> These are the list you want to change of each row querried.\r\n\r\n- `where`:str --> Specifies the groupe of elements or a single element to be updated.\r\n\r\n- `with_values`:list --> The values to be updated to the current row data.\r\n\r\n\r\n### delete() --> `delete`\r\n\r\nThis function removes an entire row from the table that has the specified value passed in.\r\n\r\n```python\r\nhydro.delete(\r\n from_=\"Table_1\",\r\n where=\"id = 1\"\r\n)\r\n```\r\n```json\r\n// Expected result\r\n{\r\n \"TABLE NAME\": \"TABLE_1\",\r\n \"META DATA\": null,\r\n \"TABLE COLUMNS\": [\r\n \"name\",\r\n \"age\"\r\n ],\r\n \"PK\": \"name\",\r\n \"ROWS\": []\r\n}\r\n```\r\n\r\n- `from_`: str --> Is the table to search the row.\r\n\r\n- `where`: str --> pecifies the groupe of elements or a single element to be updated.\r\n\r\n\r\n## Observable Functions\r\nThose are mede to access general data fro the table, like the entire table structure, or the table's rows\r\n\r\n### read_table()\r\nThis function returns the entire table structure. To use this functions just pass the table name.\r\n```python\r\nhydro.read_table(table_name=\"TABLE_1\")\r\n```\r\n```bash\r\n#Expected output\r\n\r\n'{\"TABLE NAME\": \"TABLE_1\", \"META DATA\": null, \"TABLE COLUMNS\": [\"name\", \"age\"], \"PK\": \"name\", \"ROWS\": [{\"id\": 1, \"values\":{ \"name\": \"Caio\",\"age\": 19}}]}'\r\n```\r\n\r\n- `table_name`:str -->Inte the table's name to me readed\r\n\r\n\r\n### read_rows()\r\nThis function returns the entire list of rows in the table, to use, just pass the table's name.\r\n\r\n```python\r\nhydro.read_rows(table_name=\"TABLE_1\")\r\n```\r\n```bash\r\n# Expected output as the 'TABLE_1' only has this row\r\n'[{\"id\": 1, \"values\":{\"name\": \"Caio\",\"age\": 19}}]'\r\n```\r\n\r\n- `table_name`:str -->Inte the table's name to me readed\r\n\r\n\r\n### read_columns()\r\nUsed to get the columns in the table. Important to say that ir does not returns data from the rows, just the name of the columns in the table.\r\n\r\n\r\n```python\r\nhydro.read_columns(table_name=\"TABLE_1\")\r\n```\r\n```bash\r\n# Expected output as the 'TABLE_1' only has those columns\r\n'[\"name\", \"age\"]'\r\n\r\n```\r\n- `table_name`:str -->Inte the table's name to me readed\r\n",
"bugtrack_url": null,
"license": null,
"summary": "# About HydroDB",
"version": "1.0.9",
"project_urls": {
"Download": "https://github.com/CaioTeixeiraDePaula/HydroDB/archive/refs/tags/v1.0.5.zip"
},
"split_keywords": [
"db",
" data_base",
" back-end"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eac1af645b9979d8375e7557ce705b91332bba49cda8cbda4917e8949301b6ac",
"md5": "eceabd29ac5d1b6ab93f6d3da2491ae7",
"sha256": "e96943d9584f9e9980c2d2f4f7f42d4d3fcd40ea021cce6c6cd050859c714535"
},
"downloads": -1,
"filename": "hydrodb-1.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eceabd29ac5d1b6ab93f6d3da2491ae7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6846,
"upload_time": "2024-03-25T14:54:15",
"upload_time_iso_8601": "2024-03-25T14:54:15.826927Z",
"url": "https://files.pythonhosted.org/packages/ea/c1/af645b9979d8375e7557ce705b91332bba49cda8cbda4917e8949301b6ac/hydrodb-1.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "87f107c164c2ea40f34b403411e60dca3c6e13f04131aefa8311c540452bc805",
"md5": "37ce9b76f691a8d74ed8cd387c5b4db0",
"sha256": "7f32ff52a935eefadb76a809439cc50ee8fd301b88bc9959d17defd842dbc43c"
},
"downloads": -1,
"filename": "hydrodb-1.0.9.tar.gz",
"has_sig": false,
"md5_digest": "37ce9b76f691a8d74ed8cd387c5b4db0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8996,
"upload_time": "2024-03-25T14:54:16",
"upload_time_iso_8601": "2024-03-25T14:54:16.935473Z",
"url": "https://files.pythonhosted.org/packages/87/f1/07c164c2ea40f34b403411e60dca3c6e13f04131aefa8311c540452bc805/hydrodb-1.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-25 14:54:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CaioTeixeiraDePaula",
"github_project": "HydroDB",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hydrodb"
}
JSON
