ORM 事件¶

SessionEvents.before_commit（）

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。after_begin（session： Session， transaction： SessionTransaction， connection： Connection）→ 无¶

在连接上开始事务后执行。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_begin')
def receive_after_begin(session, transaction, connection):
    "listen for the 'after_begin' event"

    # ... (event handling logic) ...

注意

此事件在 session 修改自己的内部状态。要在此 hook 中调用 SQL作，请使用为活动提供的联系;不要使用 Session 运行 SQL作径直。

参数

session¶– 目标 Session。
transaction¶—— SessionTransaction。
connection¶– 将用于 SQL 语句的 Connection 对象。

另请参阅

SessionEvents.after_commit（）

QueryEvents.before_compile_delete()

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。after_bulk_delete（delete_context： _O）→ 无¶

调用旧版 Query.delete（） 方法后的事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_bulk_delete')
def receive_after_bulk_delete(delete_context):
    "listen for the 'after_bulk_delete' event"

    # ... (event handling logic) ...

# DEPRECATED calling style (pre-0.9, will be removed in a future release)
@event.listens_for(SomeSessionClassOrObject, 'after_bulk_delete')
def receive_after_bulk_delete(session, query, query_context, result):
    "listen for the 'after_bulk_delete' event"

    # ... (event handling logic) ...

在 0.9 版本发生变更：该 SessionEvents.after_bulk_delete() 事件现在接受参数 SessionEvents.after_bulk_delete.delete_context 。在未来的发行版中，将删除对接受上面列出的先前参数签名为“已弃用”的侦听器函数的支持。

旧版功能

SessionEvents.after_bulk_delete() 方法是 SQLAlchemy 2.0 的遗留事件钩子。活动 不参与使用 delete（） 的 2.0 样式调用，记录在具有自定义 WHERE 条件的 ORM UPDATE 和 DELETE。对于 2.0 样式的使用， SessionEvents.do_orm_execute() 钩子将拦截这些调用。

参数

delete_context¶ –

一个 “delete context” 对象，其中包含有关更新的详细信息，包括以下属性：

session - 涉及的 Session

query - 查询 对象，此更新作被召唤。

result 的 CursorResult 由于批量 DELETE作。

在 1.4 版本发生变更： update_context 不再具有 QueryContext 对象。

另请参阅

SessionEvents.after_bulk_update()

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。after_bulk_update（update_context： _O）→ 无¶

调用旧版 Query.update（） 方法后的事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_bulk_update')
def receive_after_bulk_update(update_context):
    "listen for the 'after_bulk_update' event"

    # ... (event handling logic) ...

# DEPRECATED calling style (pre-0.9, will be removed in a future release)
@event.listens_for(SomeSessionClassOrObject, 'after_bulk_update')
def receive_after_bulk_update(session, query, query_context, result):
    "listen for the 'after_bulk_update' event"

    # ... (event handling logic) ...

在 0.9 版本发生变更：该 SessionEvents.after_bulk_update() 事件现在接受参数 SessionEvents.after_bulk_update.update_context 。在未来的发行版中，将删除对接受上面列出的先前参数签名为“已弃用”的侦听器函数的支持。

旧版功能

SessionEvents.after_bulk_update() 方法是 SQLAlchemy 2.0 的遗留事件钩子。活动 不参与使用 update（） 的 2.0 样式调用具有自定义 WHERE 条件的 ORM UPDATE 和 DELETE。对于 2.0 样式的使用， SessionEvents.do_orm_execute() 钩子将拦截这些调用。

参数

update_context¶ –

一个 “Update Context” 对象，其中包含有关更新的详细信息，包括以下属性：

session - 涉及的 Session

query - 查询 对象，此更新作被召唤。

值传递给 Query.update（） 的

result 的 CursorResult 由于 bulk UPDATE作。

在 1.4 版本发生变更： update_context 不再具有 QueryContext 对象。

另请参阅

QueryEvents.before_compile_update()

SessionEvents.after_bulk_delete()

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。after_commit（session： Session）→ 无¶

在提交发生后执行。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_commit')
def receive_after_commit(session):
    "listen for the 'after_commit' event"

    # ... (event handling logic) ...

注意

SessionEvents.after_commit（） 钩子不是每次刷新的，也就是说，Session 可以向数据库发出 SQL 在事务范围内多次。要拦截这些事件，请使用 SessionEvents.before_flush（）、 SessionEvents.after_flush（） 或 SessionEvents.after_flush_postexec() 事件。

注意

调用 SessionEvents.after_commit（） 事件时，Session 不在活动事务中，因此无法发出 SQL。要发出与每个事务对应的 SQL，请使用 SessionEvents.before_commit（） 事件。

参数: session¶– 目标 Session。

另请参阅

SessionEvents.before_commit（）

SessionEvents.after_begin（）

SessionEvents.before_flush（）

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。after_flush（session： Session， flush_context： UOWTransaction）→ 无¶

在 flush 完成后，但在调用 commit 之前执行。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_flush')
def receive_after_flush(session, flush_context):
    "listen for the 'after_flush' event"

    # ... (event handling logic) ...

请注意，会话的状态仍处于预刷新状态，即 'new'、'dirty' 和 'deleted' 列表仍然显示预刷新状态以及实例属性的历史记录设置。

警告

