Like this project? it on

The Backend

The backend provides the main interface to the database and is responsible for retrieving, storing and deleting objects. The class documented here is an abstract base class that gets implemented by the specific backends. Functionality can vary between different backends, e.g. database transactions will not be supported by all backends.

class blitzdb.backends.base.Backend(autodiscover_classes=True, autoload_embedded=True, allow_documents_in_query=True)

Abstract base class for all backend implementations. Provides operations for querying the database, as well as for storing, updating and deleting documents.

Parameters:autodiscover_classes – If set to True, document classes will be discovered automatically, using a global list of all classes generated by the Document metaclass.

The `Meta` attribute

As with blitzdb.document.Document, the Meta attribute can be used to define certain class-wide settings and properties. Redefine it in your backend implementation to change the default values.

autodiscover_classes()

Registers all document classes that have been defined in the code so far. The discovery mechanism works by reading the value of blitzdb.document.document_classes, which is updated by the meta-class of the blitzdb.document.Document class upon creation of a new subclass.

autoregister(cls)

Autoregister a class that is encountered for the first time.

Parameters:cls – The class that should be registered.

delete(obj)

Deletes an object from the database.

Parameters:obj – The object to be deleted.

deserialize(obj, encoders=None, embedded=False, create_instance=True)

Deserializes a given object, i.e. converts references to other (known) Document objects by lazy instances of the corresponding class. This allows the automatic fetching of related documents from the database as required.

Parameters:obj – The object to be deserialized. Returns:The deserialized object.

filter(cls, **kwargs)

Filter objects from the database that correspond to a given set of properties.

Parameters:

• cls – The class for which to filter objects from the database.
• properties – The properties used to filter objects.

Returns:

A blitzdb.queryset.QuerySet instance containing the keys of the objects matching the query.

Functionality might differ between backends

Please be aware that the functionality of the filter function might differ from backend to backend. Consult the documentation of the given backend that you use to find out which queries are supported.

get(cls, properties)

Abstract method to retrieve a single object from the database according to a list of properties.

Parameters:

• cls – The class for which to return an object.
• properties – The properties of the object to be returned

Returns:

An instance of the requested object.

Exception Behavior

Raises a blitzdb.document.Document.DoesNotExist exception if no object with the given properties exists in the database, and a blitzdb.document.Document.MultipleObjectsReturned exception if more than one object in the database corresponds to the given properties.

register(cls, parameters=None, overwrite=False)

Explicitly register a new document class for use in the backend.

Parameters:

• cls – A reference to the class to be defined
• parameters – A dictionary of parameters. Currently, only the collection parameter is used to specify the collection in which to store the documents of the given class.

Registering classes

If possible, always use autodiscover_classes = True or register your document classes beforehand using the register function, since this ensures that related documents can be initialized appropriately. For example, suppose you have a document class Author that contains a list of references to documents of class Book. If you retrieve an instance of an Author object from the database without having registered the Book class, the references to that class will not get parsed properly and will just show up as dictionaries containing a primary key and a collection name.

Also, when blitzdb.backends.base.Backend.autoregister() is used to register a class, you can’t pass in any parameters to customize e.g. the collection name for that class (you can of course do this throught the Meta attribute of the class)

## Inheritance

If register encounters a document class with a collection name that overlaps with the collection name of an already registered document class, it checks if the new class is a subclass of the one that is already register. If yes, it associates the new class to the collection name. Otherwise, it leaves the collection associated to the already registered class.

save(obj, cache=None)

Abstract method to save a Document instance to the database.

Parameters:

• obj – The object to be stored in the database.
• cache – Whether to performed a cached save operation (not supported by all backends).

serialize(obj, convert_keys_to_str=False, embed_level=0, encoders=None, autosave=True, for_query=False, path=None)

Serializes a given object, i.e. converts it to a representation that can be stored in the database. This usually involves replacing all Document instances by database references to them.

Parameters:

• obj – The object to serialize.
• convert_keys_to_str – If True, converts all dictionary keys to string (this is e.g. required for the MongoDB backend)
• embed_level – If embed_level > 0, instances of Document classes will be embedded instead of referenced. The value of the parameter will get decremented by 1 when calling serialize on child objects.
• autosave – Whether to automatically save embedded objects without a primary key to the database.
• for_query – If true, only the pk and __collection__ attributes will be included in document references.

Returns:

The serialized object.