CookieBD database documentation

This document has the documentation for version 9.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 some arguments, such as:

1. key: Any text can be used as a key, of any size;
2. database: Database path/name.

It is not possible to access databases created in versions lower than 9.0.0. This version has a different storage method, making it impossible to access banks that were created using other versions.

from cookiedb import CookieDB

cookiedb = CookieDB('MyDatabase', key='secret')

By creating an instance of the CookieDB class, you are now ready to write and read data. The database will be created automatically if it does not exist. If you create a database using one key and try to open it using another, InvalidDatabaseKeyError exception will be thrown.

Creating item

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

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('MyDatabase', key='secret')

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

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('MyDatabase', key='secret')

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('MyDatabase', key='secret')

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')

Append a item to a list

If you need to add a new item to a list saved in the database, use the append() method to do this. Here is an example:

from cookiedb import CookieDB

cookiedb = CookieDB('MyDatabase', key='secret')

# create "products/" item as a list
cookiedb.add('products/', [
    {
        'name': 'Banana',
        'price': 3.25
    }
])

# add new product in "products/"
cookiedb.append('products/', {
    'name': 'Cookie',
    'price': 2.50
})

cookiedb.get('products/')

If you use the append() method on a path where the item is not a list, the exception ItemIsNotAListError will be thrown. If the specified path does not exist, it will be created automatically containing a list.

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('MyDatabase', key='secret')

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.