Learn how to use the CookieDB database with the complete documentation.
This document has the documentation for version 8.0.0
of CookieDB, check the file CHANGELOG.md to see all changes to the project.
See here a tutorial on how to use CookieDB in an easy and objective way.
To manipulate the database, you must instantiate the CookieDB
class passing some arguments, such as:
key
: Any text can be used as a key, of any size;database
: Database path/name.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 version7.0.0
, another type of encryption is used.
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.
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:
path
: path of the item (where its value will be stored);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'
}
})
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': {}
}
}
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).
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')
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/')
# result:
# [
# {
# 'name': 'Banana',
# 'price': 3.25
# },
# {
# 'name': 'Cookie',
# 'price': 2.50
# }
# ]
If you use the append()
method on a path where the item is not a list, the exception ItemIsNotAListError
will be thrown.
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.