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):
        primary_key = 'name' #use the name of the author as the primary key
class blitzdb.document.Document(attributes=None, lazy=False, backend=None, autoload=True, db_loader=None)[source]

The Document object is the base class for all documents stored in the database. The name of the collection can be set by defining a Document.Meta class within the class and setting its collection attribute.

Parameters:
  • attributes – the attributes of the document instance. Expects a Python dictionary.
  • lazy – if set to True, will lazily load the document from the backend when an attribute is requested. This requires that backend has been specified and that the pk attribute is set.
  • backend – the backend to be used for saving and loading the document.

The `Meta` attribute

You can use the Meta attribute of the class to specify the primary_key (defaults to pk) or change the collection name for a given class.

example:

class Actor(Document):

    class Meta(Document.Meta):
        pk = 'name'
        collection = 'hollywood_actors'

Accessing Document Attributes

Document attributes are accessible as class attributes:

marlon = Actor({'name' : 'Marlon Brando', 'birth_year' : 1924})

print("%s was born in %d" % (marlon.name,marlon.birth_year))

In case one of your attributes shadows a class attribute or function, you can still access it using the attributes attribute.

example:

fail = Document({'delete': False,'save' : True})

print(fail.delete) #will print <bound method Document.save ...>

print(fail.attributes['delete']) #will print 'False'

Defining “non-database” attributes

Attributes that begin with an underscore (_) will not be stored in the attributes() dictionary but as normal instance attributes of the document. This is useful if you need to define e.g. some helper variables that you don’t want to store in the database.

__eq__(other)[source]

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
autogenerate_pk()[source]

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.uuid4().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)[source]

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()[source]

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, implicit=False)[source]

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.
  • implicit – whether the loading was triggered implicitly (e.g. by accessing attributes)

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)[source]

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.