此事件在 Session 发出 SQL 以修改数据库之后运行，但在它更改其内部状态以反映这些更改之前运行，包括将新插入的对象放入身份映射中。在此事件中发出的 ORM作（例如相关项目的加载）可能会生成新的身份映射条目，这些条目将立即被替换，有时会导致令人困惑的结果。SQLAlchemy 将从版本 1.3.9 开始针对此情况发出警告。

参数

session¶– 目标 Session。
flush_context¶– 内部 UOWTransaction 对象，用于处理 flush 的详细信息。

另请参阅

SessionEvents.after_flush_postexec()

SessionEvents.before_flush（）

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。after_flush_postexec（session： Session， flush_context： UOWTransaction）→ 无¶

在 flush 完成后和 post-exec 状态出现后执行。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_flush_postexec')
def receive_after_flush_postexec(session, flush_context):
    "listen for the 'after_flush_postexec' event"

    # ... (event handling logic) ...

这将是 'new'、'dirty' 和 'deleted' 列表处于最终状态的时候。实际的 commit（）可能已经发生，也可能没有发生，具体取决于 flush 是启动自己的事务还是参与更大的事务。

参数

session¶– 目标 Session。
flush_context¶– 内部 UOWTransaction 对象，用于处理 flush 的详细信息。

另请参阅

SessionEvents.after_flush（）

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。after_rollback（session： Session）→ 无¶

在发生实际 DBAPI 回滚后执行。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_rollback')
def receive_after_rollback(session):
    "listen for the 'after_rollback' event"

    # ... (event handling logic) ...

请注意，此事件仅在针对数据库进行实际回滚时触发 - 它不会在每次如果底层 DBAPI 事务已回滚，则调用 Session.rollback（） 方法。在许多情况下，Session 在此事件期间不会处于 “active” 状态，因为当前交易无效。获取会话 在最外层回滚进行后处于活动状态，使用事件， SessionEvents.after_soft_rollback() 检查 Session.is_active 标志。

参数: session¶– 目标 Session。

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。after_soft_rollback（session： Session， previous_transaction： SessionTransaction）→ 无¶

在发生任何回滚后执行，包括实际上不在 DBAPI 级别发出的“软”回滚。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_soft_rollback')
def receive_after_soft_rollback(session, previous_transaction):
    "listen for the 'after_soft_rollback' event"

    # ... (event handling logic) ...

这对应于嵌套回滚和外部回滚，即调用 DBAPI 的 rollback（）方法的最内层回滚，以及仅从事务堆栈中弹出自身的封闭回滚调用。

给定的 Session 可用于调用 SQL 和 Session.query（）作，首先检查 Session.is_active 标志：

@event.listens_for(Session, "after_soft_rollback")
def do_something(session, previous_transaction):
    if session.is_active:
        session.execute(text("select * from some_table"))

参数

session¶– 目标 Session。
previous_transaction¶– SessionTransaction 事务性标记对象。当前的给定 Session 的 SessionTransaction 可通过 Session.transaction 属性获得。

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。after_transaction_create（session： Session， transaction： SessionTransaction）→ 无¶

在创建新的 SessionTransaction 时执行。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_transaction_create')
def receive_after_transaction_create(session, transaction):
    "listen for the 'after_transaction_create' event"

    # ... (event handling logic) ...

此事件与 SessionEvents.after_begin（） 不同因为它发生在每个 SessionTransaction 中总体而言，与事务开始时相反在单个数据库连接上。它还被调用对于嵌套事务和子事务，并且始终为由相应的 SessionEvents.after_transaction_end() 事件（假设 Session 正常运行）。

参数

session¶—— 目标 Session。

交易¶ –

目标 SessionTransaction。

检测这是否是最外层的 SessionTransaction 与 “subtransaction” 或 SAVEPOINT 相反，测试 SessionTransaction.parent 属性是否为 None：

@event.listens_for(session, "after_transaction_create")
def after_transaction_create(session, transaction):
    if transaction.parent is None:
        ...  # work with top-level transaction

要检测 SessionTransaction 是否为 SAVEPOINT，请使用 SessionTransaction.nested 属性：

@event.listens_for(session, "after_transaction_create")
def after_transaction_create(session, transaction):
    if transaction.nested:
        ...  # work with SAVEPOINT transaction

另请参阅

会话事务

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。after_transaction_end（session： Session， transaction： SessionTransaction）→ 无¶

在 SessionTransaction 的 span 结束时执行。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_transaction_end')
def receive_after_transaction_end(session, transaction):
    "listen for the 'after_transaction_end' event"

    # ... (event handling logic) ...

此事件与 SessionEvents.after_commit（） 不同因为它对应于所有 SessionTransaction 正在使用的对象，包括嵌套事务的对象和子事务匹配，并且始终由相应的 SessionEvents.after_transaction_create() 事件。

参数

session¶—— 目标 Session。

交易¶ –

目标 SessionTransaction。

检测这是否是最外层的 SessionTransaction 与 “subtransaction” 或 SAVEPOINT 相反，测试 SessionTransaction.parent 属性是否为 None：

@event.listens_for(session, "after_transaction_create")
def after_transaction_end(session, transaction):
    if transaction.parent is None:
        ...  # work with top-level transaction

要检测 SessionTransaction 是否为 SAVEPOINT，请使用 SessionTransaction.nested 属性：

@event.listens_for(session, "after_transaction_create")
def after_transaction_end(session, transaction):
    if transaction.nested:
        ...  # work with SAVEPOINT transaction

另请参阅

会话事务

