picomongo 0.6

Ultimate MongoDB Object Document Mapper

Faster than minimongo, lighter than micromongo, please welcome picomongo, the ultimate Mongo ODM made by Dailymotion.

Getting started

To start off with picomongo, just import it:

>>> from picomongo import Document, ConnectionManager
>>> ConnectionManager.configure()

And you’re ready, let’s define a document:

>>> class UserDocument(Document):
...     pass
>>> user = UserDocument({'name': 'Mike'})
>>> user
UserDocument({'name': 'Mike'})
>>> user.name
'Mike'
>>> user.save()

YOU: Wait, wait where is my document ?

Don’t worry, in order to facilitate your work, picomongo use these default values:

• Mongo uri: ‘mongodb://localhost’

• Database: ‘test’

• Collection: Your document class name in lowercase

You have access to these values, which are traditionnal pymongo objects:

>>> UserDocument.con
Connection('localhost', 27017)
>>> UserDocument.db
Database(Connection('localhost', 27017), u'test')
>>> UserDocument.col
Collection(Database(Connection('localhost', 27017), u'test'), u'userdocument')

One thing you should always keep in mind, you always need to call configure before be able to save/retrieve your documents. If you want to use the default configuration, just call configure without arguments otherwise see below (part Configuration time).

TIP: You can call configure after the declaration of your documents BUT before document saving/retrieving.

You can use them as you will do with traditionnal pymongo objects, for example you can retrieve your user using traditionnal collection:

>>> UserDocument.col.find_one()
{u'_id': ObjectId('4eb2cae58250f05eb4000000'), u'name': u'Mike'}

YOU: But wait, why I get a dict, I want an object instead.

Don’t worry, it’s even more simpler:

>>> user2 = UserDocument.find_one()
UserDocument({u'_id': ObjectId('4eb2cae58250f05eb4000000'), u'name': u'Mike'})
>>> user2.name
u'Mike'

But when this auto-configuration was done? As soon as you try to access them.

Configure the collection

You can configure on which collection your documents will be saved. You can override the collection_name in your custom Document classes if you want to configure it. Example:

>>> class CustomDocument(Document):
...     collection_name = 'my_custom_collection'
>>> custom = CustomDocument()
>>> custom.col
Collection(Database(Connection('localhost', 27017), u'test'), u'my_custom_collection')

Configuration time

Once you use it a bit, let’s see the most powerful part of picomongo, configuration.

All configurations are stored in ConnectionManager:

>>> from picomongo import Document, ConnectionManager

You can add your own configuration by calling the configure method with your configuration. The configuration format is:

{'_default_': {'uri': 'default_uri', 'db': 'default_db'},
 'document_name': {'uri': 'specific_uri', 'db': 'specific_db', 'col': 'default_col'},
 'document_name2': ...,}

Uri must be a valid mongodb connection uri as described in this doc page: http://www.mongodb.org/display/DOCS/Connections

Nothing is required in the configuration, and picomongo will use some rules to compute the final configuration:

• In default configuration:

  • If uri is not present, use ‘mongodb://localhost’

  • If db is not present, use ‘test’

• In document configuration:

  • If uri is not present, use default uri

  • If db is not present, use default db

  • If col is not preset, use document class name

You can access configuration using this syntax:

>>> ConnectionManager.get_config('_default_')   # Access default configuration
>>> ConnectionManager.get_config('document')    # Access configuration for document named 'document'

Here is some examples of configurations:

• Change default db:

  >>> ConnectionManager.configure({'\_default\_': {'db': 'other_db'}})
  >>> ConnectionManager.get_config('\_default\_').db
  Database(Connection('localhost', 27017), u'other_db')

• Store some documents in another mongodb instance:

  >>> ConnectionManager.configure({'document1': {'uri': 'mongodb://127.0.0.1:8000'}})
  >>> ConnectionManager.get_config('_default_').con
  Connection('localhost', 27017)
  >>> ConnectionManager.get_config('document1').con
  Connection('localhost', 8000)

TIP: This last example will surely fail as picomongo try to connect to this uri during configuration (and you probably do not have a mongodb instance running at this uri).