peewee README

The project's README from github.com/coleifer/peewee. As one markdown file: README.md.

.. image:: https://media.charlesleifer.com/blog/photos/peewee4-logo.png

peewee

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

Peewee is a single module with no required dependencies and has been running production workloads of all sizes since 2010.

New to peewee? These may help:

Installation:

.. code-block:: console

pip install peewee

Sqlite comes built-in provided by the standard-lib sqlite3 module. Other backends can be installed using the following instead:

.. code-block:: console

pip install peewee[mysql]  # Install peewee with pymysql.
pip install peewee[postgres]  # Install peewee with psycopg2.
pip install peewee[psycopg3]  # Install peewee with psycopg3.

# AsyncIO implementations.
pip install peewee[aiosqlite]  # Install peewee with aiosqlite.
pip install peewee[aiomysql]  # Install peewee with aiomysql.
pip install peewee[asyncpg]  # Install peewee with asyncpg.

Examples

Defining models is similar to Django or SQLAlchemy:

.. code-block:: python

from peewee import *
import datetime


db = SqliteDatabase('my_database.db')

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

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

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

Connect to the database and create tables:

.. code-block:: python

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

Create a few rows:

.. code-block:: python

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:

.. code-block:: python

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

# Get tweets created by one of several users.
usernames = ['charlie', 'huey', 'mickey']
users = User.select().where(User.username.in_(usernames))
tweets = Tweet.select().where(Tweet.user.in_(users))

# We could accomplish the same using a JOIN:
tweets = (Tweet
          .select()
          .join(User)
          .where(User.username.in_(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 (for illustrative purposes only, imagine a simple
# table for tracking a "count" associated with each URL). We don't want to
# naively get the save in two separate steps since this is prone to race
# conditions.
Counter.update(count=Counter.count + 1).where(Counter.url == request.url).execute()

Check out the example twitter app <http://docs.peewee-orm.com/en/latest/peewee/example.html>_.

Asyncio

.. code-block:: python

import asyncio
from peewee import *
from playhouse.pwasyncio import AsyncPostgresqlDatabase

db = AsyncPostgresqlDatabase('my_app')

class User(db.Model):
    username = CharField(unique=True)

class Tweet(db.Model):
    user = ForeignKeyField(User, backref='tweets')
    message = TextField()

async def main():
    async with db:
        await db.acreate_tables([User, Tweet])

        # Queries are awaited on the event loop using asyncpg.
        huey = await User.acreate(username='huey')
        tweet = await Tweet.acreate(user=huey, message='meow')

        async with db.atomic():
            tweet.message = 'purr'
            await tweet.asave()

        # Create a query - nothing is executed yet.
        query = Tweet.select(Tweet, User).join(User)

        # Execute and buffer the results.
        tweets = await query.aexecute()  # Or: await db.list(query)
        for tweet in tweets:
            print(tweet.user.username, '->', tweet.message)

        # Streaming results via server-side cursor.
        async for tweet in db.iterate(query):
            print(tweet.user.username, '->', tweet.message)

    await db.close_pool()

asyncio.run(main())

See the asyncio docs <https://docs.peewee-orm.com/en/latest/peewee/asyncio.html>_ for details.

Learning more

Check the documentation <http://docs.peewee-orm.com/>_ for more examples.

Specific question? Come hang out in the #peewee channel on irc.libera.chat, 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 <https://github.com/coleifer/peewee/issues/new>_ on GitHub.

Still want more info?

.. image:: https://media.charlesleifer.com/blog/photos/wat.jpg

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:

peewee (coleifer/peewee)

Searching Database…

12K ·GitHub
Peewee
What is this?Peewee is a small, expressive ORM for Python that lets you work with SQL databases using Python objects and a flexible query-builder.
Is it a framework or just a library?It is a single-module library you import into your app, not a framework — no required dependencies, and it plugs into existing frameworks like Flask or FastAPI.
How do I add it to a project?Install it as a Python package and define your models as classes mapped to database tables, then use the query-builder API to select, insert, update, and delete rows.
Which databases does it work with, and do I need extra drivers?It supports SQLite, MySQL, MariaDB, and PostgreSQL out of the box; no required third-party dependencies are needed for the core library.
Does it support async/await out of the box?Yes, peewee has asyncio support with async iteration over query results via server-side cursors, in addition to its normal synchronous API.
Who is this meant for?Python developers building web apps or services (often with Flask or FastAPI) who want a lightweight ORM instead of a heavier one like SQLAlchemy or Django ORM.
Can I do atomic updates to avoid race conditions?Yes, you can perform atomic updates directly in SQL, like incrementing a counter field in a single update statement, avoiding read-then-write race conditions.
Does it support pagination and ordering helpers?Yes, query results support chainable methods like .orderby() and .paginate() to sort and page through large result sets easily.
Is there a real example app to learn from?Yes, the README points to an example Twitter-style app and several blog posts showing peewee used with Flask for note-taking apps, bookmarking services, and more.
What are similar projects?sequelize, efcore, diesel, typeorm, orm, ent, drizzle-orm, sqlmodel
Which topics is it in?asyncio, flask, orm, fastapi, mysql, sql, sqlite, postgresql, backend, database, server, library
Creator
coleifer
Size
17.1 MB
Stars
12K
Updated
CommitOct 07Release4.5.3Oct 07
Age
16y
Commits · 90 Days