SessionEvents.after_attach（）

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。before_attach（session： Session， instance： _O）→ 无¶

在将实例附加到会话之前执行。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'before_attach')
def receive_before_attach(session, instance):
    "listen for the 'before_attach' event"

    # ... (event handling logic) ...

这是在 add、delete 或 merge 导致对象成为 session 的一部分之前调用的。

另请参阅

SessionEvents.after_commit（）

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。before_commit（session： Session）→ 无¶

在调用 commit 之前执行。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'before_commit')
def receive_before_commit(session):
    "listen for the 'before_commit' event"

    # ... (event handling logic) ...

注意

SessionEvents.before_commit（） 钩子不是每次刷新的，也就是说，Session 可以向数据库发出 SQL 在事务范围内多次。要拦截这些事件，请使用 SessionEvents.before_flush（）、 SessionEvents.after_flush（） 或 SessionEvents.after_flush_postexec() 事件。

参数: session¶– 目标 Session。

另请参阅

SessionEvents.after_begin（）

SessionEvents.after_flush（）

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。before_flush（session： Session， flush_context： UOWTransaction， instances：Sequence[_O]None）→ 无¶

在 flush 进程开始之前执行。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'before_flush')
def receive_before_flush(session, flush_context, instances):
    "listen for the 'before_flush' event"

    # ... (event handling logic) ...

参数

session¶– 目标 Session。
flush_context¶– 内部 UOWTransaction 对象，用于处理 flush 的详细信息。
instances¶– 通常为 None，这是可以传递给 Session.flush（） 方法的对象集合（请注意，此用法已弃用）。

另请参阅

SessionEvents.after_flush_postexec()

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。deleted_to_detached（session： Session， instance： _O）→ 无¶

截取特定对象的“已删除到分离”过渡。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'deleted_to_detached')
def receive_deleted_to_detached(session, instance):
    "listen for the 'deleted_to_detached' event"

    # ... (event handling logic) ...

当已删除的对象从会话中逐出时，将调用此事件。发生这种情况的典型情况是，提交删除对象的 Session 的事务时;对象将从 Deleted 状态移动到 Detached 状态。

当 Session.expunge_all（） 或 Session.close（） 时，也会为在 flush 中删除的对象调用它事件，以及对象是否单独通过 Session.expunge（） 从其已删除状态中删除。

另请参阅

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。deleted_to_persistent（session： Session， instance： _O）→ None¶

截获特定对象的 “deleted to persistent” 过渡。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'deleted_to_persistent')
def receive_deleted_to_persistent(session, instance):
    "listen for the 'deleted_to_persistent' event"

    # ... (event handling logic) ...

仅当已删除的对象时，才会发生此转换由于调用 Session.rollback（） 的在任何其他情况下都不会调用该事件。

另请参阅

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。detached_to_persistent（session： Session， instance： _O）→ 无¶

截获特定对象的 “detached to persistent” 过渡。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'detached_to_persistent')
def receive_detached_to_persistent(session, instance):
    "listen for the 'detached_to_persistent' event"

    # ... (event handling logic) ...

此事件是 SessionEvents.after_attach（） 事件，该事件仅被调用对于此特定过渡。它通常在 Session.add（） 调用，以及在 Session.delete（） 调用（如果对象之前不是与 会话（请注意，标记为 “deleted” 的对象将保持 “persistent” 状态，直到刷新继续）。

注意

如果对象在调用 Session.delete（）时，该对象在调用此事件时尚未标记为已删除。要检测已删除的对象，请检查发送到 SessionEvents.persistent_to_detached() to 事件，或者如果需要在 flush 之前拦截已删除的对象，请检查 SessionEvents.before_flush（） 事件中的 Session.deleted 集合。

参数

session¶ – 目标 Session
instance¶—— 正在作的 ORM 映射实例。

另请参阅

属性 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。dispatch： _Dispatch[_ET] = <sqlalchemy.event.base.SessionEventsDispatch 对象>¶

引用回 _Dispatch 类。

针对 _Dispatch._events 的双向

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。do_orm_execute（orm_execute_state： ORMExecuteState）→ 无¶

拦截代表 ORM Session 对象发生的语句执行。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'do_orm_execute')
def receive_do_orm_execute(orm_execute_state):
    "listen for the 'do_orm_execute' event"

    # ... (event handling logic) ...

对于从 Session.execute（） 方法以及相关方法（如 Session.scalars（） 和 Session.scalar（）的 Session.scalar（） 来获取。截至 SQLAlchemy 1.4 中，所有通过 Session.execute（） 方法以及相关方法 Session.scalars（）、Session.scalar（） 等将参与此活动。此事件钩子不适用于 ORM flush 进程内部发出的查询，即 Flushing 中描述的过程。

注意

SessionEvents.do_orm_execute() 事件钩子仅针对 ORM 语句执行触发，即通过 Session.execute（） 和 Session 对象上的类似方法调用的语句。它不会触发仅由 SQLAlchemy Core 调用的语句，即使用 Connection.execute（） 直接调用的语句，或者以其他方式源自 Engine 对象而不涉及任何 Session 的语句。要拦截所有 SQL 执行，而不管 Core API 还是 ORM API 正在使用中，请参阅 ConnectionEvents 中的事件钩子，例如 ConnectionEvents.before_execute() 和 ConnectionEvents.before_cursor_execute() 。

