peewee: A Python repository from bsuire

peewee

Peewee is a simple and small ORM. It has few (but expressive) concepts, making it easy to learn and intuitive to use.

A small, expressive ORM
Written in python with support for versions 2.6+ and 3.2+.
built-in support for sqlite, mysql and postgresql
tons of extensions available in the playhouse

https://api.travis-ci.org/coleifer/peewee.png?branch=master

New to peewee? Here is a list of documents you might find most helpful when getting started:

Quickstart guide -- this guide covers all the essentials. It will take you between 5 and 10 minutes to go through it.
Guide to the various query operators describes how to construct queries and combine expressions.
Field types table lists the various field types peewee supports and the parameters they accept.

For flask helpers, check out the flask_utils extension module. You can also use peewee with the popular extension flask-admin to provide a Django-like admin interface for managing peewee models.

Examples

Defining models is similar to Django or SQLAlchemy:

from peewee import *
import datetime

db = SqliteDatabase('my_database.db', threadlocals=True)

class BaseModel(Model):
    class Meta:
        database = db

class User(BaseModel):
    username = CharField(unique=True)

class Tweet(BaseModel):
    user = ForeignKeyField(User, related_name='tweets')
    message = TextField()
    created_date = DateTimeField(default=datetime.datetime.now)
    is_published = BooleanField(default=True)

Connect to the database and create tables:

db.connect()
db.create_tables([User, Tweet])

Create a few rows:

charlie = User.create(username='charlie')
huey = User(username='huey')
huey.save()

# No need to set `is_published` or `created_date` since they
# will just use the default values we specified.
Tweet.create(user=charlie, message='My first tweet')

Queries are expressive and composable:

# A simple query selecting a user.
User.get(User.username == 'charles')

# Get tweets created by one of several users. The "<<" operator
# corresponds to the SQL "IN" operator.
usernames = ['charlie', 'huey', 'mickey']
users = User.select().where(User.username << usernames)
tweets = Tweet.select().where(Tweet.user << users)

# We could accomplish the same using a JOIN:
tweets = (Tweet
          .select()
          .join(User)
          .where(User.username << usernames))

# How many tweets were published today?
tweets_today = (Tweet
                .select()
                .where(
                    (Tweet.created_date >= datetime.date.today()) &
                    (Tweet.is_published == True))
                .count())

# Paginate the user table and show me page 3 (users 41-60).
User.select().order_by(User.username).paginate(3, 20)

# Order users by the number of tweets they've created:
tweet_ct = fn.Count(Tweet.id)
users = (User
         .select(User, tweet_ct.alias('ct'))
         .join(Tweet, JOIN.LEFT_OUTER)
         .group_by(User)
         .order_by(tweet_ct.desc()))

# Do an atomic update
Counter.update(count=Counter.count + 1).where(
    Counter.url == request.url)

Check out the example app for a working Twitter-clone website written with Flask.

Learning more

Check the documentation for more examples.

Specific question? Come hang out in the #peewee channel on freenode.irc.net, or post to the mailing list, http://groups.google.com/group/peewee-orm . If you would like to report a bug, create a new issue on GitHub.

Still want more info?

I've written a number of blog posts about building applications and web-services with peewee (and usually Flask). If you'd like to see some real-life applications that use peewee, the following resources may be useful:

bsuire/peewee

peewee

Examples

Learning more

Still want more info?