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