此外，此事件钩子不适用于在 ORM flush 进程内部发出的查询，即 Flushing 中描述的过程;要拦截 flush 进程中的步骤，请参阅 Persistence Events 和 Mapper 级别的 Flush 事件中描述的事件钩子。

此事件是一个do_事件，这意味着它能够替换 Session.execute（） 方法通常执行的作。其预期用途包括分片和结果缓存方案，这些方案可能寻求在多个数据库连接中调用同一语句，返回从每个连接合并的结果，或者根本不调用该语句，而是从缓存中返回数据。

该钩子打算取代 Query._execute_and_instances 可以在 SQLAlchemy 1.4 之前子类化的方法。

参数: orm_execute_state¶ – ORMExecuteState 的实例，它还包含有关当前执行的所有信息作为辅助函数，用于派生其他通常所需的信息。有关详细信息，请参阅该对象。

另请参阅

执行事件 - 有关如何使用的 SessionEvents.do_orm_execute() 顶级文档

ORMExecuteState - 传递给 SessionEvents.do_orm_execute() event 中包含有关要调用的语句的所有信息。它还提供了一个接口来扩展当前语句、选项和参数，以及一个允许在任何时候以编程方式调用语句的选项。

ORM Query Events - 包括使用 SessionEvents.do_orm_execute()

Dogpile Caching - 如何利用 SessionEvents.do_orm_execute() 事件钩子将 Dogpile 缓存与 ORM Session 集成的示例。

水平分片 - 水平分片示例 / 扩展依赖于 SessionEvents.do_orm_execute() event 钩子在多个后端调用 SQL 语句并返回合并结果。

在 1.4 版本加入.

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。loaded_as_persistent（session： Session， instance： _O）→ 无¶

截获特定对象的 “loaded as persistent” 过渡。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'loaded_as_persistent')
def receive_loaded_as_persistent(session, instance):
    "listen for the 'loaded_as_persistent' event"

    # ... (event handling logic) ...

此事件在 ORM 加载过程中调用，并且与 InstanceEvents.load（） 事件非常相似。但是，这里的事件可以链接到 Session 类或实例，而不是 mapper 或类层次结构，并且可以与其他 session 生命周期事件顺利集成。在调用此事件时，保证该对象存在于会话的标识映射中。

注意

在 Eager 加载器可能已完成之前，在 loader 进程中调用此事件，并且对象的状态可能未完成。此外，对对象调用行级刷新作会将该对象放入新的 loader 上下文中，从而干扰现有的 load 上下文。请参阅 InstanceEvents.load（） 上的注释，了解有关使用 SessionEvents.restore_load_context 参数，其中的工作方式与 InstanceEvents.restore_load_context ，以解决此情况。

参数

session¶ – 目标 Session
instance¶—— 正在作的 ORM 映射实例。

另请参阅

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。pending_to_persistent（session： Session， instance： _O）→ 无¶

截获特定对象的 “pending to persistent” 转换。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'pending_to_persistent')
def receive_pending_to_persistent(session, instance):
    "listen for the 'pending_to_persistent' event"

    # ... (event handling logic) ...

此事件在 flush 进程中调用，类似于在 SessionEvents.after_flush（） 事件中扫描 Session.new 集合。但是，在这种情况下，当调用事件时，对象已移至持久状态。

参数

session¶ – 目标 Session
instance¶—— 正在作的 ORM 映射实例。

另请参阅

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。pending_to_transient（session： Session， instance： _O）→ 无¶

截获特定对象的 “pending to transient” 过渡。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'pending_to_transient')
def receive_pending_to_transient(session, instance):
    "listen for the 'pending_to_transient' event"

    # ... (event handling logic) ...

当尚未刷新的待处理对象从 session 中逐出时，会发生这种不太常见的转换;当 Session.rollback（） 方法回滚事务或使用 Session.expunge（） 方法时，可能会发生这种情况。

参数

session¶ – 目标 Session
instance¶—— 正在作的 ORM 映射实例。

另请参阅

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。persistent_to_deleted（session： Session， instance： _O）→ None¶

截获特定对象的 “persistent to deleted” 过渡。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'persistent_to_deleted')
def receive_persistent_to_deleted(session, instance):
    "listen for the 'persistent_to_deleted' event"

    # ... (event handling logic) ...

当在 flush 中从数据库中删除持久对象的身份时，将调用此事件，但该对象仍与 Session 关联，直到事务完成。

如果事务回滚，则对象将再次移动设置为持久状态，并且 SessionEvents.deleted_to_persistent() event 被调用。如果事务已提交，则对象将变为 detached，这将发出 SessionEvents.deleted_to_detached() 事件。

请注意，虽然 Session.delete（） 方法是将对象标记为已删除的主要公共接口，但许多对象由于级联规则而被删除，这些规则并不总是在 flush 时间之前确定。因此，在刷新继续之前，无法捕获将要删除的每个对象。因此，该 SessionEvents.persistent_to_deleted() 事件在 flush 结束时调用。

另请参阅

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。persistent_to_detached（session： Session， instance： _O）→ 无¶

截获特定对象的 “persistent to detached” 过渡。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'persistent_to_detached')
def receive_persistent_to_detached(session, instance):
    "listen for the 'persistent_to_detached' event"

    # ... (event handling logic) ...

当持久对象从会话中逐出时，将调用此事件。有许多情况会导致这种情况发生，包括：

使用 Session.expunge（） 等方法或 Session.close（）
调用 Session.rollback（） 方法，当对象是该会话事务的 INSERT 语句的一部分时

