simplejsondb

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
• Installation
• The Database object
  • Database constructor
  • Database.data
  • Database.save(**additional)
  • Database.load()
  • Database.path
  • Database.folder
• The DatabaseFolder object
  • DatabaseFolder constructor
  • Examples

A basic example

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:

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:

$ (sudo) pip install simplejsondb

You can also clone the Github repo, download the latest release from Github or directly from PyPI. Then, unzip the files (if they are zipped), and use the following command to install the package:

$ (sudo) python setup.py install

If the command above didn't work, make sure that you have the setuptools package installed using:

$ (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

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!'}