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
collection in the database.
Using the Model
To instantiate a new
user = User(name='Simon', email@example.com')
Attributes can also be assigned after instantiation.
user = User() user.name = 'Simon' user.email = 'firstname.lastname@example.org'
Saving the changes is as easy as calling :meth:`~simon.Model.save`.
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
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
w parameter to
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' 'email@example.com'
user2 = User(name='Simon', firstname.lastname@example.org') user2.save() users = User.find(name='simon') for user in users: print '%r %r' % (user.name, user.email) # 'Simon' 'email@example.com' # 'Simon' 'firstname.lastname@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
It's also possible to connect to a database on a remote server.
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
password arguments or as part of the URI.
connect('localhost', name='simon', username='user', password='passwd') # ~ or ~ connect('mongodb://user:email@example.com/simon')
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()