参数

session¶ – 目标 Session
instance¶—— 正在作的 ORM 映射实例。
deleted¶ —— 布尔值。如果为 True，则表示此对象已移至 detached 状态，因为它已标记为已删除并刷新。

另请参阅

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。persistent_to_transient（session： Session， instance： _O）→ 无¶

截获特定对象的 “persistent to transient” 过渡。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'persistent_to_transient')
def receive_persistent_to_transient(session, instance):
    "listen for the 'persistent_to_transient' event"

    # ... (event handling logic) ...

当已刷新的待处理对象从 session 中逐出时，会发生这种不太常见的转换;当 Session.rollback（） 方法回滚事务时，可能会发生这种情况。

参数

session¶ – 目标 Session
instance¶—— 正在作的 ORM 映射实例。

另请参阅

方法 sqlalchemy.orm.SessionEvents 的 SessionEvents 进行访问。transient_to_pending（session： Session， instance： _O）→ 无¶

截获特定对象的 “transient to pending” 转换。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'transient_to_pending')
def receive_transient_to_pending(session, instance):
    "listen for the 'transient_to_pending' event"

    # ... (event handling logic) ...

此事件是 SessionEvents.after_attach（） 事件，该事件仅被调用对于此特定过渡。它通常在 Session.add（） 调用。

参数

session¶ – 目标 Session
instance¶—— 正在作的 ORM 映射实例。

另请参阅

MapperEvents.before_mapper_configured()

Mapper 事件¶

Mapper 事件钩子包含与单个或多个 Mapper 对象相关的事件，这些对象是将用户定义的类映射到 Table 对象的中心配置对象。在 Mapper 级别发生的事情类型包括：

基于对象的持久化作 - 最流行的映射器钩子是工作单元钩子，例如 MapperEvents.before_insert（）、 MapperEvents.after_update（） 等。这些事件与更粗粒度的会话级事件，例如 SessionEvents.before_flush（） 的 API 中，它们发生在 flush 进程中，基于每个对象;虽然对对象进行更精细的活动更直接，但 Session 功能的可用性是有限的。
Mapper 配置事件 - Mapper 钩子的另一类主要类别是当 Mapper 完成时，当 Mapper 被 Map 时出现的 API 和映射器集配置为相互引用。这些事件包括 MapperEvents.instrument_class() 、 MapperEvents.before_mapper_configured() 和 MapperEvents.mapper_configured() 在个人 Mapper 级别和 MapperEvents.before_configured() 以及 MapperEvents.after_configured() Mapper 对象。

对象名称	描述
MapperEvents	定义特定于映射的事件。

类 sqlalchemy.orm 中。Mapper事件¶

定义特定于映射的事件。

例如：

from sqlalchemy import event


def my_before_insert_listener(mapper, connection, target):
    # execute a stored procedure upon INSERT,
    # apply the value to the row to be inserted
    target.calculated_value = connection.execute(
        text("select my_special_function(%d)" % target.special_number)
    ).scalar()


# associate the listener function with SomeClass,
# to execute during the "before_insert" hook
event.listen(SomeClass, "before_insert", my_before_insert_listener)

可用目标包括：

映射类
已映射或待映射类的未映射超类（使用 propagate=True 标志）
Mapper 对象
Mapper 类本身表示侦听所有 Mapper。

映射器事件提供对映射器关键部分的钩子，包括与对象插桩、对象加载和对象持久性相关的部分。特别是，持久化方法 MapperEvents.before_insert（） 和 MapperEvents.before_update（） 很受欢迎用于增强 state 的 PLACES - 但是，这些方法运行时有几个重要的限制。这鼓励用户评估 SessionEvents.before_flush（） 和 SessionEvents.after_flush（） 方法作为更灵活和用户友好的钩子，在刷新期间应用额外的数据库状态。

使用 MapperEvents 时，listen（） 函数可以使用多个修饰符。

参数

propagate=False¶– 当为 True 时，事件侦听器应应用于所有继承的映射器和/或继承类的映射器，以及作为此侦听器目标的任何映射器。
raw=False¶– 当 True 时，传递给适用事件侦听器函数的 “target” 参数将是实例的 InstanceState 管理对象，而不是映射的实例本身。
retval=False¶ –

当为 True 时，用户定义的事件函数必须具有返回值，其目的是控制后续事件传播，或以其他方式更改映射器正在进行的作。可能的返回值为：
- sqlalchemy.orm.interfaces.EXT_CONTINUE - 继续正常事件处理。
- sqlalchemy.orm.interfaces.EXT_STOP - 取消链中的所有后续事件处理程序。
- other values （其他值） - 由特定侦听器指定的返回值。

成员

after_configured（）， after_delete（）， after_insert（）， after_mapper_constructed（）， after_update（）， before_configured（）， before_delete（）， before_insert（）， before_mapper_configured（）， before_update（），调度， instrument_class（）， mapper_configured（）

类签名

类 sqlalchemy.orm.MapperEvents （sqlalchemy.event.Events）

方法 sqlalchemy.orm.MapperEvents 中。after_configured（）→ 无¶

在配置了一系列映射器后调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_configured')
def receive_after_configured():
    "listen for the 'after_configured' event"

    # ... (event handling logic) ...

MapperEvents.after_configured() 每次 configure_mappers（） 函数为调用，在函数完成其工作后调用。 configure_mappers（） 通常在首次使用 Mapping 时以及每次提供新的 Mapper 可用并检测到新的 Mapper 使用情况时自动调用。

