Peewee：一个轻量小巧的 Python ORM，11k+ Star

peewee 是一款简单小巧的 Python ORM，目前积累了 11,969 个 Star：

它的设计目标是保持概念精简，让开发者可以快速上手，同时提供灵活的查询构造能力。代码库体积不大，核心概念清晰，文档也比较完善。

peewee 支持 SQLite、MySQL、MariaDB 和 PostgreSQL 四种主流数据库，也提供了 asyncio 异步支持。它与 Flask、FastAPI、Pydantic 等框架都能良好集成。

安装方式很直接：

pip install peewee

针对不同数据库，可以选择对应的安装方式：

pip install peewee[mysql]
pip install peewee[postgres]
pip install peewee[psycopg3]

异步场景下也有对应的包：

pip install peewee[aiosqlite]
pip install peewee[aiomysql]
pip install peewee[asyncpg]

---

定义模型

peewee 的模型定义方式与 Django 或 SQLAlchemy 类似：

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)

连接数据库并创建表：

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

创建数据：

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

Tweet.create(user=charlie, message='My first tweet')

字段默认值在创建时会自动填充，不需要手动设置。

---

查询操作

peewee 的查询语法比较直观，支持链式调用和组合查询：

# 单条查询
User.get(User.username == 'charlie')

# IN 查询
usernames = ['charlie', 'huey', 'mickey']
users = User.select().where(User.username.in_(usernames))

# JOIN 查询
tweets = (Tweet
          .select()
          .join(User)
          .where(User.username.in_(usernames)))

# 条件计数
tweets_today = (Tweet
                .select()
                .where(
                    (Tweet.created_date >= datetime.date.today()) &
                    (Tweet.is_published == True))
                .count())

# 分页
User.select().order_by(User.username).paginate(3, 20)

# 聚合排序
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()))

原子更新也可以直接通过查询完成，避免并发竞争：

Counter.update(count=Counter.count + 1).where(Counter.url == request.url)

这些查询方式覆盖了日常开发中的大部分需求。

---

扩展生态

peewee 的 playhouse 模块提供了很多扩展功能，包括数据库迁移、CSV 导入导出、全文搜索等。社区也提供了不少第三方插件，可以按需选用。官方还提供了多个示例项目，包括一个完整的 Twitter 克隆应用，可以帮助新手理解最佳实践。

与 SQLAlchemy 相比，peewee 的学习曲线更平缓，适合中小型项目或需要快速交付的场景。它的 API 设计比较一致，没有过多的抽象层次。对于需要轻量级 ORM 的 Python 项目来说，peewee 是一个值得考虑的选择。

可以帮助新手理解最佳实践。

与 SQLAlchemy 相比，peewee 的学习曲线更平缓，适合中小型项目或需要快速交付的场景。它的 API 设计比较一致，没有过多的抽象层次。对于需要轻量级 ORM 的 Python 项目来说，peewee 是一个值得考虑的选择。