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

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 :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='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 :meth:`~simon.Model.save`. 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.)

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 :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' % (user.name, user.email)
# 'Simon' 'simon@example.com'

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='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 :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('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 :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.

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