将此事件与 MapperEvents.mapper_configured() 事件，该事件基于每个映射器调用，而配置手术收益;与该事件不同，当调用此事件时，所有交叉配置（例如 backrefs）也将进行可用于任何待处理的映射器。此外，与 MapperEvents.before_configured() 相比，在配置一系列映射器之前调用。

此事件只能应用于 Mapper 类，而不能应用于单个映射或映射类。它仅对所有 mapping 作为一个整体调用：

from sqlalchemy.orm import Mapper


@event.listens_for(Mapper, "after_configured")
def go(): ...

理论上，每个应用程序都会调用一次此事件，但实际上，每当新映射器受到 configure_mappers（） 影响时，都会调用此事件叫。如果新映射是在现有映射具有已使用，则可能会再次调用此事件。为了确保特定事件只调用一次，不再调用， once=True 参数（0.9.4 中的新功能）可以应用：

from sqlalchemy.orm import mapper


@event.listens_for(mapper, "after_configured", once=True)
def go(): ...

另请参阅

MapperEvents.mapper_configured()

MapperEvents.before_configured()

方法 sqlalchemy.orm.MapperEvents 中。after_delete（mapper： Mapper[_O]， connection：连接， target： _O→ 无¶

在发出与该实例对应的 DELETE 语句后接收对象实例。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_delete')
def receive_after_delete(mapper, connection, target):
    "listen for the 'after_delete' event"

    # ... (event handling logic) ...

注意

此事件仅适用于 会话刷新作，并且不适用于 启用 ORM 的 INSERT、UPDATE 和 DELETE 语句。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute() .

此事件用于在给定连接上发出其他 SQL 语句，以及执行与删除事件相关的应用程序特定簿记。

在上一步中一次性发出同一类的一批对象的 DELETE 语句后，通常会为这些对象调用该事件。

警告

映射器级别的 flush 事件只允许非常有限的作，仅对正在作的行的本地属性，以及允许在给定的 连接。请完整阅读 Mapper 级别 Flush Events 中的注释，了解有关使用这些方法的指南;通常，SessionEvents.before_flush（） method 应该是一般 on-flush 更改的首选。

参数

mapper¶—— 作为此事件目标的 Mapper。
connection¶—— 用于为此实例发出 DELETE 语句的 Connection。这为特定于此实例的目标数据库上的当前事务提供了句柄。
target¶ —— 被删除的 Map 实例。如果事件配置为 raw=True，则这将是与实例关联的 InstanceState 状态管理对象。

结果

此事件不支持返回值。

另请参阅

方法 sqlalchemy.orm.MapperEvents 中。after_insert（mapper： Mapper[_O]， connection：连接， target： _O→ 无¶

在发出与该实例对应的 INSERT 语句后接收对象实例。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_insert')
def receive_after_insert(mapper, connection, target):
    "listen for the 'after_insert' event"

    # ... (event handling logic) ...

注意

此事件仅适用于 会话刷新作，并且不适用于 启用 ORM 的 INSERT、UPDATE 和 DELETE 语句。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute() .

此事件用于在 INSERT 发生后修改实例上的仅限 Python 内状态，以及在给定连接上发出其他 SQL 语句。

该事件通常是针对 same class 之后的 INSERT 语句在上一步中立即发出。在极度在极少数情况下，这是不可取的， Mapper 对象可以配置为 batch=False，这将导致实例批次被分解为单独的（并且性能更差的）event->persist->事件步骤。

警告

映射器级别的 flush 事件只允许非常有限的作，仅对正在作的行的本地属性，以及允许在给定的 连接。请完整阅读 Mapper 级别 Flush Events 中的注释，了解有关使用这些方法的指南;通常，SessionEvents.before_flush（） method 应该是一般 on-flush 更改的首选。

参数

mapper¶—— 作为此事件目标的 Mapper。
connection¶—— 用于为此实例发出 INSERT 语句的 Connection。这为特定于此实例的目标数据库上的当前事务提供了句柄。
target¶ —— 被持久化的 Map 实例。如果事件配置为 raw=True，则这将是与实例关联的 InstanceState 状态管理对象。

结果

此事件不支持返回值。

另请参阅

方法 sqlalchemy.orm.MapperEvents 中。after_mapper_constructed（mapper： Mapper[_O]， class_： type[_O]）→ 无¶

当 Mapper 完全构建时，接收 class 和 mapper。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_mapper_constructed')
def receive_after_mapper_constructed(mapper, class_):
    "listen for the 'after_mapper_constructed' event"

    # ... (event handling logic) ...

此事件在 Mapper 完成。这发生在 MapperEvents.instrument_class() 事件之后，在 Mapper 已经完成了其参数的初始传递，以生成其 MapperProperty 对象集合，这些对象可通过 Mapper.get_property（） 访问 method 和 Mapper.iterate_properties 属性。

此事件与 MapperEvents.before_mapper_configured() 事件，因为它是在 Mapper 的构造函数中调用的，而不是在 registry.configure（） 进程中调用的。目前，此事件是唯一适用于希望创建其他映射类以响应此 Mapper 构造的处理程序的事件，当 registry.configure（） 下次运行时，该事件将成为同一 configure 步骤的一部分。

2.0.2 新版功能.

另请参阅

版本控制对象 - 一个示例， MapperEvents.before_mapper_configured() 说明了创建新映射器以记录更改审计历史记录的事件对象。

