Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
173 lines (110 sloc) 4.38 KB


Ready to dive in? Here's a quick run through the basics of using Simon. It will guide you through defining models, saving and retrieving documents, and connecting to a database.

Defining a Model

To define a simple model, all you need to do is inherit from the :class:`~simon.Model` class.

from simon import Model

class User(Model):
    """This is the model used for users."""

This will define the User model which will use the users collection in the database.

Using the Model

To instantiate a new User:

user = User(name='Simon', email='')

Attributes can also be assigned after instantiation.

user = User() = 'Simon' = ''


Saving the changes is as easy as calling :meth:``. created and modified dates will be added to the document before it is written to the database, and the :class:`ObjectId <pymongo:bson.objectid.ObjectId>` assigned by the database will be added to the instance. (created will only be added to documents that haven't already been saved and don't already have a created field.)

print '%r %r %r' % (, user.created, user.modified)
# ObjectId('50e467580ea5faf0b83679f7') datetime.datetime(2013, 1, 2, 16, 59, 4, 688000) datetime.datetime(2013, 1, 2, 16, 59, 4, 688000)

By default saves happen with write concern set. If, for some reason, this behavior isn't desired, write concern can be turned off by setting the w parameter to 0.


Once the document has been saved it can easily be retrieved from the database. The :meth:`~simon.Model.get` method accepts the names of fields as parameters with values to match against.

user = User.get(name='Simon')
print '%r %r' % (,
# 'Simon' ''

For information about the possible exceptions associated with :meth:`~simon.Model.get`, check out Exceptions.

Retrieving multiple documents instead of just one is also easy. Just use the :meth:`~simon.Model.find` method instead of :meth:`~simon.Model.get`. They accept parameters the same way.

user2 = User(name='Simon', email='')

users = User.find(name='simon')
for user in users:
    print '%r %r' % (,

# 'Simon' ''
# 'Simon' ''

Connecting to a Database

Before you can use your models, you need to connect to a database. This is done by using the :meth:`~simon.connection.connect` method.

from simon.connection import connect

connect('localhost', name='simon')

This will open a connection to the simon database on localhost. It's also possible to connect to a database on a remote server.

connect('', name='simon')

Or you can specify a full URI.


When connecting to a database that requires authentication, a username and password can be specified either through the username and password arguments or as part of the URI.

connect('localhost', name='simon', username='user', password='passwd')

# ~ or ~



When using the :meth:`~simon.Model.get` method from a model class it is important to keep in mind that there are a couple of exceptions it can raise. It's a good idea to catch them.

    user = User.get(name='Simon2')
except User.NoDocumentFound:
    # This means no documents matched the query

    user = User.get(name='Simon')
except User.MultipleDocumentsFound:
    # This means more than one document matched the query

There is also an exception that can be raised when connecting to a database.

    connect('locahost', name='simon')
except ConnectionError:
    # There was a problem connecting to the database