peewee

a little orm

208 个版本
Changelog
Documentation
Repository
安装
pip install peewee
poetry add peewee
pipenv install peewee
conda install peewee
描述

.. 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.

  • a small, expressive ORM
  • flexible query-builder that exposes full power of SQL
  • supports sqlite, mysql, mariadb, postgresql
  • asyncio support <https://docs.peewee-orm.com/en/latest/peewee/asyncio.html>__ built on the standard async drivers (aiosqlite, asyncpg, aiomysql)
  • tons of extensions
  • use with flask <https://docs.peewee-orm.com/en/latest/peewee/framework_integration.html#flask>, fastapi <https://docs.peewee-orm.com/en/latest/peewee/framework_integration.html#fastapi>, pydantic <https://docs.peewee-orm.com/en/latest/peewee/orm_utils.html#module-playhouse.pydantic_utils>, and more <https://docs.peewee-orm.com/en/latest/peewee/framework_integration.html>.

New to peewee? These may help:

  • Quickstart <https://docs.peewee-orm.com/en/latest/peewee/quickstart.html#quickstart>_
  • Example twitter app <https://docs.peewee-orm.com/en/latest/peewee/example.html#example>_
  • Using peewee interactively <https://docs.peewee-orm.com/en/latest/peewee/interactive.html#interactive>_
  • Models and fields <http://docs.peewee-orm.com/en/latest/peewee/models.html>_
  • Querying <http://docs.peewee-orm.com/en/latest/peewee/querying.html>_
  • Relationships and joins <http://docs.peewee-orm.com/en/latest/peewee/relationships.html>_
  • Extensive library of SQL / Peewee examples <https://docs.peewee-orm.com/en/latest/peewee/query_library.html#query-library>_
  • Flask setup <https://docs.peewee-orm.com/en/latest/peewee/framework_integration.html#flask>_ or FastAPI setup <https://docs.peewee-orm.com/en/latest/peewee/framework_integration.html#fastapi>_

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:

  • Building a note-taking app with Flask and Peewee <https://charlesleifer.com/blog/saturday-morning-hack-a-little-note-taking-app-with-flask/>_ as well as Part 2 <https://charlesleifer.com/blog/saturday-morning-hacks-revisiting-the-notes-app/>_ and Part 3 <https://charlesleifer.com/blog/saturday-morning-hacks-adding-full-text-search-to-the-flask-note-taking-app/>_.
  • Analytics web service built with Flask and Peewee <https://charlesleifer.com/blog/saturday-morning-hacks-building-an-analytics-app-with-flask/>_.
  • Personalized news digest (with a boolean query parser!) <https://charlesleifer.com/blog/saturday-morning-hack-personalized-news-digest-with-boolean-query-parser/>_.
  • Structuring Flask apps with Peewee <https://charlesleifer.com/blog/structuring-flask-apps-a-how-to-for-those-coming-from-django/>_.
  • Creating a lastpass clone with Flask and Peewee <https://charlesleifer.com/blog/creating-a-personal-password-manager/>_.
  • Creating a bookmarking web-service that takes screenshots of your bookmarks <https://charlesleifer.com/blog/building-bookmarking-service-python-and-phantomjs/>_.
  • Building a pastebin, wiki and a bookmarking service using Flask and Peewee <https://charlesleifer.com/blog/dont-sweat-small-stuff-use-flask-blueprints/>_.
  • Encrypted databases with Python and SQLCipher <https://charlesleifer.com/blog/encrypted-sqlite-databases-with-python-and-sqlcipher/>_.
  • Dear Diary: An Encrypted, Command-Line Diary with Peewee <https://charlesleifer.com/blog/dear-diary-an-encrypted-command-line-diary-with-python/>_.
