Document API

Documents represent database records. Each document is a (in)complete subset of fields contained in a record. Available data types and query mechanisms are determined by the storage in use.

The API was inspired by Django, MongoKit, WTForms, Svarga and several other projects. It was important to KISS (keep it simple, stupid), DRY (do not repeat yourself) and to make the API as abstract as possible so that it did not depend on backends and yet did not get in the way.

class doqu.document_base.Document(**kw)

A document/query object. Dict-like representation of a document stored in a database. Includes schema declaration, bi-directional validation (outgoing and query), handles relations and has the notion of the saved state, i.e. knows the storage and primary key of the corresponding record.

classmethod contribute_to_query(query)

Returns given query filtered by schema and validators defined for this document.

delete()

Deletes the object from the associated storage.

classmethod from_storage(storage, key, data)

Returns a document instance filled with given data and bound to given storage and key. The instance can be safely saved back using save(). If the concrete subclass defines the structure, then usused fields coming from the storage are hidden from the public API but nevertheless they will be saved back to the database as is.

pk

Returns current primary key (if any) or None.

save(storage=None, keep_key=False)

Saves instance to given storage.

Parameters:

• storage – the storage to which the document should be saved. If not specified, default storage is used (the one from which the document was retrieved of to which it this instance was saved before).
• keep_key – if True, the primary key is preserved even when saving to another storage. This is potentially dangerous because existing unrelated records can be overwritten. You will only need this when copying a set of records that reference each other by primary key. Default is False.

validate()

Checks if instance data is valid. This involves a) checking whether all values correspond to the declated structure, and b) running all Validators against the data dictionary.

Raises ValidationError if something is wrong.

Note

if the data dictionary does not contain some items determined by structure or validators, these items are not checked.

Note

The document is checked as is. There are no side effects. That is, if some required values are empty, they will be considered invalid even if default values are defined for them. The save() method, however, fills in the default values before validating.

doqu.document_base.Many

alias of OneToManyRelation