方法 sqlalchemy.orm.MapperEvents 中。after_update（mapper： Mapper[_O]， connection：连接， target： _O→ 无¶

在发出与该实例对应的 UPDATE 语句后接收对象实例。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_update')
def receive_after_update(mapper, connection, target):
    "listen for the 'after_update' event"

    # ... (event handling logic) ...

注意

此事件仅适用于 会话刷新作，并且不适用于 启用 ORM 的 INSERT、UPDATE 和 DELETE 语句。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute() .

此事件用于在 UPDATE 发生后修改实例上的仅限 Python 内状态，以及在给定连接上发出其他 SQL 语句。

对于标记为 “dirty” 的所有实例，甚至那些没有净变化的实例，都会调用此方法添加到其基于列的属性中，并且没有对其执行任何 UPDATE 语句。当对象的任何基于列的属性调用了“set attribute”作时，或者当其任何集合被修改时，该对象将被标记为脏。如果在更新时，没有基于列的属性有任何净更改，则不会发出 UPDATE 语句。这意味着发送到 MapperEvents.after_update（） 的实例是 不保证已发出 UPDATE 语句。

检测对象上基于列的属性是否具有 net 更改，因此会产生 UPDATE 语句，请使用 object_session(instance).is_modified(instance, include_collections=False) .

在上一步中一次性发出同一类的一批对象的 UPDATE 语句后，通常会为该事件调用该事件。在极少数情况下，这是不可取的，可以将 Mapper 配置为batch=False，这将导致实例批次被分解为单独的（并且性能更差的）event->persist->事件步骤。

警告

映射器级别的 flush 事件只允许非常有限的作，仅对正在作的行的本地属性，以及允许在给定的 连接。请完整阅读 Mapper 级别 Flush Events 中的注释，了解有关使用这些方法的指南;通常，SessionEvents.before_flush（） method 应该是一般 on-flush 更改的首选。

参数

mapper¶—— 作为此事件目标的 Mapper。
connection¶– 用于为此实例发出 UPDATE 语句的 Connection。这为特定于此实例的目标数据库上的当前事务提供了句柄。
target¶ —— 被持久化的 Map 实例。如果事件配置为 raw=True，则这将是与实例关联的 InstanceState 状态管理对象。

结果

此事件不支持返回值。

另请参阅

MapperEvents.before_mapper_configured()

方法 sqlalchemy.orm.MapperEvents 中。before_configured（）→ 无¶

在配置一系列映射器之前调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_configured')
def receive_before_configured():
    "listen for the 'before_configured' event"

    # ... (event handling logic) ...

MapperEvents.before_configured() 每次 configure_mappers（） 函数为调用，在函数完成任何工作之前调用。 configure_mappers（） 通常在首次使用 Mapping 时以及每次提供新的 Mapper 可用并检测到新的 Mapper 使用情况时自动调用。

此事件只能应用于 Mapper 类，而不能应用于单个映射或映射类。它仅对所有 mapping 作为一个整体调用：

from sqlalchemy.orm import Mapper


@event.listens_for(Mapper, "before_configured")
def go(): ...

将此事件与 MapperEvents.after_configured() 进行对比，后者在配置一系列映射器后调用，以及 MapperEvents.before_mapper_configured() 和 MapperEvents.mapper_configured() ，它们都是基于每个映射器调用的。

理论上，每个应用程序都会调用一次此事件，但实际上，每当新映射器要受到 configure_mappers（） 的影响时，都会调用此事件叫。如果新映射是在现有映射具有已使用，则可能会再次调用此事件。为了确保特定事件只调用一次，不再调用， once=True 参数（0.9.4 中的新功能）可以应用：

from sqlalchemy.orm import mapper


@event.listens_for(mapper, "before_configured", once=True)
def go(): ...

另请参阅

MapperEvents.mapper_configured()

MapperEvents.after_configured()

方法 sqlalchemy.orm.MapperEvents 中。before_delete（mapper： Mapper[_O]， connection：连接， target： _O→ 无¶

在发出与该实例对应的 DELETE 语句之前接收该对象实例。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_delete')
def receive_before_delete(mapper, connection, target):
    "listen for the 'before_delete' event"

    # ... (event handling logic) ...

注意

此事件仅适用于 会话刷新作，并且不适用于 启用 ORM 的 INSERT、UPDATE 和 DELETE 语句。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute() .

此事件用于在给定连接上发出其他 SQL 语句，以及执行与删除事件相关的应用程序特定簿记。

在后续步骤中，在立即发出 DELETE 语句之前，通常会为同一类的一批对象调用该事件。

警告

映射器级别的 flush 事件只允许非常有限的作，仅对正在作的行的本地属性，以及允许在给定的 连接。请完整阅读 Mapper 级别 Flush Events 中的注释，了解有关使用这些方法的指南;通常，SessionEvents.before_flush（） method 应该是一般 on-flush 更改的首选。

参数

mapper¶—— 作为此事件目标的 Mapper。
connection¶—— 用于为此实例发出 DELETE 语句的 Connection。这为特定于此实例的目标数据库上的当前事务提供了句柄。
target¶ —— 被删除的 Map 实例。如果事件配置为 raw=True，则这将是与实例关联的 InstanceState 状态管理对象。

结果

此事件不支持返回值。

另请参阅

方法 sqlalchemy.orm.MapperEvents 中。before_insert（mapper： Mapper[_O]， connection：连接， target： _O→ 无¶

