Example

The following code is a simplified example of how to use python-docar. We start using the Django backend:

# First declare your document
from webapp.models import EntryModel, AuthorModel
from docar import Document, Collection, fields

class Author(Document):
    name = fields.StringField()

    class Meta:
        backend_type = 'django'
        model = AuthorModel
        identifier = 'name'

class BlogEntry(Document):
    id = fields.NumberField()
    title = fields.StringField()
    body = fields.StringField()
    published = fields.BooleanField(default=False)
    author = fields.ForeignDocument(Author)

    class Meta:
        backend_type = 'django'
        model = EntryModel
        #identifier = 'id'  # The identifier defaults to 'id'

# You can also declare collections of documents
class Blog(Collection):
    document = BlogEntry

You can use those documents in the views of your application:

from webapp.documents import Author, BlogEntry, Blog

entry = BlogEntry({'id': 1})

# Bind the document to a model
entry.fetch()

I can also change attributes of the document and save it back to the model:

entry.title = "20000 Leagues under the sea"
entry.save()  # --> saves to the django model backend

The render method renders the document into a normalized dictionary. Serializers take the normalized output, and transform it into the message format that is needed.:

# render the document as a json string
entry.render()

{
    "id": 1,
    "title": "20000 Leagues under the sea",
    "body": "The whole story about captain Nemo ...",
    "published": True,
    "author": {
        "name": "Jules Vernes",
    }
}

Installation

Clone yourself the latest source from github. Development happens fast, so its good to always go with the latest commit:

$ git clone git://github.com/30loops/python-docar.git
$ cd python-docar
$ sudo python setup.py install

Development

This module comes along with a thorough test suite. Run it the following way:

$ python setup.py nosetests

Documentation

To build the documentation you need sphinx installed:

$ cd docs
$ make html

You find the documentation in docs/_build/html/.

Disclaimer

The use of this software comes without any warranty. It is released under a BSD license. See LICENSE for details.