# How to start using `dstore`
Ready for use , with all BASIC (Create, Read, Update, Delete) operations are supported.
Developed by `Mutiibwa Grace Peter` [🔗](https://gracepeter.pythonanywhere.com/), `Tukasiima Blessing` (c) 2024
---
Report issues at [🔍 dstore-orm repo](https://github.com/GracePeterMutiibwa/dstore-orm/issues)
---
`dstore-orm` is a Sqlite ORM that offers means of saving objects (dictionaries) to the database, making it applicable for less data intensive applications while hiding the complexities of database interactions.
- This `package` aims to make it so easy to get going with saving object structured data for small scale appliactions.
## `Getting started`
Install the package using;
``` python
pip install dstore-orm
```
## `Usage Guide`
1. Creating a `definitions` file
The **definitions file** should have an extension of `.dst`
```markdown
# Inside the the .dst file you can add definitions like;
Student:[name=str, age=int]
```
- `No spaces` should exist between the name of the Table and the colon and the list of field names i.e.
```
Student : [name=str] is Invalid
^ ^
| |
Such spaces are not valid
```
> 
- In the list of fields like `[name=str, age=int]` **no spaces** should exist between the `field name and the type`.
```
Student: [name = str, age=str]
^ ^
| |
Such spaces wont
be recognized
```
---
- Above , `Student` is the name of the table and the list `[name=str]` is a definition of the fields the `Student` table will have
```markdown
# With many tables and many fields
Student:[name=str, age=int]
Color:[name=str, code=str]
```
Suppose the `details.dst` is located in a folder called `learn`
> Note: If the `dst` file is put in a folder, that folder should exist.
---
2. Creating a connection to the `database` in our python file or code via the `definitions` file.
```python
from dstore import SqliteORM
# path to definitions
definition_path = './learn/details.dst'
# connect to the definitions file
datase_connection = SqliteORM().connect(definition_path)
```
> Upon successfull connection;
- The `definitions file` will be `created if its missing`.
- An `sqlite database file with the same name as the definitions file` will be created.
Get meta information about the database created using the `meta` and `definitions` attribute
```python
# display a list of tables as defined in the database
print(datase_connection.meta)
# display the structure of the databse tables
print(datase_connection.definitions)
```
**Note**: Before any operations can be done, ensure that there are `definitions` in your `definitions file` otherwise you `will get an error`.
---
# CRUD OPERATIONS
**Note**: Before any (Create, Read, Update, Delete) operation, a connection to the database must be created.
```python
from dstore import SqliteORM
# definitions
definition_path = 'learn/details.dst'
# create connection
databaseConnection = SqliteORM().connect(definition_path)
```
1. `Saving` objects to the database
> Before any saving operation, an object (`a dictionary`) with fields defined as in the `definitions` file is prepared.
---
- Keys (.i.e. name, age) of the object (dictionary) should match those defined in the definitions file.
- Data types for the values should match to i.e. `'John Doe'` is a string (`str`) and `12` is an integer (`int`)
---
```python
# an object
sampleObject = {
'name': 'John Doe',
'age': 12
}
# save
databaseConnection.save('Student', sampleObject)
```
2. `Reading` data from the database
```python
# fetch all records in `Student` table
data = databaseConnection.fetch("Student")
```
```python
# Get certain fields from the table
# i.e. get only the name field
data = databaseConnection.fetch("Student", ['name'])
print(data)
```
3. `Updating` records in the database
```python
databaseConnection.update("Student", ['age'], [17], ('name', 'John Doe'))
```
> Explanation
|Section|Description|
|---|---|
|`Student`|Name of the table to update|
|`['age']`| A list of fields to replace, if they are `many the format is ['age', 'name']`|
|`[17]`| The replace list containing values for the replace fields, note that the `order matters`, in case they are `many the format is [17, 'Red']`|
|`('name', 'John Doe')`| `'name'` - For all fields to replace, the name field value i.e. 'John Doe' will be looked for, and wherever its found, `fields in that record will be updated with values in the replace list`. |
---
4. `Deleting` records from the database
> Deleting specific record
```python
# data record based on conditions
databaseConnection.delete("Student", [('id', 67)])
```
- `'Student'` - Is the table you want to delete from.
- [`('id', 67)`] - A list containing tuple indicating the fields to look for i.e. `id`, and in case they have the specified values i.e. `67` in the `id` field, then that field will be deleted.
> Deleting (`purging`) all records in a given table.
```python
# delete : all data in table but not the table.
databaseConnection.purge("Student")
```
5. Deleting the whole table from the database
```python
# delete table 'Student' from the database
databaseConnection.drop("Student")
```
**Note**;
- A `wrong table name will raise an error` (ensure the table actuall exists before deleting).
- Deleting the table `does not remove it from the definitions file`.
- Attempting to `save to the table after the table is deleted will re-create` the table.
Raw data
{
"_id": null,
"home_page": "https://github.com/GracePeterMutiibwa/dstore-orm",
"name": "dstore-orm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6.0",
"maintainer_email": null,
"keywords": "python, sqlite3, orm, sqlite3 orm, save objects, save objects in Python",
"author": "The Big Engineer (Mutiibwa Grace Peter), Blessing Tukasiima",
"author_email": "<dstore.orm.helpdesk@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0d/18/f02152eb30753b4a1e329630b004a0cfd460840c90766b5137462e0f8b71/dstore_orm-0.0.1.tar.gz",
"platform": null,
"description": "\r\n\r\n\r\n\r\n\r\n# How to start using `dstore`\r\n\r\n\r\n\r\nReady for use , with all BASIC (Create, Read, Update, Delete) operations are supported.\r\n\r\n\r\n\r\nDeveloped by `Mutiibwa Grace Peter` [\ud83d\udd17](https://gracepeter.pythonanywhere.com/), `Tukasiima Blessing` (c) 2024\r\n\r\n\r\n\r\n---\r\n\r\nReport issues at [\ud83d\udd0d dstore-orm repo](https://github.com/GracePeterMutiibwa/dstore-orm/issues)\r\n\r\n\r\n\r\n---\r\n\r\n`dstore-orm` is a Sqlite ORM that offers means of saving objects (dictionaries) to the database, making it applicable for less data intensive applications while hiding the complexities of database interactions.\r\n\r\n\r\n\r\n- This `package` aims to make it so easy to get going with saving object structured data for small scale appliactions.\r\n\r\n\r\n\r\n## `Getting started`\r\n\r\nInstall the package using;\r\n\r\n``` python\r\n\r\npip install dstore-orm\r\n\r\n```\r\n\r\n\r\n\r\n## `Usage Guide`\r\n\r\n\r\n\r\n1. Creating a `definitions` file\r\n\r\n\r\n\r\nThe **definitions file** should have an extension of `.dst`\r\n\r\n\r\n\r\n```markdown\r\n\r\n# Inside the the .dst file you can add definitions like;\r\n\r\n\r\n\r\nStudent:[name=str, age=int]\r\n\r\n```\r\n\r\n\r\n\r\n- `No spaces` should exist between the name of the Table and the colon and the list of field names i.e.\r\n\r\n\r\n\r\n```\r\n\r\nStudent : [name=str] is Invalid\r\n\r\n ^ ^ \r\n\r\n | |\r\n\r\n\r\n\r\nSuch spaces are not valid\r\n\r\n```\r\n\r\n\r\n\r\n> \r\n\r\n\r\n\r\n- In the list of fields like `[name=str, age=int]` **no spaces** should exist between the `field name and the type`.\r\n\r\n\r\n\r\n```\r\n\r\nStudent: [name = str, age=str]\r\n\r\n ^ ^\r\n\r\n | |\r\n\r\n Such spaces wont\r\n\r\n be recognized\r\n\r\n```\r\n\r\n\r\n\r\n---\r\n\r\n\r\n\r\n- Above , `Student` is the name of the table and the list `[name=str]` is a definition of the fields the `Student` table will have\r\n\r\n\r\n\r\n\r\n\r\n```markdown\r\n\r\n\r\n\r\n# With many tables and many fields\r\n\r\n\r\n\r\nStudent:[name=str, age=int]\r\n\r\n\r\n\r\nColor:[name=str, code=str]\r\n\r\n\r\n\r\n```\r\n\r\n\r\n\r\nSuppose the `details.dst` is located in a folder called `learn`\r\n\r\n\r\n\r\n> Note: If the `dst` file is put in a folder, that folder should exist. \r\n\r\n\r\n\r\n---\r\n\r\n\r\n\r\n\r\n\r\n2. Creating a connection to the `database` in our python file or code via the `definitions` file.\r\n\r\n\r\n\r\n```python\r\n\r\n\r\n\r\nfrom dstore import SqliteORM\r\n\r\n\r\n\r\n\r\n\r\n# path to definitions\r\n\r\ndefinition_path = './learn/details.dst'\r\n\r\n\r\n\r\n# connect to the definitions file\r\n\r\ndatase_connection = SqliteORM().connect(definition_path)\r\n\r\n```\r\n\r\n\r\n\r\n> Upon successfull connection; \r\n\r\n- The `definitions file` will be `created if its missing`.\r\n\r\n\r\n\r\n- An `sqlite database file with the same name as the definitions file` will be created.\r\n\r\n\r\n\r\nGet meta information about the database created using the `meta` and `definitions` attribute\r\n\r\n```python\r\n\r\n\r\n\r\n# display a list of tables as defined in the database\r\n\r\nprint(datase_connection.meta)\r\n\r\n\r\n\r\n# display the structure of the databse tables\r\n\r\nprint(datase_connection.definitions)\r\n\r\n```\r\n\r\n\r\n\r\n**Note**: Before any operations can be done, ensure that there are `definitions` in your `definitions file` otherwise you `will get an error`.\r\n\r\n\r\n\r\n---\r\n\r\n\r\n\r\n# CRUD OPERATIONS\r\n\r\n\r\n\r\n**Note**: Before any (Create, Read, Update, Delete) operation, a connection to the database must be created.\r\n\r\n\r\n\r\n```python\r\n\r\nfrom dstore import SqliteORM\r\n\r\n\r\n\r\n# definitions\r\n\r\ndefinition_path = 'learn/details.dst'\r\n\r\n\r\n\r\n# create connection\r\n\r\ndatabaseConnection = SqliteORM().connect(definition_path)\r\n\r\n```\r\n\r\n\r\n\r\n1. `Saving` objects to the database\r\n\r\n\r\n\r\n> Before any saving operation, an object (`a dictionary`) with fields defined as in the `definitions` file is prepared.\r\n\r\n---\r\n\r\n\r\n\r\n\r\n\r\n- Keys (.i.e. name, age) of the object (dictionary) should match those defined in the definitions file.\r\n\r\n\r\n\r\n- Data types for the values should match to i.e. `'John Doe'` is a string (`str`) and `12` is an integer (`int`)\r\n\r\n---\r\n\r\n\r\n\r\n```python\r\n\r\n# an object\r\n\r\nsampleObject = {\r\n\r\n 'name': 'John Doe',\r\n\r\n 'age': 12\r\n\r\n}\r\n\r\n\r\n\r\n# save\r\n\r\ndatabaseConnection.save('Student', sampleObject)\r\n\r\n```\r\n\r\n\r\n\r\n2. `Reading` data from the database\r\n\r\n\r\n\r\n```python\r\n\r\n\r\n\r\n# fetch all records in `Student` table\r\n\r\ndata = databaseConnection.fetch(\"Student\")\r\n\r\n\r\n\r\n```\r\n\r\n\r\n\r\n```python\r\n\r\n# Get certain fields from the table\r\n\r\n# i.e. get only the name field\r\n\r\ndata = databaseConnection.fetch(\"Student\", ['name'])\r\n\r\n\r\n\r\nprint(data)\r\n\r\n```\r\n\r\n\r\n\r\n3. `Updating` records in the database\r\n\r\n```python\r\n\r\ndatabaseConnection.update(\"Student\", ['age'], [17], ('name', 'John Doe'))\r\n\r\n```\r\n\r\n\r\n\r\n> Explanation\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n|Section|Description|\r\n\r\n|---|---|\r\n\r\n|`Student`|Name of the table to update|\r\n\r\n|`['age']`| A list of fields to replace, if they are `many the format is ['age', 'name']`|\r\n\r\n|`[17]`| The replace list containing values for the replace fields, note that the `order matters`, in case they are `many the format is [17, 'Red']`|\r\n\r\n|`('name', 'John Doe')`| `'name'` - For all fields to replace, the name field value i.e. 'John Doe' will be looked for, and wherever its found, `fields in that record will be updated with values in the replace list`. |\r\n\r\n\r\n\r\n---\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n4. `Deleting` records from the database\r\n\r\n> Deleting specific record\r\n\r\n```python\r\n\r\n# data record based on conditions\r\n\r\ndatabaseConnection.delete(\"Student\", [('id', 67)])\r\n\r\n```\r\n\r\n\r\n\r\n- `'Student'` - Is the table you want to delete from.\r\n\r\n\r\n\r\n- [`('id', 67)`] - A list containing tuple indicating the fields to look for i.e. `id`, and in case they have the specified values i.e. `67` in the `id` field, then that field will be deleted.\r\n\r\n\r\n\r\n> Deleting (`purging`) all records in a given table.\r\n\r\n\r\n\r\n```python\r\n\r\n# delete : all data in table but not the table.\r\n\r\ndatabaseConnection.purge(\"Student\")\r\n\r\n```\r\n\r\n\r\n\r\n5. Deleting the whole table from the database\r\n\r\n```python\r\n\r\n# delete table 'Student' from the database\r\n\r\ndatabaseConnection.drop(\"Student\")\r\n\r\n```\r\n\r\n\r\n\r\n**Note**;\r\n\r\n- A `wrong table name will raise an error` (ensure the table actuall exists before deleting).\r\n\r\n\r\n\r\n- Deleting the table `does not remove it from the definitions file`.\r\n\r\n\r\n\r\n- Attempting to `save to the table after the table is deleted will re-create` the table.\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple ORM for Sqlite3",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/GracePeterMutiibwa/dstore-orm"
},
"split_keywords": [
"python",
" sqlite3",
" orm",
" sqlite3 orm",
" save objects",
" save objects in python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "260ff63e07ccc500199528515dcffbcee4d2950e5aa16517a6cb18b57ead01e7",
"md5": "1cd04b3f1e8d4797b42698f07520e780",
"sha256": "89c1f8fcbaaafacfb7800be830353add455b88edf4fdb4b03fb42341bfc0bea4"
},
"downloads": -1,
"filename": "dstore_orm-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1cd04b3f1e8d4797b42698f07520e780",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6.0",
"size": 11529,
"upload_time": "2024-11-11T22:23:02",
"upload_time_iso_8601": "2024-11-11T22:23:02.197051Z",
"url": "https://files.pythonhosted.org/packages/26/0f/f63e07ccc500199528515dcffbcee4d2950e5aa16517a6cb18b57ead01e7/dstore_orm-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0d18f02152eb30753b4a1e329630b004a0cfd460840c90766b5137462e0f8b71",
"md5": "1b20400de9ada2de40c8c9ec6514ed1f",
"sha256": "14dbea702fd5670c7ef0aecc5d593768ac83e6b537c91f703435bdcdf285afc0"
},
"downloads": -1,
"filename": "dstore_orm-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "1b20400de9ada2de40c8c9ec6514ed1f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.0",
"size": 13318,
"upload_time": "2024-11-11T22:23:03",
"upload_time_iso_8601": "2024-11-11T22:23:03.524895Z",
"url": "https://files.pythonhosted.org/packages/0d/18/f02152eb30753b4a1e329630b004a0cfd460840c90766b5137462e0f8b71/dstore_orm-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-11 22:23:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GracePeterMutiibwa",
"github_project": "dstore-orm",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "dstore-orm"
}
JSON
