ErisPulse.Core.Bases.model 模块
模块概述
ErisPulse 数据模型层(ORM)—— 声明式模型与 Active Record CRUD
构建于内置存储层(:mod:ErisPulse.Core.storage,SQLite / MySQL / PostgreSQL)
之上:模型对后端透明——切换 ErisPulse.storage.backend 配置即可换库,模型
代码不变。自动建表、增删改查、查询表达式均由字段声明驱动。
声明形态与声明式配置类(Core/Bases/config_schema.py)对齐:一份约束词表
(choices / ge / le / max_length)、同一校验器引擎
(:func:ErisPulse.Core.Bases.config_schema.validate_field_constraints)、
同一类型类别注册表(:func:ErisPulse.Core.Bases.config_schema.python_type_category)。
基座有意分立——配置字段是普通值(TOML 往返),模型字段是列描述符
(类访问=查询表达式,实例访问=行值),生命周期与消费点各自独立。
提示
- 表名默认取类名 snake_case(
UserProfile → user_profile),可用__tablename__覆写Field(autoincrement=True)的主键由数据库自增,create后自动回填 (save主键缺失退化为插入时同样回填)list/dict类型字段(含list[int]等参数化泛型)以 JSON 文本列存储,读写自动序列化- 环境无关:
Model.__storage__可覆写为自定义BaseStorage实例 (默认使用全局ErisPulse.Core.storage单例)- 处于
storage.atransaction()环境事务内时,读写自动复用事务连接, 随事务统一提交/回滚- 关系映射:
relationship()声明 has-many / belongs-to,实例上链式查询 或直接 await(见 :class:Relationship)- 复合主键:多个
Field(primary_key=True)组成表级PRIMARY KEY (a, b)约束(自增主键仅单列);__unique_together__声明联合唯一(唯一索引 实现,已存在的表自动补建)- 惯用快捷:
get_or_create/update_or_create、save(update_fields=[...])部分列更新、Field(auto_now_add=True / auto_now=True)时间戳列、Field(on_delete="CASCADE")外键删除动作
示例:
from ErisPulse.Core.Bases import Model, Field
class User(Model):
id: int = Field(primary_key=True, autoincrement=True)
name: str = Field(max_length=64)
age: int = Field(default=0, ge=0, le=150)
await User.create_table()
alice = await User.create(name="Alice", age=20)
adults = await User.where(User.age > 18).all()
函数列表
_validate_column(name: str) -> str
列名合法性校验(防注入;与 sql_base 的标识符校验同一口径)
_quote_ident(name: str, dialect: SQLDialect | None = None) -> str
标识符引用(优先方言引号;无方言时回落双引号记号,SQLite/Postgres 通用)
async _related_none() -> None
内部方法 belongs-to 外键为 None 时的短路返回值
relationship(related: str | type[Model], foreign_key: str) -> Relationship
声明模型关系(:class:Relationship 的工厂函数,与 Field(...) 同风格)
- related: 对方模型(类名字符串或类)
- foreign_key: 外键列名(声明在对方表为 has-many,本表为 belongs-to)
返回值: 关系描述符
示例:
class User(Model):
messages = relationship("Message", foreign_key="user_id")
msgs = await user.messages.all()
_combine(conditions: tuple) -> Condition | None
多条件 AND 组合(类级 CRUD 快捷入口用)
类列表
class Field
模型字段描述符(声明式列定义)
default: 字段默认值(未提供且非自增主键 → 必填 NOT NULL)
primary_key: 是否主键;多个
primary_key=True字段组成复合主键(DDL 收敛为表级
PRIMARY KEY (a, b)约束)autoincrement: 是否自增主键(隐含 primary_key,整型;单列主键专用,
与其他主键字段共存时模型定义报错)
max_length: 字符串最大长度(生成 VARCHAR(n),并参与写入校验)
nullable: 是否允许 NULL(默认 False → NOT NULL)
index: 是否生成普通索引
unique: 是否唯一约束
choices: 枚举选项(写入校验)
ge: 数值下界(写入校验)
le: 数值上界(写入校验)
description: 字段描述(i18n 字典格式与配置类一致,预留文档/面板用)
column_type: 覆写 SQL 列类型定义(如
"TEXT");默认按类型注册表派生foreign_key: 列级外键约束(
"表.列",如"users.id")——DDL 生成REFERENCES约束(关系映射的基础设施;ORM 级关系对象后续版本交付)on_delete: 外键删除动作(
foreign_key声明时生效):"CASCADE"/
"SET NULL"/"RESTRICT"/"NO ACTION"/"SET DEFAULT", 生成ON DELETE子句;其他值模型定义报错auto_now_add: 插入时自动写入当前时间戳(
time.time()浮点纪秒)auto_now: 插入与实例
save()更新时均自动写入当前时间戳(隐含插入侧行为;
QuerySet.update批量路径不触发)
示例:
id: int = Field(primary_key=True, autoincrement=True)
name: str = Field(max_length=64)
created_at: float = Field(auto_now_add=True)
user_id: int = Field(foreign_key="users.id", on_delete="CASCADE")
方法列表
__new__(*args: Any, **kwargs: Any) -> Any
实例化类型标注为 Any
类体声明 name: str = Field(...) 的赋值侧类型检查:Field 是声明
哨兵(类属性由 Model 机制消费、实例属性由 __init__ 写入真实值),
哨兵本身与声明类型不匹配——返回 Any 让类型检查器跳过赋值侧检查
(pydantic v2 Field() -> Any 同款口径);实例属性读取类型由
声明注解(str / int)提供。
_annotation() -> Any
字段注解(set_name 阶段从 owner annotations 反查)
required -> bool(property)
是否必填(无默认值且非自增且非自动时间列;自动时间列插入时必然打点)
effective_default() -> Any
运行时默认值(default 优先,其次 default_factory,否则 None)
to_db_value(value: Any) -> Any
写入数据库的参数值(JSON 列序列化;其余原样)
is_json -> bool(property)
是否 JSON 序列化列
sql_type() -> str
列类型定义(方言翻译前的统一记号,由 aCreateTable 翻译)
column_definition(*, nullable_override: bool | None = None) -> str
单列 DDL 定义(统一记号)
nullable_override: 覆写可空性渲染(如自动迁移为存量行回填
而强制省略 NOT NULL);None 表示按字段声明
_is_composite_pk() -> bool
内部方法 所属模型是否复合主键(inline PRIMARY KEY 仅单主键列合法)
_sql_literal(value: Any) -> str
默认值的 DDL 字面量(仅声明性默认值,运行值走参数绑定)
提示 已知局限:反斜杠按字面渲染(仅
''转义)。MySQL 默认 sql_mode 下\是字符串转义符,含反斜杠的声明默认值在 MySQL 上的 DDL 语义会偏移;本层无方言信息(统一记号由 aCreateTable 翻译),如需精确跨方言行为请避免在声明默认值中使用反斜杠。
class ColumnExpr
ColumnExpr 类提供相关功能。
方法列表
in_(values: list | tuple) -> Condition
IN 条件(User.id.in_([1, 2, 3]))
class Condition
查询条件节点(叶子比较 / AND-OR 组合),编译为参数化 WHERE 片段
方法列表
__bool__() -> bool
禁用真值判断:条件对象只能传给 :meth:Model.where 等查询入口
compile(dialect: SQLDialect | None = None) -> tuple[str, list[Any]]
编译为 (WHERE 片段, 参数列表);片段为空串表示无条件
- dialect: 方言(提供时标识符按方言引号引用,缺省为双引号记号)
class QuerySet
链式查询集(惰性构建,await 终结符执行)
User.where(...).order_by("-age").limit(10).all()
注意:链式方法(where / order_by / limit / offset)就地修改当前实例
并返回自身——复用中间 QuerySet 对象会让条件互相串染;需要分支查询时,
请各自从 :meth:Model.where 重新构建。
内部方法
由 :meth:Model.where 创建;update / delete 亦经由 QuerySet 应用条件
方法列表
order_by(*fields: str) -> QuerySet
排序("age" 升序 / "-age" 降序)
async all() -> list[Any]
执行查询,返回模型实例列表
async first() -> Any | None
执行查询,返回首个实例(无结果为 None)
在查询集副本上附加 LIMIT 1,不修改原查询集——同一实例先
first() 再 all() 仍返回全量结果。
async count() -> int
统计满足查询条件的总行数
语义说明:count 不受 limit / offset 影响——返回满足 where 条件的 全部行数("符合条件的有多少条"),而非分页窗口内的条数。
async update(**values: Any) -> int
批量更新符合条件的行
返回值: 受影响行数
async delete() -> int
删除符合条件的行
返回值: 受影响行数
class _RelatedMany(QuerySet)
内部方法
has-many 关系查询集:在 :class:QuerySet 全部链式能力之上,
附带 create 自动回填本表主键到对方外键列
方法列表
where(*conditions: Condition) -> _RelatedMany
追加对方表字段的条件过滤(与关系外键条件 AND 组合)
示例:
await user.posts.where(Post.title == "hi").all()
async create(**kwargs: Any) -> Any
创建对方表的一行并自动填入本实例主键
示例:
await user.messages.create(content="hi") # user_id 自动 = user.id
class _RelatedOne
内部方法
belongs-to 单条等待器:author = await msg.author 即解析为对方实例或 None。
外键值为 None 时以短路模式构造(await 直接返回 None,不发起查询)
class Relationship
模型关系声明描述符(has-many / belongs-to)
在模型类体中以类属性形式声明,实例上使用;方向按外键列声明在哪张表 自动判定,惰性解析(首次访问时查注册表),无需预注册顺序:
class User(Model):
id: int = Field(primary_key=True, autoincrement=True)
name: str = Field(max_length=64)
messages = relationship("Message", foreign_key="user_id") # has-many
class Message(Model):
id: int = Field(primary_key=True, autoincrement=True)
user_id: int = Field(foreign_key="users.id")
content: str = Field()
author = relationship("User", foreign_key="user_id") # belongs-to
提示
- 外键列声明在对方表 → has-many:返回 :class:
QuerySet,全部链式能力 可用(await user.messages.order_by("-id").limit(10).all()/.first()/.count()/.delete()),且await user.messages.create(...)自动回填本表主键到对方外键列- 外键列声明在本表 → belongs-to:
author = await msg.author直接 await 得到对方实例(无匹配返回 None;外键值为 None 时跳过查询返回 None)related传类名字符串(按类名注册表惰性解析,两侧模型定义顺序无关) 或直接传模型类- 关系查询与对方模型走同一存储后端(不支持跨后端关联)
方法列表
__init__(related: str | type[Model], foreign_key: str)
声明模型关系
- related: 对方模型(类名或类)
- foreign_key: 外键列名(本表或对方表,判定方向)
_related_model(owner: type) -> type[Model]
解析对方模型(类名字符串按注册表惰性查找)
class Model
模型基类(Active Record)
继承并声明 :class:Field 类属性即可获得自动建表与 CRUD 能力:
class User(Model):
id: int = Field(primary_key=True, autoincrement=True)
name: str = Field(max_length=64)
await User.create_table()
user = await User.create(name="Alice")
user.name = "Bob"
await user.save()
方法列表
_normalize_unique_together(declared: Any) -> tuple[tuple[str, ...], ...](classmethod)
内部方法 unique_together 归一化为分组元组:字符串序列收单组,序列的序列 按多组展开;字段名未声明时定义期报错
_pk_field() -> Field | None(classmethod)
首个主键字段(单主键模型;复合主键语义请用 :meth:_pk_fields)
_pk_fields() -> list[Field](classmethod)
全部主键字段(按声明顺序;复合主键返回多列)
table_name() -> str(classmethod)
表名(snake_case 自动派生或 __tablename__ 覆写)
columns() -> dict[str, Field](classmethod)
字段声明表({字段名: Field})
_get_storage() -> SQLStorageBase(classmethod)
解析存储后端(覆写优先,否则全局单例)
_row_to_instance(row: dict) -> Model(classmethod)
行 dict → 实例(JSON 列反序列化;bool 类别跨后端归一化为 bool)
to_dict() -> dict
导出行数据(JSON 列已反序列化)
_validate() -> None
写入前逐字段约束校验(共享校验器引擎),失败抛 ValueError
async create_table() -> bool(classmethod)
自动建表 + 自动迁移(幂等)
表不存在时 CREATE TABLE IF NOT EXISTS;已存在时对比现有列与
模型字段,为新增字段自动执行 ALTER TABLE ADD COLUMN(阶段二
自动迁移):非主键、剔除 NOT NULL 约束(存量行回填 NULL),主键与
类型变更不在自动迁移范围(需手工处理)。迁移列同步创建其声明的索引。
返回值: 是否成功
_table_constraints(dialect) -> list[str](classmethod)
内部方法 表级 DDL 约束片段(复合主键收敛为 PRIMARY KEY (a, b))
async _create_unique_indexes(storage, dialect) -> None(classmethod)
内部方法
联合唯一分组建唯一索引(CREATE UNIQUE INDEX;存在性预检幂等,
已存在的表无需重建即可补索引)
_index_name(table: str, column: str, prefix: str = 'idx') -> str(classmethod)
内部方法
索引名派生:<prefix>_<表>_<列>。超过 63 字符(PostgreSQL 标识符上限,
超长会被静默截断导致存在性预检永不命中、每次建表重复 CREATE INDEX
失败)时截断并追加稳定哈希后缀,保证跨运行确定性
async _migrate_new_columns(storage) -> list[str](classmethod)
内部方法
自动迁移:为表中新增的模型字段执行 ALTER TABLE ADD COLUMN
迁移列剔除 NOT NULL 约束(存量行回填 NULL),跳过主键(主键变更 需重建表,不属于自动迁移范围)。
- storage: 存储实例
返回值: 本次新增的列名列表
async drop_table() -> bool(classmethod)
删表(危险操作,仅测试与显式维护场景使用)
async has_table() -> bool(classmethod)
表是否存在
where(*conditions: Condition) -> QuerySet(classmethod)
条件查询入口(User.where(User.age > 18) → :class:QuerySet)
多条件以 AND 连接;OR 用 (cond1) | (cond2) 组合。
all() -> QuerySet(classmethod)
无条件查询集(等价 cls.where())
async get(**eq_kwargs: Any) -> Any | None(classmethod)
等值查询首条(User.get(id=1));无结果返回 None
异常: ValueError - 条件字段未在模型中声明时
async create(**kwargs: Any) -> Any(classmethod)
插入一行并返回实例(自增主键自动回填)
处于 storage.atransaction() 环境事务内时,INSERT 复用事务连接,
随事务统一提交/回滚,不独立提交。
异常: ValueError - 约束校验失败(必填缺失 / 枚举外 / 越界 / 超长)
async _insert_and_backfill(instance: Model) -> None(classmethod)
内部方法
INSERT 一行并按需回填自增主键到实例(:meth:create 与 :meth:save 共用)
列参数构建(自增主键交由数据库、可空/有默认字段 None 跳过、JSON 序列化) 与连接路由在此收敛:处于环境事务内复用事务连接,否则开事务专用连接 自管提交(自增回填要求 INSERT 与 last-id 查询同连接)。
- instance: 已完成约束校验的待插入实例
async count(*conditions: Condition) -> int(classmethod)
行数统计(await User.count(User.age > 18))
async delete_all(*conditions: Condition) -> int(classmethod)
批量删除(await User.delete_all(User.age > 18);无条件则全表删除)
async update_all(*conditions: Condition, **values: Any) -> int(classmethod)
批量更新(await User.update_all(User.age > 18, name="adult"))
async get_or_create(defaults: dict[str, Any] | None = None, **kwargs: Any) -> tuple[Any, bool](classmethod)
查得即返回( (实例, False) );无则以 kwargs + defaults 创建( (实例, True) )
- defaults: 仅创建路径补齐的非过滤字段
- kwargs: 等值过滤条件(同时作为创建值)
返回值: (实例, 是否新建)
异常: ValueError - 条件字段未在模型中声明时
并发竞争下两个协程可能同时走到创建分支——唯一约束(主键 / unique /
__unique_together__)会让后到者收到 :class:StorageOperationError;
需要幂等语义时捕获后重查一次。
async update_or_create(defaults: dict[str, Any] | None = None, **kwargs: Any) -> tuple[Any, bool](classmethod)
查得则更新 defaults 字段并保存;无则创建
- defaults: 查得路径的更新字段 / 创建路径的补齐字段(过滤条件字段除外)
- kwargs: 等值过滤条件(同时作为创建值)
返回值: (实例, 是否新建)
异常: ValueError - 条件字段未在模型中声明时
async save(update_fields: list[str] | None = None) -> int
按主键更新本行(先约束校验);主键缺失时退化为插入(自增主键同样回填到本实例)
默认整行覆盖语义——更新除主键外的全部列、无脏检查;并发场景下会
覆盖其他写入方对同一行的修改(丢失更新),且每次写全列。update_fields
指定部分列更新白名单;乐观锁需自行以版本列条件实现。
update_fields: 仅更新白名单列(主键列被忽略;空列表为无操作
返回 0;模型需走插入路径时报错)
返回值: 受影响行数
异常: ValueError - update_fields 含未声明字段 / 模型需插入 /
复合主键字段值不全(复合主键无法退化为插入)
async delete() -> int
按主键删除本行(复合主键按全部主键列定位)
异常: ValueError - 模型无主键或任一主键字段值为空时
返回值: 受影响行数