picomongo 0.6

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