README

========
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.

Philosophy
==========

MongoKit is designed to be:

 * **simple**: MongoKit use plain python type to describe document structure
 * **fast**: MongoKit is fast but if you *really* need to be fast you have access to the raw pymongo layer without changing the API
 * **powerfull**: MongoKit brings many feature like document auto-reference, custom types or i18n support.

.. topic:: **Your data is clean**:


    "Tools change, not data". In order to follow this "credo", MongoKit won't
    add any information into your data saved into the database.
    So if you need to use other mongo tools or ODMs in other languages, your
    data won't be polluted by MongoKit's stuff.

Features
========

 * schema validation (wich use simple python type for the declaration)
 * doted notation
 * nested and complex schema declaration
 * untyped field support
 * 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
 * document migration support

Go to the full documentation_ .

.. _documentation : http://namlook.github.com/mongokit/

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

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

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

    >>> connection = Connection()
    
    >>> @connection.register
    ... 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.

    >>> 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::

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

.. _tutorial : http://namlook.github.com/mongokit/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


Recent Change Log
=================

v0.6
----

 * fix error when check is True. Thanks to @dasmith for the patch
 * Many english corrections in the documentation thanks to @allancaffee
 * spliting doc and refactoring documentation
 * remove unused MongoDocumentCursor

v0.5.13.1
---------

 * fix #26 -- unable to install (debian lenny, py 2.5)
 * fix #25 -- put the new url into the setup.py

v0.5.13
-------

 * fix #21 -- required_fields weird behavior with autorefs
 * fix #19 -- 'checked' field not listed in 'indexes' section
 * fix #20 -- creating index on fields not in structure + optimize index generation
 * fix #18 -- typo in the doc
 * fix import. Dbref isn't in pymongo package anymore
 * fix deprecation warning from pymongo's from_dict
 * fix #8 -- allow to access Document via the db

v0.5.12.1
---------

 * fix #17 -- got an unexpected keyword argument 'from_son'
 * fix #15 -- typo in the doc

v.0.5.12
---------

 * allow register method to be a decorator (thanks to Christopher Grebs for the inspiration)
 * get ride of MongoDocumentCursor and use a subclass of pymongo's Cursor instead
 * structure and descriptors validation is now done at object creation (not instantiation)

   - *advantage* : mongokit is 40% faster
   - *beware* : if you put a Document into a structure for reference, mongokit doesn't check anymore if use_autorefs is set

 * add i18n descriptor validation + better i18n support
 * code cleaning

v0.5.11
-------

 * support latest pymongo version
 * some changes in GridFS support (please read http://namlook.github.com/mongokit/gridfs.html)
 * Deprecate atomic_save feature
 * remove libmagic import from grid.py : to many trouble with this lib, we have to find another way to guess the content-type
 * fix #79 -- Tries to migrate non-saved document
 * fix #70 -- Set changes from set to list when a validation error occurs
 * add contributor + fix email address to prevent spam
 * fix deprecation warning of Python 2.6
 * fix issue with validation and migration
 * fix #75 -- add "version" attribute to module