Skip to main content

Ultimate MongoDB Object Document Mapper

Project description

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'})

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'})

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:

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://'}})
    >>> 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).

Project details

Release history Release notifications | RSS feed

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

picomongo-0.6.tar.gz (4.2 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page