分类
Development Status :: 5 - Production/Stable Intended Audience :: Developers Operating System :: OS Independent Programming Language :: Python :: 3 Topic :: Database Topic :: Software Development :: Libraries :: Python Modules
版本列表
4.1.0 2026-06-16
4.0.9 2026-06-16
4.0.8 2026-06-13
4.0.7 2026-06-11
4.0.6 2026-05-20
4.0.5 2026-04-23
4.0.4 2026-04-02
4.0.3 2026-03-26
4.0.2 2026-03-15
4.0.1 2026-03-01
4.0.0 2026-02-20
3.19.0 2026-01-07
3.18.3 2025-11-03
3.18.2 2025-07-08
3.18.1 2025-04-30
3.18.0 2025-04-29
3.17.9 2025-02-05
3.17.8 2024-11-12
3.17.7 2024-10-15
3.17.6 2024-07-06
3.17.5 2024-05-10
3.17.4 2024-05-10
3.17.3 2024-04-17
3.17.2 2024-04-16
3.17.1 2024-02-05
3.17.0 2023-10-13
3.16.3 2023-08-14
3.16.2 2023-04-21
3.16.1 2023-04-18
3.16.0 2023-02-27
3.15.4 2022-11-11
3.15.3 2022-09-22
3.15.2 2022-08-26
3.15.1 2022-07-12
3.15.0 2022-06-17
3.14.10 2022-03-07
3.14.9 2022-02-15
3.14.8 2021-10-28
3.14.7 2021-10-27
3.14.6 2021-10-27
3.14.4 2021-03-19
3.14.3 2021-03-11
3.14.2 2021-03-04
3.14.1 2021-02-07
3.14.0 2020-11-07
3.13.3 2020-04-24
3.13.2 2020-03-27
3.13.1 2019-12-06
3.13.0 2019-12-06
3.12.0 2019-11-25
3.11.2 2019-09-24
3.11.1 2019-09-23
3.11.0 2019-09-19
3.10.0 2019-08-03
3.9.6 2019-06-06
3.9.5 2019-04-26
3.9.4 2019-04-14
3.9.3 2019-03-23
3.9.2 2019-03-06
3.9.1 2019-03-06
3.9.0 2019-03-06
3.8.2 2019-01-17
3.8.1 2019-01-07
3.8.0 2018-12-16
3.7.1 2018-10-05
3.7.0 2018-09-06
3.6.4 2018-07-18
3.6.3 2018-07-18
3.6.2 2018-07-18
3.6.1 2018-07-17
3.6.0 2018-07-17
3.5.2 2018-07-03
3.5.1 2018-06-27
3.5.0 2018-05-29
3.4.0 2018-05-20
3.3.4 2018-05-04
3.3.3 2018-05-03
3.3.2 2018-05-01
3.3.1 2018-04-26
3.3.0 2018-04-24
3.2.5 2018-04-19
3.2.4 2018-04-18
3.2.3 2018-04-16
3.2.2 2018-04-01
3.2.1 2018-03-31
3.2.0 2018-03-28
3.1.7 2018-03-27
3.1.6 2018-03-26
3.1.5 2018-03-14
3.1.4 2018-03-14
3.1.3 2018-03-10
3.1.2 2018-02-28
3.1.1 2018-02-27
3.1.0 2018-02-23
3.0.19 2018-02-21
3.0.18 2018-02-14
3.0.17 2018-02-10
3.0.16 2018-02-08
3.0.15 2018-02-08
3.0.14 2018-02-07
3.0.13 2018-02-06
3.0.12 2018-02-05
3.0.11 2018-02-04
3.0.10 2018-02-02
3.0.9 2018-02-01
3.0.8 2018-01-31
3.0.7 2018-01-31
3.0.6 2018-01-30
3.0.5 2018-01-30
3.0.4 2018-01-30
3.0.3 2018-01-30
3.0.2 2018-01-29
3.0.1 2018-01-29
2.10.2 2017-10-08
2.10.1 2017-05-09
2.10.0 2017-05-08
2.9.2 2017-04-07
2.9.1 2017-03-12
2.9.0 2017-03-06
2.8.8 2017-02-26
2.8.7 2017-02-22
2.8.5 2016-10-03
2.8.4 2016-10-02
2.8.3 2016-08-25
2.8.2 2016-08-09
2.8.1 2016-05-04
2.8.0 2016-01-14
2.7.4 2015-12-04
2.7.3 2015-11-21
2.7.2 2015-11-21
2.7.1 2015-11-20
2.7.0 2015-11-20
2.6.4 2015-09-22
2.6.3 2015-07-07
2.6.2 2015-07-02
2.6.1 2015-05-29
2.6.0 2015-04-22
2.5.1 2015-04-05
2.5.0 2015-03-21
2.4.7 2015-02-04
2.4.6 2015-01-22
2.4.5 2014-12-22
2.4.4 2014-12-03
2.4.3 2014-11-24
2.4.2 2014-11-08
2.4.1 2014-10-28
2.4.0 2014-10-18
2.3.3 2014-09-30
2.3.2 2014-09-15
2.3.1 2014-08-19
2.3.0 2014-08-12
2.2.5 2014-07-08
2.2.4 2014-05-14
2.2.3 2014-04-21
2.2.2 2014-03-13
2.2.1 2014-02-12
2.2.0 2014-01-29
2.1.7 2013-12-26
2.1.6 2013-11-19
2.1.5 2013-10-22
2.1.4 2013-08-07
2.1.3 2013-06-29
2.1.2 2013-05-22
2.1.1 2013-04-14
2.1.0 2013-04-02
2.0.9 2013-03-25
2.0.8 2013-03-03
2.0.7 2013-01-26
2.0.6 2013-01-09
2.0.5 2012-12-21
2.0.4 2012-11-18
2.0.3 2012-10-30
2.0.2 2012-10-15
2.0.1 2012-10-09
2.0.0 2012-10-08
1.0.0 2012-08-26
0.9.9 2012-07-03
0.9.8 2012-06-23
0.9.7 2012-06-04
0.9.6 2012-05-09
0.9.5 2012-04-24
0.9.4 2012-04-09
0.9.3 2012-04-06
0.9.2 2012-03-20
0.9.1 2012-03-13
0.9.0 2012-02-01
0.8.2 2012-01-31
0.8.1 2012-01-29
0.8.0 2012-01-08
0.7.5 2011-12-28
0.7.4 2011-11-17
0.7.3 2011-10-01
0.7.2 2011-09-29
0.7.1 2011-09-17
0.7.0 2011-09-14
0.6.2 2011-09-07
0.6.1 2011-07-18
0.6.0 2011-07-18
0.5.0 2011-06-30
0.4.0 2011-06-08
0.3.2 2011-02-12
0.3.1 2011-01-31
0.3.0 2010-11-28
0.2.2 2010-11-25
0.2.1 2010-11-23
0.2.0 2010-11-23
0.1.1 2010-11-19
0.1.0 2010-10-18
相关教程
Peewee 轻量 ORM：简洁的 Python 数据库库
使用简洁易用的 Peewee 定义模型，执行查询和迁移，适合中小型项目。