Like this project? it on

The Document

The Document class is the base for all documents stored in the database. To create a new document type, just create a class that inherits from this base class:

from blitzdb import Document

class Author(Document):
    pass

From document classes to collections

Internally, Blitz stores document attributes in collections, which it distinguishes based by name. By default, the name of a collection will be the lowercased name of the corresponding class (e.g. author for the Author class above). You can override this behavior by setting the collection attribute in the document class’ Meta class attribute:

class Author(Document):

    class Meta(Document.Meta):
        collection = 'fancy_authors'

Likewise, you can also change the name of the attribute to be used as primary key for this document class, which defaults to pk:

class Author(Document):

    class Meta(Document.Meta):
        pk = 'name' #use the name of the author as the primary key

class blitzdb.document.Document(attributes=None, lazy=False, default_backend=None, autoload=True)

__eq__(other)

Compares the document instance to another object. The comparison rules are as follows:

• If the Python id of the objects are identical, return True
• If the types of the objects differ, return False
• If the types match and the primary keys are identical, return True
• If the types and attributes of the objects match, return True
• Otherwise, return False

attributes

Returns a reference to the attributes of the document. The attributes are the “unique source of truth” about the state of a document.

autogenerate_pk()

Autogenerates a primary key for this document. This function gets called by the backend if you save a document without a primary key field. By default, it uses uuid.uuid1().hex to generate a (statistically) unique primary key for the object (more about UUIDs). If you want to define your own primary key generation mechanism, just redefine this function in your document class.

delete(backend=None)

Deletes a document from the database. If the backend argument is not specified, the function resorts to the default backend as defined during object instantiation. If no such backend is defined, an AttributeError exception will be thrown.

Parameters:backend – the backend from which to delete the document.

initialize()

Gets called when after the object attributes get loaded from the database. Redefine it in your document class to perform object initialization tasks.

Keep in Mind

The function also get called after invoking the revert function, which resets the object attributes to those in the database, so do not assume that the function will get called only once during the lifetime of the object.

Likewise, you should not perform any initialization in the __init__ function to initialize your object, since this can possibly break lazy loading and revert operations.

pk

Returns (or sets) the primary key of the document, which is stored in the attributes dict along with all other attributes. The name of the primary key defaults to pk and can be redefine in the Meta class. This function provides a standardized way to retrieve and set the primary key of a document and is used by the backend and a few other classes. If possible, always use this function to access the primary key of a document.

Automatic primary key generation

If you save a document to the database that has an empty primary key field, Blitz will create a default primary-key by calling the autogenerate_pk function of the document. To generate your own primary keys, just redefine this function in your derived document class.

revert(backend=None)

Reverts the state of the document to that contained in the database. If the backend argument is not specified, the function resorts to the default backend as defined during object instantiation. If no such backend is defined, an AttributeError exception will be thrown.

Parameters:backend – the backend from which to delete the document.

Keep in Mind

This function will call the initialize function after loading the object, which allows you to perform document-specific initialization tasks if needed.

save(backend=None)

Saves a document to the database. If the backend argument is not specified, the function resorts to the default backend as defined during object instantiation. If no such backend is defined, an AttributeError exception will be thrown.

Parameters:backend – the backend in which to store the document.