MongoKit framework try to keep its simplicity when you manage mongodb in python. MongoKit was developed to be fast and light with KISS and DRY in mind. MongoKit brings structured schema and validation layer on top of the great pymongo driver. Discuss with us on Google group : or follow the news on Twitter: h…
Switch branches/tags
Pull request Compare This branch is 228 commits behind namlook:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



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

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 as simple and light as possible with the KISS and DRY principles in mind.


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
  • powerful: MongoKit brings many feature like document auto-reference, custom types or i18n support.

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.


  • schema validation (wich use simple python type for the declaration)
  • schema less feature
  • 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 .

A quick example

Document are enhanced python dictionary 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'}

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.

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.

Recent Change Log



  • change MongokitMasterSlaveConnection to MasterSlaveConnection for consistency
  • fix #57 -- support pymongo > 1.9 in
  • fix #45 -- remove automatique index creation
  • fix #43 -- slicing a cursor should return a mongokit document, not dict
  • Dont try to convert None struct to json (patch from @mLewisLogic thanks !)
  • fix schemaless issue (thanks to Mihai Pocorschi for reporting it)


  • add use_schemaless feature ! please see the documentation for more informations
  • Add equality test for mongokit operators (thanks to @allancaffee)
    This allows developers to write unit tests on the structure of their document classes when operators are used
  • roll back find_and_modify for master branch (need pymongo 1.10 for that)
  • many documentation fixes
  • fix #55 -- Bug in VersionedDocument remove() method
  • fix #53 -- Fixed a few spelling errors in README
  • fix #52 -- Advanced bulk migration docs example is broken
  • fix #51 -- pymongo.dbref is deprecated, use bson.dbref instead
  • fix #49 -- Can't specify default values for lists of embedded objects
  • fix #48 -- uuid.UUID support
  • fix #41 -- add basestring to authorized types
  • fix #40 -- Made some enhancements
  • fix #39 -- KeyError when saving partially loaded documents
  • fix #34 -- add find_and_modify method to Document
  • fix #32 -- allow the structure to be empty (was: document.to_json())
  • fix #24 -- Don't handle __database__/__collection__ attribute for virtual documents