========
MongoKit
========

MongoDB_ is a great schema-less document oriented database. It have a lot of
driver for many langages (python, ruby, perl, java, php...).

.. _MongoDB : http://www.mongodb.org/display/DOCS/Home

MongoKit is a python module that brings structured schema and validation layer
on top of the great pymongo driver. It has be written to be simpler and lighter
as possible with the KISS and DRY principles in mind.

Features
========

 * schema validation (wich use simple python type for the declaration)
 * doted notation
 * nested and complex schema declaration
 * required fields validation
 * default values
 * custom validators
 * cross database document reference
 * random query support (which returns a random document from the database)
 * inheritance and polymorphisme support
 * versionized document support (in beta stage)
 * partial auth support (it brings a simple User model) 
 * operator for validation (currently : OR, NOT and IS)
 * simple web framework integration
 * import/export to json
 * i18n support
 * GridFS support

A quick example
===============

Document are enhanced python dictionnary with a ``validate()`` method.
A Document declaration look like that::

    >>> from mongokit import *
    >>> import datetime

    >>> class BlogPost(Document):
    ...     structure = {
    ...             'title':unicode,
    ...             'body':unicode,
    ...             'author':unicode,
    ...             'date_creation':datetime.datetime,
    ...             'rank':int
    ...     }
    ...     required_fields = ['title','author', 'date_creation']
    ...     default_values = {'rank':0, 'date_creation':datetime.datetime.utcnow}
    ... 

We fire a connection and register our objects.

    >>> con = Connection()
    >>> con.register([BlogPost])
    >>> blogpost = con.test.example.BlogPost() # this use the db "test" and the collection "example"
    >>> blogpost['title'] = u'my title'
    >>> blogpost['body'] = u'a body'
    >>> blogpost['author'] = u'me'
    >>> blogpost
    {'body': u'a body', 'title': u'my title', 'date_creation': datetime.datetime(...), 'rank': 0, 'author': u'me'}
    >>> blogpost.save()
   
Saving the object will call the `validate()` method.

And you can use more complex structure::

    >>> class ComplexDoc(Document):
    ...     structure = {
    ...         "foo" : {"content":int},
    ...         "bar" : {
    ...             int:{unicode:int}
    ...         }
    ...     }
    ...     required_fields = ['foo.content', 'bar.$int']
     
Please, see the tutorial_ for more examples.

.. _tutorial : http://bytebucket.org/namlook/mongokit/wiki/html/tutorial.html

Suggestion and patches are really welcome. If you find mistakes in the documentation
(english is not my primary langage) feel free to contact me. You can find me (namlook) 
on the freenode #mongodb irc channel or on twitter_.

.. _twitter : http://twitter.com/namlook


Mongokit is documented and well tested with 100% of code coverage::

    Name                          Stmts   Exec  Cover   Missing
    -----------------------------------------------------------
    mongokit                         11     11   100%   
    mongokit.auth                    43     43   100%   
    mongokit.collection              31     31   100%   
    mongokit.connection              14     14   100%   
    mongokit.database                 7      7   100%   
    mongokit.document               400    400   100%   
    mongokit.generators              32     32   100%   
    mongokit.helpers                 69     69   100%   
    mongokit.mongo_exceptions         8      8   100%   
    mongokit.operators               47     47   100%   
    mongokit.schema_document        462    462   100%   
    mongokit.versioned_document      45     45   100%   
    -----------------------------------------------------------
    TOTAL                          1169   1169   100%   
    ----------------------------------------------------------------------
    Ran 193 tests in 58.080s

Change Log
==========

v0.5.3
------
 * fix default_value issue when using with dict and list (see #35)
 * fix bug reported by Andrew Degtiariov : http://bit.ly/c1vcUv
 * add clone and explain method to MongoDocumentCursor
 * add distinct to cursor (thanks to Flaper87)
 * fix index test
 * fix : when a field is added to a saved document and not specified in the structure, the validation wasn't work properly
 * use current database if DBRef has no database information. Please, see the doc
 * support of pymongo 1.4


v0.5.2
------
 * bugs fix in json import/export
 * bugs fix in default values and required values
 * `gridfs support`_

.. _`gridfs support` : http://bytebucket.org/namlook/mongokit/wiki/html/gridfs.html

v0.5.1
------
 * `save()` doesn't return ``self`` anymore (was an API monster)
 * fix bug in `find_one()` method. Now returns None if no Document is found
 * fix bug when using default values
 * adding i18n list support
 * add i18n inheritance support
 * adding index inheritance support

v0.5
----
 * refactoring API which is getting much much more cleaner. Please see the migration_ page to keep your code up to date
 * 100% code coverage by 162 unit tests
 * lot of bug fix (too many to list them here)
 * add document size validation
 * add cross database reference support
 * `i18n support`_

.. _migration : http://bytebucket.org/namlook/mongokit/wiki/html/migration.html
.. _`i18n support` : http://bytebucket.org/namlook/mongokit/wiki/html/i18n.html

v0.4
----
    * add autoref support to belong_to (delete cascade)
      (http://bytebucket.org/namlook/mongokit/wiki/html/cascade.html#delete-cascade)
    * changing collection dynamically 
      (http://bytebucket.org/namlook/mongokit/wiki/html/tutorial.html#changing-collection-dynamically)
    * add immutable field (python tuple support)
      (http://bytebucket.org/namlook/mongokit/wiki/html/tutorial.html#case-of-tuple-or-immutable-field)
    * add direction and ttl to index support
      (http://bytebucket.org/namlook/mongokit/wiki/html/tutorial.html#indexes)
    * add connection sharing support
      (http://bytebucket.org/namlook/mongokit/wiki/html/tutorial.html#sharing-connection)
    * add json import/export for MongoDocument
      (http://bytebucket.org/namlook/mongokit/wiki/html/tutorial.html#json-support)
    * full relation support (related_to)
      (http://bytebucket.org/namlook/mongokit/wiki/html/relations.html)
    * add long type support

v0.3.3
------

   * add autoref support (thanks to @bwmcadams)
   * add mongodb index support (thanks to @marcammann) 
   * adding CustomType (original idea from Phillip Oldham) 
   * support now all type of subclassed supported type 
   * add "delete cascade" feature
   * add the possibility to skip the validation layer for more performances
   * fix issue while passing queries to fetch() and update tutorial 
   * self._collection must not be None in __init__ 
   * fix #11 - pylons_env extension documentation typo 
   * add more complete test + docstring 
   * fix issue #9 - bug with custom_types and nested dict in list