CookieBD database documentation

This document has the documentation for version 7.0.0 of CookieDB, check the file CHANGELOG.md to see all changes to the project.

Using CookieDB

See here a tutorial on how to use CookieDB in an easy and objective way.

Manipulation

To manipulate the database, you must instantiate the CookieDB class passing (or not) some arguments, such as:

1. key: Any text can be used as a key, of any size;
2. database_local: directory where the database will be or is, if nothing is past, the current directory will be used;

It is not possible to access a database created in versions smaller than 7.0.0 in this version. In previous versions, CookieDB used the cryptography library to encrypt the database. As of version 7.0.0, another type of encryption is used.

from cookiedb import CookieDB

cookiedb = CookieDB(key='secret')

After that, you can perform any operation.

Creating a database

To create a database, use the CookieDB.create_database method, passing (or not) some arguments:

1. database: name of the database;
2. if_not_exists: optional parameter, if the database does not exist, no error It will be released.

from cookiedb import CookieDB

cookiedb = CookieDB(key='secret')
cookiedb.create_database('MyDatabase')

Opening a database

It is only possible to open a database if it exists, otherwise a exception will be thrown. There is no secret to open, just use the CookieDB.open method:

from cookiedb import CookieDB

cookiedb = CookieDB(key='secret')
cookiedb.open('MyDatabase')

All CookieDB database files (from version 1.0.0) have a .cookiedb extension, when opening a database, CookieDB will look for the database name along with the .cookiedb extension (e.g. MyDatabase.cookiedb).

If you create a database using one key and try to open it using another, InvalidDatabaseKeyError exception will be thrown. Furthermore, if no database is open and write, read, update, or delete operations are performed, the NoOpenDatabaseError exception will be thrown.

Closing a database

To close a database, use the close method of the CookieDB class. If you use this method when no database is open, the NoDatabaseOpenError exception will be thrown.

from cookiedb import CookieDB

cookiedb = CookieDB(key='secret')
cookiedb.open('MyDatabase')

# ...performing operations on the database...

# close the database
cookiedb.close()

Checking database

If you want to know which database it is in, use the CookieDB.checkout method:

from cookiedb import CookieDB

cookiedb = CookieDB(key='secret')
cookiedb.open('MyDatabase')
cookiedb.checkout()  # output: MyDatabase

If no database are open, None will be returned.

Creating item

An “item” is an object in the database, which can be a dictionary, list, string, integer or float. The path can be just a string or an integer.

To create an item, we use the CookieDB.add method, which has the following parameters:

1. path: path of the item (where its value will be stored);
2. value: item value.

from cookiedb import CookieDB

cookiedb = CookieDB(key='secret')
cookiedb.open('MyDatabase')

cookiedb.add('languages', {
    'python': {
        'extension': '.py',
        'creator': 'Guido van Rossum'
    },
    'cpp': {
        'extension': '.cpp',
        'creator': 'Bjarne Stroustrup'
    }
})

Each path, separated by “/” (slash), is a key in the JSON file, creating an organized structure, see the example:

path = 'languages/python'

# equivalent to:

json = {
    'languages': {
        'python': {}
    }
}

Getting an item

To get an item, use the CookieDB.get method passing the argument path with the path of the item:

from cookiedb import CookieDB

cookiedb = CookieDB(key='secret')
cookiedb.open('MyDatabase')

languages = cookiedb.get('languages')
print(languages)

# or, get an item inside that item

python_info = cookiedb.get('languages/python')
print(python_info)

That is, you can get data through the path as long as the content is a dictionary (key and value).

Updating an item

To update an item, use the CookieDB.update method. This method will only update existing items, if it doesn’t exist the exception ItemNotExistsError will be thrown:

from cookiedb import CookieDB

cookiedb = CookieDB(key='secret')
cookiedb.open('MyDatabase')

cookiedb.add('languages', {
    'python': {
        'extension': '.py',
        'creator': 'Unknown'
    },
    'cpp': {
        'extension': '.cpp',
        'creator': 'Bjarne Stroustrup'
    }
})

# updating python language name
cookiedb.update('languages/python/creator', 'Guido van Rossum')

Deleting an item

To delete an item, use the CookieDB.delete method passing the path that will be deleted:

from cookiedb import CookieDB

cookiedb = CookieDB(key='secret')
cookiedb.open('MyDatabase')

languages = cookiedb.get('languages')
print(languages)

# delete item
cookiedb.delete('languages/python')

# updated items
languages = cookiedb.get('languages')
print(languages)

With that, just specify the path and you can delete whatever you want.