在发出与该实例对应的 INSERT 语句之前接收该对象实例。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_insert')
def receive_before_insert(mapper, connection, target):
    "listen for the 'before_insert' event"

    # ... (event handling logic) ...

注意

此事件仅适用于 会话刷新作，并且不适用于 启用 ORM 的 INSERT、UPDATE 和 DELETE 语句。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute() .

此事件用于在 INSERT 发生之前修改实例上的本地非对象相关属性，以及在给定连接上发出其他 SQL 语句。

在后续步骤中，在立即发出其 INSERT 语句之前，通常会为同一类的一批对象调用该事件。在极少数情况下，这是不可取的，可以将 Mapper 对象配置为batch=False，这将导致实例批次被分解为单独的（并且性能更差的）event->persist->事件步骤。

警告

映射器级别的 flush 事件只允许非常有限的作，仅对正在作的行的本地属性，以及允许在给定的 连接。请完整阅读 Mapper 级别 Flush Events 中的注释，了解有关使用这些方法的指南;通常，SessionEvents.before_flush（） method 应该是一般 on-flush 更改的首选。

参数

mapper¶—— 作为此事件目标的 Mapper。
connection¶—— 用于为此实例发出 INSERT 语句的 Connection。这为特定于此实例的目标数据库上的当前事务提供了句柄。
target¶ —— 被持久化的 Map 实例。如果事件配置为 raw=True，则这将是与实例关联的 InstanceState 状态管理对象。

结果

此事件不支持返回值。

另请参阅

MapperEvents.before_configured()

方法 sqlalchemy.orm.MapperEvents 中。before_mapper_configured（mapper： Mapper[_O]， class_： type[_O]）→ 无¶

在配置特定 mapper 之前调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_mapper_configured')
def receive_before_mapper_configured(mapper, class_):
    "listen for the 'before_mapper_configured' event"

    # ... (event handling logic) ...

此事件旨在通过返回接口来允许在 configure 步骤中跳过特定映射器。EXT_SKIP 符号，该符号向 configure_mappers（） 调用指示应在当前配置运行中跳过此特定映射器（或使用 propagate=True 的映射器层次结构）。当跳过一个或多个映射器时，“new mappers” 标志将保持设置状态，这意味着在使用映射器时将继续调用 configure_mappers（） 函数，以继续尝试配置所有可用的映射器。

与其他 configure 级别的事件相比， MapperEvents.before_configured() 、 MapperEvents.after_configured() 和 MapperEvents.mapper_configured() 这 MapperEvents.before_mapper_configured() event 在使用 retval=True 注册时提供有意义的返回值参数。

在 1.3 版本加入.

例如：

from sqlalchemy.orm import EXT_SKIP

Base = declarative_base()

DontConfigureBase = declarative_base()


@event.listens_for(
    DontConfigureBase,
    "before_mapper_configured",
    retval=True,
    propagate=True,
)
def dont_configure(mapper, cls):
    return EXT_SKIP

另请参阅

MapperEvents.after_configured()

MapperEvents.mapper_configured()

方法 sqlalchemy.orm.MapperEvents 中。before_update（mapper： Mapper[_O]， connection：连接， target： _O→ 无¶

在发出与该实例对应的 UPDATE 语句之前接收该对象实例。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_update')
def receive_before_update(mapper, connection, target):
    "listen for the 'before_update' event"

    # ... (event handling logic) ...

注意

此事件仅适用于 会话刷新作，并且不适用于 启用 ORM 的 INSERT、UPDATE 和 DELETE 语句。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute() .

此事件用于在 UPDATE 发生之前修改实例上的本地非对象相关属性，以及在给定连接上发出其他 SQL 语句。

对于标记为 “dirty” 的所有实例，甚至那些没有净变化的实例，都会调用此方法添加到其基于列的属性中。当对象的任何基于列的属性调用了“set attribute”作时，或者当其任何集合被修改时，该对象将被标记为脏。如果在更新时，没有基于列的属性有任何净更改，则不会发出 UPDATE 语句。这意味着发送到 MapperEvents.before_update（） 的实例是 不能保证会发出 UPDATE 语句，尽管您可以通过修改属性来影响此处的结果，以便确实存在 value 的净变化。

检测对象上基于列的属性是否具有 net changes，因此将生成 UPDATE 语句，请使用 object_session(instance).is_modified(instance, include_collections=False) .

在后续步骤中，在立即发出 UPDATE 语句之前，通常会为同一类的一批对象调用该事件。在极少数情况下，这是不可取的，可以将 Mapper 配置为batch=False，这将导致实例批次被分解为单独的（并且性能更差的）event->persist->事件步骤。

警告

映射器级别的 flush 事件只允许非常有限的作，仅对正在作的行的本地属性，以及允许在给定的 连接。请完整阅读 Mapper 级别 Flush Events 中的注释，了解有关使用这些方法的指南;通常，SessionEvents.before_flush（） method 应该是一般 on-flush 更改的首选。

参数

mapper¶—— 作为此事件目标的 Mapper。
connection¶– 用于为此实例发出 UPDATE 语句的 Connection。这为特定于此实例的目标数据库上的当前事务提供了句柄。
target¶ —— 被持久化的 Map 实例。如果事件配置为 raw=True，则这将是与实例关联的 InstanceState 状态管理对象。

结果

此事件不支持返回值。

另请参阅