Quickstart

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 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='simon@example.com')

Attributes can also be assigned after instantiation.

user = User()
user.name = 'Simon'
user.email = 'simon@example.com'

Saving

Saving the changes is as easy as calling save(). created and modified dates will be added to the document before it is written to the database, and the 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.)

user.save()

print '%r %r %r' % (user.id, 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.

user.save(w=0)

Retrieving

Once the document has been saved it can easily be retrieved from the database. The get() method accepts the names of fields as parameters with values to match against.

user = User.get(name='Simon')
print '%r %r' % (user.name, user.email)
# 'Simon' 'simon@example.com'

For information about the possible exceptions associated with get(), check out Exceptions.

Retrieving multiple documents instead of just one is also easy. Just use the find() method instead of get(). They accept parameters the same way.

user2 = User(name='Simon', email='simon@example.org')
user2.save()

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

# 'Simon' 'simon@example.com'
# 'Simon' 'simon@example.org'

Connecting to a Database

Before you can use your models, you need to connect to a database. This is done by using the 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('simon.example.com', name='simon')

Or you can specify a full URI.

connect('mongodb://simon.example.com/simon')

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 ~

connect('mongodb://user:passwd@simon.example.com/simon')

Exceptions

When using the 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.

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

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

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

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

Table Of Contents

Previous topic

Simon: Simple MongoDB Models

Next topic

Basic Usage

This Page

Fork me on GitHub