django-mongokit 0.1.4

django-mongokit
===============

(c) Peter Bengtsson, peter@fry-it.com, 2010
License: New BSD License

Bridging Django to MongoDB with the MongoKit ODM
------------------------------------------------

The purpose of this module is to make it easy to use
[MongoKit](http://bitbucket.org/namlook/mongokit/wiki/Home) to
define your models for Django if you prefer to use MongoDB instead of
a relational database. This kit takes care of the boilerplate and
makes your MongoKit documents work better with Django as it defines a
`_meta` class attribute when registering.

Installation
------------

`pip/easy_install django-mongokit` (XXX UPLOAD TO PYPI)

Usage/Configuration
-------------------

First of all you need to define a name of the database and but that
into your `settings.DATABASES` directive. Here's an example:

DATABASES = {
'default': {
'ENGINE': 'sqlite3',
'NAME': 'example-sqlite3.db',
},
'mongodb': {
'ENGINE': 'django_mongokit.mongodb',
'NAME': 'example',
},
}

Note that `default` and `mongodb` are mandatory keys in this settings.
What you can change is the `NAME` part under `DATABASES['mongodb']`.

In Django, you might be used to doing something like this:

from django.db import models

class Talk(models.Model):
topic = models.CharField(max_length=250)
date = models.DateTimeField()

Now, with `django_mongokit` you can do this:

from django_mongokit.document import DjangoDocument

class Talk(DjangoDocument):
structure = {
'topic': unicode,
'date': datetime.datetime
}

This base class gives you some benefits out-of-the-box which will
hopefully make working with MongoKit documents easier such as `pk`.
This will return the `ObjectID` of an instance as a byte string which
can be very useful for mapping URLs and finding documents by ID. For
example:

>>> from mongokit import Connection
>>> conn = Connection()
>>> from exampleapp.models import Talk
>>> conn.register([Talk])
>>> database = conn['example']
>>> collection = database['talks']
>>> talk = collection.Talk.find_one()
>>> talk
'4b87c6b19d40b3375a000001'

There's also the `_meta` attribute which Django people will be
familiar with:

>>> talk._meta
<Meta Talk 'Talk', 'Talks'>
>>> talk._meta.verbose_name
'Talk'
>>> talk._meta.verbose_name_plural
'Talks'

If you want to override any of the `_meta` attributes you do it just
like you do it with the Django ORM:


class Talk(models.Model):
...
class Meta:
verbose_name_plural = u"Talkings"

A limited set of signals are fired when working with `django_mongokit`
documents. These are:

* pre_delete
* post_delete
* pre_save
* post_save


Examples
--------

`django-mongokit` comes with an example project and an example app
that does some basic things. It might be a good source of inspiration
for how to use `django-mongokit` to look at this example app.