MongoKit Documentation

https://github.com/namlook/mongokit/raw/devel/doc/mongokit_logo.png

Build Status

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

Features

  • Schema validation (which uses simple python types for the declaration)
  • Schema-less feature
  • Dot 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 polymorphism 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

Quick Example

A quick example

Documents are enhanced python dictionaries with a validate() method. A Document declaration look as follows:

>>> # Python 3
>>> from mongokit import *
>>> import datetime

>>> connection = Connection()

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

>>> # Python 2
>>> 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 establish a connection and register our objects.

>>> blogpost = con.test.example.BlogPost() # this uses the database "test" and the collection "example"
>>> blogpost['title'] = 'my title'
>>> blogpost['body'] = 'a body'
>>> blogpost['author'] = 'me'
>>> blogpost
{'body': 'a body', 'title': 'my title', 'date_creation': datetime.datetime(...), 'rank': 0, 'author': 'me'}
>>> blogpost.save()

Saving the object will call the validate() method.

And you can use a more complex structure as follows:

>>>  @connection.register
...  class ComplexDoc(Document):
...     __database__ = 'test'
...     __collection__ = 'example'
...     structure = {
...         "foo" : {"content":int},
...         "bar" : {
...             'bla':{'spam':int}
...         }
...     }
...     required_fields = ['foo.content', 'bar.bla.spam']

Community

Suggestions and patches are really welcome. If you find mistakes in the documentation feel free to send a pull request or to contact us.

Contents:

Indices and tables