Diving into the code

For simplicity all example code is contained within a single module,examples/twitter/app.py. For a guide on structuring larger Flask apps withpeewee, check out Structuring Flask Apps.

Models

In the spirit of the popular web framework Django, peewee uses declarativemodel definitions. If you’re not familiar with Django, the idea is that youdeclare a model class for each table. The model class then defines one or morefield attributes which correspond to the table’s columns. For the twitterclone, there are just three models:

• User:
• Represents a user account and stores the username and password, an emailaddress for generating avatars using gravatar, and a datetime fieldindicating when that account was created.
• Relationship:
• This is a utility model that contains two foreign-keys tothe User model and stores which users follow one another.
• Message:
• Analogous to a tweet. The Message model stores the text content ofthe tweet, when it was created, and who posted it (foreign key to User).

If you like UML, these are the tables and relationships:In order to create these models we need to instantiate aSqliteDatabase object. Then we define our model classes, specifyingthe columns as Field instances on the class.

# create a peewee database instance -- our models will use this database to
# persist information
database = SqliteDatabase(DATABASE)
 
# model definitions -- the standard "pattern" is to define a base model class
# that specifies which database to use.  then, any subclasses will automatically
# use the correct storage.
class BaseModel(Model):
    class Meta:
        database = database
 
# the user model specifies its fields (or columns) declaratively, like django
class User(BaseModel):
    username = CharField(unique=True)
    password = CharField()
    email = CharField()
    join_date = DateTimeField()
 
# this model contains two foreign keys to user -- it essentially allows us to
# model a "many-to-many" relationship between users.  by querying and joining
# on different columns we can expose who a user is "related to" and who is
# "related to" a given user
class Relationship(BaseModel):
    from_user = ForeignKeyField(User, backref='relationships')
    to_user = ForeignKeyField(User, backref='related_to')
 
    class Meta:
        # `indexes` is a tuple of 2-tuples, where the 2-tuples are
        # a tuple of column names to index and a boolean indicating
        # whether the index is unique or not.
        indexes = (
            # Specify a unique multi-column index on from/to-user.
            (('from_user', 'to_user'), True),
        )
 
# a dead simple one-to-many relationship: one user has 0..n messages, exposed by
# the foreign key.  because we didn't specify, a users messages will be accessible
# as a special attribute, User.messages
class Message(BaseModel):
    user = ForeignKeyField(User, backref='messages')
    content = TextField()
    pub_date = DateTimeField()

Note

Note that we create a BaseModel class that simply defines what databasewe would like to use. All other models then extend this class and will alsouse the correct database connection.

Peewee supports many different field types which map todifferent column types commonly supported by database engines. Conversionbetween python types and those used in the database is handled transparently,allowing you to use the following in your application:

• Strings (unicode or otherwise)
• Integers, floats, and Decimal numbers.
• Boolean values
• Dates, times and datetimes
• None (NULL)
• Binary data

Creating tables

In order to start using the models, its necessary to create the tables. This isa one-time operation and can be done quickly using the interactive interpreter.We can create a small helper function to accomplish this:

def create_tables():
    with database:
        database.create_tables([User, Relationship, Message])

Open a python shell in the directory alongside the example app and execute thefollowing:

>>> from app import *
>>> create_tables()

Note

If you encounter an ImportError it means that either flask or _peewee_was not found and may not be installed correctly. Check the Installing and Testingdocument for instructions on installing peewee.

Every model has a create_table() classmethod which runs a SQLCREATE TABLE statement in the database. This method will create the table,including all columns, foreign-key constraints, indexes, and sequences. Usuallythis is something you’ll only do once, whenever a new model is added.

Peewee provides a helper method Database.create_tables() which willresolve inter-model dependencies and call create_table() oneach model, ensuring the tables are created in order.

Note

Adding fields after the table has been created will require you toeither drop the table and re-create it or manually add the columnsusing an ALTER TABLE query.

Alternatively, you can use the schema migrations extensionto alter your database schema using Python.

Establishing a database connection

You may have noticed in the above model code that there is a class defined onthe base model named Meta that sets the database attribute. Peewee allowsevery model to specify which database it uses. There are many Metaoptions you can specify which control the behavior of yourmodel.

This is a peewee idiom:

DATABASE = 'tweepee.db'
 
# Create a database instance that will manage the connection and
# execute queries
database = SqliteDatabase(DATABASE)
 
# Create a base-class all our models will inherit, which defines
# the database we'll be using.
class BaseModel(Model):
    class Meta:
        database = database

