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.
Base class for document schemata.
Wrapper for a record with predefined metadata.
Usage:
>>> from doqu import Document
>>> from doqu.validators import AnyOf
>>> class Note(Document):
... structure = {
... 'text': unicode,
... 'is_note': bool,
... }
... defaults = {
... 'is_note': True,
... }
... validators = {
... 'is_note': [AnyOf([True])],
... }
...
... def __unicode__(self):
... return u'{text}'.format(**self)
To save model instances and retrieve them you will want a storage:
>>> from doqu import get_db
>>> db = get_db(backend='doqu.ext.tokyo_tyrant', port=1983)
# and another one, just for testing (yep, the real storage is the same)
>>> other_db = get_db(backend='doqu.ext.tokyo_tyrant', port=1983)
# let's make sure the storage is empty
>>> db.clear()
See documentation on methods for more details.
Returns the document as an instance of another model. Copies attributes of current instance that can be applied to another model (i.e. only overlapping attributes – ones that matter for both models). All other attributes are re-fetched from the database (if we know the key).
Note
The document key is preserved. This means that the new instance represents the same document, not a new one. Remember that models are “views”, and to “convert” a document does not mean copying; it can however imply adding attributes to the existing document.
Neither current instance nor the returned one are saved automatically. You will have to do it yourself.
Please note that trying to work with the same document via different instances of models whose properties overlap can lead to unpredictable results: some properties can be overwritten, go out of sync, etc.
| Parameters: |
|
|---|
Usage:
>>> class Contact(Note):
... structure = {'name': unicode}
... validators = {'name': [required()]} # merged with Note's
...
... def __unicode__(self):
... return u'{name} ({text})'.format(**self)
>>> note = Note(text='phone: 123-45-67')
>>> note
<Note phone: 123-45-67>
# same document, contact-specific data added
>>> contact = note.convert_to(Contact, {'name': 'John Doe'})
>>> contact
<Contact John Doe (phone: 123-45-67)>
>>> contact.name
'John Doe'
>>> contact.text
'phone: 123-45-67'
# same document, contact-specific data ignored
>>> note2 = contact.convert_to(Note)
>>> note2
<Note phone: 123-45-67>
>>> note2.name
Traceback (most recent call last):
...
AttributeError: 'Note' object has no attribute 'name'
>>> note2.text
'phone: 123-45-67'
Deletes the object from the associated storage.
Returns an instance of given document class associated with a record stored with given primary key in given storage. Usage:
event = Event.object(db, key)
| Parameters: |
|
|---|
Returns a query for records stored in given storage and associates with given document class. Usage:
events = Event.objects(db)
| Parameters: |
|
|---|
Returns current primary key (if any) or None.
Saves instance to given storage.
| Parameters: |
|
|---|
Saves the document under another key (specified as key or generated) and returns the newly created instance.
| Parameters: |
|
|---|
See save() for details on other params.
Usage:
>>> db.clear()
>>> note = Note(text="hello") # just create the item
# WRONG:
>>> note.save() # no storage; don't know where to save
Traceback (most recent call last):
...
AttributeError: cannot save model instance: storage is not defined neither in instance nor as argument for the save() method
>>> note.save_as() # same as above
Traceback (most recent call last):
...
AttributeError: cannot save model instance: storage is not defined neither in instance nor as argument for the save() method
# CORRECT:
>>> new_key = note.save(db) # storage provided, key generated
>>> new_key
u'1'
>>> new_obj = note.save_as(storage=db) # same as above
>>> new_obj
<Note hello>
>>> new_obj.pk # new key
u'2'
>>> new_obj.text # same data
'hello'
>>> new_key = note.save() # same storage, same key
>>> new_key
u'1'
>>> new_obj = note.save_as() # same storage, autogenerated new key
>>> new_obj.pk
u'3'
>>> new_obj = note.save_as('custom_key') # same storage, key "123"
>>> new_obj.pk
'custom_key'
>>> note.save_as(123, other_db) # other storage, key "123"
<Note hello>
>>> note.save_as(storage=other_db) # other storage, autogenerated new key
<Note hello>
Warning
Current implementation may lead to data corruption if the document comes from one database and is being saved to another one, managed by a different backend. Use with care.
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.
alias of OneToManyRelation