Overview — peewee 0.9.8 documentation

### Navigation

- index
- next |
- previous |
- peewee 0.9.8 documentation »

# Overview

peewee is a lightweight ORM written in python.

Examples:

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

    # get the staff and super users
    editors = User.select().where(Q(is_staff=True) | Q(is_superuser=True))

    # get tweets by editors
    Tweet.select().where(user__in=editors)

    # how many active users are there?
    User.select().where(active=True).count()

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

    # order users by number of tweets
    User.select().annotate(Tweet).order_by(('count', 'desc'))

    # another way of expressing the same
    User.select({
        User: ['*'],
        Tweet: [Count('id', 'count')]
    }).group_by('id').join(Tweet).order_by(('count', 'desc'))

    # do an atomic update
    TweetCount.update(count=F('count') + 1).where(user=charlie)

You can use django-style syntax to create select queries:

    # how many active users are there?
    User.filter(active=True).count()

    # get tweets by a specific user
    Tweet.filter(user__username='charlie')

    # get tweets by editors
    Tweet.filter(Q(user__is_staff=True) | Q(user__is_superuser=True))

You can use python operators to create select queries:

    # how many active users are there?
    User.select().where(User.active == True).count()

    # get me all users in their thirties
    User.select().where((User.age >= 30) & (User.age < 40))

    # get me tweets from today by active users
    Tweet.select().join(User).where(
        (Tweet.pub_date >= today) &
        (User.active == True)
    )

Check out the docs for notes on the methods of querying.

## Why?

peewee began when I was working on a small app in flask and found myself writing lots of queries and wanting a very simple abstraction on top of the sql. I had so much fun working on it that I kept adding features. My goal has always been, though, to keep the implementation incredibly simple. I’ve made a couple dives into django’s orm but have never come away with a deep understanding of its implementation. peewee is small enough that its my hope anyone with an interest in orms will be able to understand the code without too much trouble.

### Navigation

- index
- next |
- previous |
- peewee 0.9.8 documentation »