ErisPulse ErisPulse
在交互式文档中心打开 →
本页章节
本文为静态镜像,内容以交互版为准 在交互式文档中心打开 →

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 往返),模型字段是列描述符 (类访问=查询表达式,实例访问=行值),生命周期与消费点各自独立。

提示

  1. 表名默认取类名 snake_case(UserProfile → user_profile),可用 __tablename__ 覆写
  2. Field(autoincrement=True) 的主键由数据库自增,create 后自动回填 (save 主键缺失退化为插入时同样回填)
  3. list / dict 类型字段(含 list[int] 等参数化泛型)以 JSON 文本列存储,读写自动序列化
  4. 环境无关:Model.__storage__ 可覆写为自定义 BaseStorage 实例 (默认使用全局 ErisPulse.Core.storage 单例)
  5. 处于 storage.atransaction() 环境事务内时,读写自动复用事务连接, 随事务统一提交/回滚
  6. 关系映射:relationship() 声明 has-many / belongs-to,实例上链式查询 或直接 await(见 :class:Relationship)
  7. 复合主键:多个 Field(primary_key=True) 组成表级 PRIMARY KEY (a, b) 约束(自增主键仅单列);__unique_together__ 声明联合唯一(唯一索引 实现,已存在的表自动补建)
  8. 惯用快捷: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 通用)


内部方法 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

提示

  1. 外键列声明在对方表 → has-many:返回 :class:QuerySet,全部链式能力 可用(await user.messages.order_by("-id").limit(10).all() / .first() / .count() / .delete()),且 await user.messages.create(...) 自动回填本表主键到对方外键列
  2. 外键列声明在本表 → belongs-to:author = await msg.author 直接 await 得到对方实例(无匹配返回 None;外键值为 None 时跳过查询返回 None)
  3. related 传类名字符串(按类名注册表惰性解析,两侧模型定义顺序无关) 或直接传模型类
  4. 关系查询与对方模型走同一存储后端(不支持跨后端关联)

方法列表

声明模型关系

  • related: 对方模型(类名或类)
  • foreign_key: 外键列名(本表或对方表,判定方向)

解析对方模型(类名字符串按注册表惰性查找)


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 - 模型无主键或任一主键字段值为空时

返回值: 受影响行数