https://github.com/reala10n/simplejsondb
Create a simple JSON database with just one line of code!
https://github.com/reala10n/simplejsondb
data database db easy json python simple
Last synced: 8 months ago
JSON representation
Create a simple JSON database with just one line of code!
- Host: GitHub
- URL: https://github.com/reala10n/simplejsondb
- Owner: RealA10N
- License: mit
- Created: 2021-01-28T14:06:34.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-09-10T23:15:16.000Z (almost 3 years ago)
- Last Synced: 2025-02-08T01:30:40.860Z (over 1 year ago)
- Topics: data, database, db, easy, json, python, simple
- Language: Python
- Homepage:
- Size: 166 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Do you need a simple, small, and very easy to use local database? You have come
to the right place! with _simplejsondb_ you can create a simple JSON database with
only one line of code, and we will take care of the rest!
- [A basic example](#a-basic-example)
- [Installation](#installation)
- [The `Database` object](#the-database-object)
- [`Database` constructor](#database-constructor)
- [Database.data](#databasedata)
- [Database.save(**additional)](#databasesaveadditional)
- [Database.load()](#databaseload)
- [Database.path](#databasepath)
- [Database.folder](#databasefolder)
- [The `DatabaseFolder` object](#the-databasefolder-object)
- [`DatabaseFolder` constructor](#databasefolder-constructor)
- [Examples](#examples)
## A basic example
```python
from simplejsondb import Database
# If database named 'translations' doesn't exist yet, creates a new empty dict database
translations = Database('translations.json', default=dict())
# Now, we can treat the database instance as a dictionary!
translations.data['Hello'] = 'Hola'
translations.data['Goodbye'] = 'Adiós'
print(translations.data.values()) # dict_values(['Hola', 'Adiós'])
# The database will automatically save the changes when the program exits
```
After running the code above for the first time, a file named `translations.json`
will be automatically created under the current working directory. Then, we will
be able to use the database inside other scripts, and treat it as a dictionary:
```python
from simplejsondb import Database
# loads the previously saved translations database
translations = Database('translations.json')
# Again, we treat the 'translations' instance as a dictionary
print(f"Hello in Spanish is {translations.data['Hello']}!")
# This will output: Hello in Spanish is Hola!
# We can also use the built in dictionary methods
for english, spanish in translations.data.items():
print(f"{english} in Spanish is {spanish}!")
# This will output:
# Hello in Spanish is Hola!
# Goodbye in Spanish is Adiós!
```
## Installation
The simplest way to install _simplejsondb_ is by using `pip`. Just run the following
command in your terminal:
```console
$ (sudo) pip install simplejsondb
```
You can also clone the [Github repo](https://github.com/RealA10N/simplejsondb),
download the latest release from [Github](https://github.com/RealA10N/simplejsondb/releases)
or directly from [PyPI](https://pypi.org/project/simplejsondb/#files). Then, unzip
the files (if they are zipped), and use the following command to install the package:
```console
$ (sudo) python setup.py install
```
If the command above didn't work, make sure that you have the `setuptools` package
installed using:
```console
$ (sudo) pip install setuptools
```
## The `Database` object
Each instance of the `Database` object is represented by a single json file in
the local storage.
### `Database` constructor
The constructor of the `Database` instance. Receives a path to a `JSON` file, and
tries to load it. If the file doesn't exist, loads the default data that is passed
using the `default` argument.
### Arguments
- **path (str):** The path to the json database file.
- **default:** The default data that will be loaded if the file doesn't exist yet.
`None` by default.
- **save_at_exit (bool):** If `True` (default), will automatically dump the database
into storage when the program exits.
### Database.data
A property that stores the data in the database. Writing and reading data should
be done directly using this property.
### Database.save(**additional)
By default, the database is loaded from the local storage when the instance is
created. It is then saved in the memory, until the program exits - and only then
the new and updated data is saved back in the local storage. By using the
`Database.save()` method, you can save the database into the local storage before
the program exists, in any given point.
#### Additional arguments
The `save` method supports receiving additional keyword arguments that are directly
passed into the `json.dump` function. One useful argument can be `indent` that is
a non-negative integer that sets the indention level of the dumped json file. For
more information, check out the [json module documentation].
### Database.load()
Loads the data from the `json` file into the instance. Overwrites previous data that was
saved under the `.data` property.
### Database.path
A property that contains the path to the database JSON file.
### Database.folder
A property that stores the absolute path to the directory where the database json
file lives in.
## The `DatabaseFolder` object
In larger projects, you may want to separate your database into multiple `json`
files under the same directory. for that, it is possible to use the `DatabaseFolder`
object, that lets you easily manage multiple `json` files, without dealing with
different instances of the `Database` object.
### `DatabaseFolder` constructor
The constructor receives a path to a directory, and stores the it for later.
#### Arguments
- **folder (str):** A path to a folder in the storage in which the database folder
will live.
- **default_factory (callable):** A function that receives a string that represents
the name of a database file, and returns the default value for the file.
The default value is the following lambda function `lambda _: None` which will
return `None` no matter what the name of the file is.
- **save_at_exit (bool):** If `True` (default), will automatically dump the database
into storage when the program exits.
### Examples
```python
from simplejsondb import DatabaseFolder
# Create a database under the 'db' folder
# The default value in the files will be a list
db = DatabaseFolder('db', default_factory=lambda _: list())
# Append 'hello' in the 'db/file1.json'
db['file1'].append('hello')
# 'db/file2.json' will store a dictionary
db['file2'] = dict()
db['file2']['hello'] = 'there!'
print(db['file2']) # {'hello': 'there!'}
```
[json module documentation]: https://docs.python.org/3/library/json.html#json.dump