Tutorial

Warning

Cormoran is in a very alpha state so its not recomendable to use it in production software.

Installing

You can install the latest estable version from PyPI.

$ pip install cormoran

Or if you want to work with the latest development version, you can install it from GitHub.

$ pip install git+git://github.com/jaimegildesagredo/cormoran.git

Importing

Import the Cormoran public API.

>>> from cormoran import *

Defining data

We need to define a new Persistent subclass with all the fields we want to persists.

>>> class User(Persistent):
...    __cormoran_name__ = u'users'
...    email = StringField(nullable=False)
...    name = StringField()
...    is_active = BooleanField(default=False)

The User class has email and name string fields and is_active boolean field. The __cormoran_name__ is an optional attribute to tell Cormoran which is the name of the collection (the SQL table). If not present will be the class name.

Also an _id integer primary field has been automatically generated.

>>> User._id
<cormoran.fields.IntegerField object at 0x7f6845fe6350>

Connecting to a SQLite database

For this tutorial we will use the SQLite backend. To create a database connection we call connect() with the uri to our database.

>>> sqlite = connect('sqlite:///tests.sqlite')

We can also use a in-memory SQLite database.

>>> sqlite = connect('sqlite:///:memory:')

Next we will create a Store object with our sqlite connection.

>>> store = Store(sqlite)

For now Cormoran doesn’t create the database structure and we need to create the tables manually, so we will execute the SQL create table statement.

>>> sqlite._connection.execute('CREATE TABLE users (_id integer primary key, email text not null, name text, is_active bool)')

Creating an object

Now we will create a new User called Mike with email mike@example.com

>>> user = User(name=u'Mike', email=u'mike@example.com')

and save him to the database.

>>> store.add(user)
>>> store.commit()

Then the _id field is populated from database.

>>> user._id == 1
True

Updating an object

We want to activate our new user.

>>> user.is_active = True
>>> store.add(user)
>>> store.commit()

Finding objects

Now we want to get all users in our system.

>>> for user in store.find(User):
...    print u'%d: %s <%s>' % (user._id, user.name, user.email)
1: Mike <mike@example.com>

We may also want to filter results. For example get only the active users.

>>> list(store.find(User).filter(is_active=True))
[<__main__.User object at 0x7ff85b681210>]