When developing a web application, it’s common to open a connection when arequest starts, and close it when the response is returned. You should alwaysmanage your connections explicitly. For instance, if you are using aconnection pool, connections will only be recycled correctly ifyou call connect() and close().

We will tell flask that during the request/response cycle we need to create aconnection to the database. Flask provides some handy decorators to make this asnap:

@app.before_requestdef before_request():    database.connect()
@app.after_requestdef after_request(response):    database.close()    return response

Note

Peewee uses thread local storage to manage connection state, so thispattern can be used with multi-threaded WSGI servers.

Making queries

In the User model there are a few instance methods that encapsulate someuser-specific functionality:

• following(): who is this user following?
• followers(): who is following this user?

These methods are similar in their implementation but with an importantdifference in the SQL JOIN and WHERE clauses:

def following(self):
    # query other users through the "relationship" table
    return (User
            .select()
            .join(Relationship, on=Relationship.to_user)
            .where(Relationship.from_user == self)
            .order_by(User.username))
 
def followers(self):
    return (User
            .select()
            .join(Relationship, on=Relationship.from_user)
            .where(Relationship.to_user == self)
            .order_by(User.username))

Creating new objects

When a new user wants to join the site we need to make sure the username isavailable, and if so, create a new User record. Looking at the join() view,we can see that our application attempts to create the User usingModel.create(). We defined the User.username field with a uniqueconstraint, so if the username is taken the database will raise anIntegrityError.

try:
    with database.atomic():
        # Attempt to create the user. If the username is taken, due to the
        # unique constraint, the database will raise an IntegrityError.
        user = User.create(
            username=request.form['username'],
            password=md5(request.form['password']).hexdigest(),
            email=request.form['email'],
            join_date=datetime.datetime.now())
 
    # mark the user as being 'authenticated' by setting the session vars
    auth_user(user)
    return redirect(url_for('homepage'))
 
except IntegrityError:
    flash('That username is already taken')

We will use a similar approach when a user wishes to follow someone. Toindicate a following relationship, we create a row in the Relationship tablepointing from one user to another. Due to the unique index on from_user andto_user, we will be sure not to end up with duplicate rows:

user = get_object_or_404(User, username=username)
try:
    with database.atomic():
        Relationship.create(
            from_user=get_current_user(),
            to_user=user)
except IntegrityError:
    pass

Performing subqueries

If you are logged-in and visit the twitter homepage, you will see tweets fromthe users that you follow. In order to implement this cleanly, we can use asubquery:

Note

The subquery, user.following(), by default would ordinarily select allthe columns on the User model. Because we’re using it as a subquery,peewee will only select the primary key.

# python code
user = get_current_user()
messages = (Message
            .select()
            .where(Message.user.in_(user.following()))
            .order_by(Message.pub_date.desc()))

This code corresponds to the following SQL query:

SELECT t1."id", t1."user_id", t1."content", t1."pub_date"
FROM "message" AS t1
WHERE t1."user_id" IN (
    SELECT t2."id"
    FROM "user" AS t2
    INNER JOIN "relationship" AS t3
        ON t2."id" = t3."to_user_id"
    WHERE t3."from_user_id" = ?
)

Other topics of interest

There are a couple other neat things going on in the example app that are worthmentioning briefly.

• Support for paginating lists of results is implemented in a simple function calledobject_list (after it’s corollary in Django). This function is used by allthe views that return lists of objects.

def object_list(template_name, qr, var_name='object_list', **kwargs):
    kwargs.update(
        page=int(request.args.get('page', 1)),
        pages=qr.count() / 20 + 1)
    kwargs[var_name] = qr.paginate(kwargs['page'])
    return render_template(template_name, **kwargs)

• Simple authentication system with a login_required decorator. The firstfunction simply adds user data into the current session when a user successfullylogs in. The decorator login_required can be used to wrap view functions,checking for whether the session is authenticated and if not redirecting to thelogin page.

def auth_user(user):
    session['logged_in'] = True
    session['user'] = user
    session['username'] = user.username
    flash('You are logged in as %s' % (user.username))
 
def login_required(f):
    @wraps(f)
    def inner(*args, **kwargs):
        if not session.get('logged_in'):
            return redirect(url_for('login'))
        return f(*args, **kwargs)
    return inner

• Return a 404 response instead of throwing exceptions when an object is notfound in the database.

def get_object_or_404(model, *expressions):
    try:
        return model.get(*expressions)
    except model.DoesNotExist:
        abort(404)

Note

To avoid having to frequently copy/paste object_list() orget_object_or_404(), these functions are included as part of theplayhouse flask extension module.

from playhouse.flask_utils import get_object_or_404, object_list