Installation¶

DOCKIT_BACKENDS = {
    'default': {
        'ENGINE': 'dockit.backends.djangodocument.backend.ModelDocumentStorage',
    }
}
DOCKIT_INDEX_BACKENDS = {
    'default': {
        'ENGINE': 'dockit.backends.djangodocument.backend.ModelIndexStorage',
    },
}

#Uncomment to use django-ztask for indexing
#DOCKIT_INDEX_BACKENDS['default']['INDEX_TASKS'] = 'dockit.backends.djangodocument.tasks.ZTaskIndexTasks'

#Uncomment to use django-celery for indexing
#DOCKIT_INDEX_BACKENDS['default']['INDEX_TASKS'] = 'dockit.backends.djangodocument.tasks.CeleryIndexTasks'

DOCKIT_BACKENDS = {
    'default': {
        'ENGINE':'dockit.backends.mongo.backend.MongoDocumentStorage',
        'USER':'travis',
        'PASSWORD':'test',
        'DB':'mydb_test',
        'HOST':'127.0.0.1',
        'PORT':27017,
    }
}
DOCKIT_INDEX_BACKENDS = {
    'default': {
        'ENGINE':'dockit.backends.mongo.backend.MongoIndexStorage',
        'USER':'travis',
        'PASSWORD':'test',
        'DB':'mydb_test',
        'HOST':'127.0.0.1',
        'PORT':27017,
    },
}

Hyperadmin¶

The primary way to use dockit with an Admin interface and APIs is to use Django-Hyperadmin. Install django-hyperadmin-dockitresource (https://github.com/zbyte64/django-hyperadmin-dockitresource) to start using DocKit with Hyperadmin.

Creating Indexes¶

Creating indexes in dockit is allot like constructing a django query except that no joins are currently allowed. After constructing a query, calling commit() ensures that the database has an index covering the criteria you supplied.

Examples:

#to create the index
MyDocument.objects.filter(published=True).commit()
#to use the index
for doc in MyDocument.objects.filter(published=True):
    print doc

#create an index for published documents that index the slug field
MyDocument.objects.filter(published=True).index('slug').commit()
#to use the index
MyDocument.objects.filter(published=True).get(slug='this-slug')

#index with a date
MyDocument.objects.filter(published=True).index('publish_date')

MyDocument.objects.filter(published=True).filter(publish_date__lte=datetime.datetime.now())

Views¶

Dockit provides all the generic class based views that django provides but re-tooled for documents.

TODO

Validation¶

Documents and Schemas support validation that mimics Django’s models. Given a document instance you may call full_clean to validate the document structure and have a ValidationError raised if the document does not conform. Documents and schemas may define their own clean_<fieldname> method to validate each entry and a clean method to validate the entire document. All validation errors are to be sublcassed from django.core.exceptions.ValidationError.

To run through the document validation run full_clean:

try:
    mydocument.full_clean()
except ValidationError as e:
    print e
    raise

Adding custom validation to a document:

class MyDocument(schema.Document):
    full_name = schema.CharField()

    def clean_full_name(self):
        value = self.full_name.strip()
        if ' ' not full_name:
            raise ValidationError('A full name must have a first and last name')
        return full_name.strip()

    def clean(self):
        if datetime.date.today().weekday() == 2:
            raise ValidationError('You cannot validate on a Wednesday!')

Multiple Record Types¶

Documents and Schemas maybe subclassed to provide polymorphic functionality. For this to work the base class must define typed_field in its Meta class which specifies a field name to store the type of schema. The subclasses must define typed_key which is to be a unique string value identifying that sublcass.

Here is an example where a collection contains multiple record types:

class ParentDocument(schema.Document):
    slug = schema.SlugField()

    class Meta:
        typed_field = '_doctype'

class Blog(ParentDocument):
    author = schema.CharField()
    body = schema.TextField()

    class Meta:
        typed_key = 'blog'

class Video(ParentDocument):
    url = schema.CharField()
    thumbnail = schema.ImageField(blank=True, null=True)

    class Meta:
        typed_key = 'video'

Blog(slug='blog-entry', author='John Smith', body='large description').save()
Video(slug='a-video', url='http://videos/url').save()

ParentDocument.objects.all() #an iterator containing a Blog and Video entry

Embedded schemas may also take advantage of this functionality as well:

class Download(schema.Schema):
    class Meta:
        typed_field = '_dltype'

class Bucket(schema.Document):
    slug = schema.SlugField()
    downloads = schema.ListField(schema.SchemaField(Download))

class Image(Download):
    full_image = schema.ImageField()

    class Meta:
        typed_key = 'image'

class Video(Download):
    url = schema.CharField()
    thumbnail = schema.ImageField(blank=True, null=True)

    class Meta:
        typed_key = 'video'

bucket = Bucket(slug='my-bucket')
bucket.downloads.append(Image(full_image=myfile))
bucket.downloads.append(Video(url='http://videos/url'))
bucket.save()

When we retrieve our bucket later we can expect the entries in downloads to be appropriately mapped to Image and Video. Outside applications may also add other Download record types and our Bucket class will be made aware of those types.

Fixtures¶

Fixture handling in Django-DocKit is handled by Django-DataTap [https://github.com/zbyte64/django-datatap]. With this library DocKit provides fixture loading and dumping from the command line.

usage:

manage.py datatap Document [<app label>, ...] [<collection name>, ...]

Internal API Reference¶

Contributing¶

DocKit is open-source and is here to serve the community by the community.

Admin¶

Django admin integration is no longer actively supported, please use django-hyperadmin if possible. It is the belief of the maintainers that the Django Admin poorly supports documents and that an alternative is better in the long run. If you must use the Django Admin with dockit and come accross an issue then patches will be accepted.

Dockit provides some basic admin functionality for documents. Additionally the admin allows for editing of nested schemas in your document and also allows for customization on a per schema basis.

Release Notes¶