pynamodb,一个顺手的 Python 库

大家好，我是木木。

今天给大家分享一个顺手的 Python 库，pynamodb。

pynamodb

DynamoDB 的能力很强，但原生 API 写起来偏底层，条件表达式、键结构、属性类型经常把业务代码搅得很散。pynamodb 做的事情，是把 DynamoDB 表包装成 Python 模型：字段、主键、条件和更新动作都可以围绕类来写。它适合已经在 AWS 上使用 DynamoDB，又希望 Python 代码更清晰、更容易维护的团队。

项目地址：https://github.com/pynamodb/PynamoDB

官方文档：https://pynamodb.readthedocs.io/

三大特点

模型直观

用 Model 和 Attribute 定义表结构，hash key、range key、普通字段都能集中描述。

表达式清楚

条件、范围查询和更新动作可以用 Python 运算符组织，比手写 DynamoDB 表达式更稳。

贴近 AWS

它不是本地数据库抽象层，核心仍然服务 DynamoDB，上线时要理解分区键、吞吐和索引设计。

最佳实践

安装方式：pip install pynamodb。

第一段代码解决的问题是：把订单模型转换成 DynamoDB 能理解的属性结构。这里不访问远端服务，只验证模型层的序列化能力。

frompynamodb.modelsimportModelfrompynamodb.attributesimportUnicodeAttribute,NumberAttributeclassOrder(Model):classMeta:table_name="orders"region="us-east-1"host="http://localhost:8000"user_id=UnicodeAttribute(hash_key=True)order_id=UnicodeAttribute(range_key=True)status=UnicodeAttribute()total=NumberAttribute(default=0)order=Order("u-100","o-001",status="paid",total=98)print("keys:",order.user_id,order.order_id)print("simple:",order.to_simple_dict())print("ddb:",order.to_dynamodb_dict())

第二段看条件表达式。DynamoDB 查询经常要把 key condition 和 filter expression 分开考虑，PynamoDB 能先把这些表达式在 Python 侧组织清楚。

frompynamodb.modelsimportModelfrompynamodb.attributesimportUnicodeAttribute,NumberAttributeclassOrder(Model):classMeta:table_name="orders"region="us-east-1"user_id=UnicodeAttribute(hash_key=True)order_id=UnicodeAttribute(range_key=True)status=UnicodeAttribute()total=NumberAttribute(default=0)condition=(Order.status=="paid")&(Order.total>50)range_key=Order.order_id.between("o-001","o-099")print("filter:",condition)print("range:",range_key)

进阶一点看更新动作。计数、状态流转、库存调整这类操作，建议表达成数据库侧的原子更新，而不是先读出来再写回。

frompynamodb.modelsimportModelfrompynamodb.attributesimportUnicodeAttribute,NumberAttributeclassOrder(Model):classMeta:table_name="orders"region="us-east-1"user_id=UnicodeAttribute(hash_key=True)order_id=UnicodeAttribute(range_key=True)status=UnicodeAttribute()total=NumberAttribute(default=0)updates=[Order.total.set(Order.total+10),Order.status.set("review"),]foractioninupdates:print("update:",action)

环境与版本信息

本文示例使用 Python 3.11，pynamodb 版本为 6.1.0，关键依赖包括 botocore 1.42.86。当前包声明 Python 版本要求为 3.7 及以上。

适用场景

适合 AWS DynamoDB 项目、Serverless 后端、订单状态、用户配置、事件记录等按主键访问清晰的数据模型。也适合想让 DynamoDB 表结构更贴近 Python 代码的团队。

不适用场景

如果项目需要复杂 SQL join、跨表事务或临时分析查询，DynamoDB 本身就不一定合适。不了解分区键和访问模式时，也不要只靠 ORM 风格掩盖建模问题。

上线检查

1. 先确认访问模式，再设计 hash key、range key 和 GSI。
2. 生产环境不要误连本地 host，AWS 区域和权限要单独配置。
3. 给条件写入、更新冲突和容量告警补测试。

总结

pynamodb 让 DynamoDB 的 Python 代码更像业务模型。它不能替你设计好表，但能让键、字段、条件和更新动作更清楚地留在代码里。