SQLAlchemy 2.0 文档

SessionEvents.before_commit()

method sqlalchemy.orm.SessionEvents.after_begin(session: Session, transaction: SessionTransaction, connection: Connection) → None¶

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

示例参数形式

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 修改其自身内部状态的过程中调用。要在该钩子中调用 SQL 操作，请使用提供给事件的 Connection；不要直接使用 Session 运行 SQL 操作。

参数:

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

另请参阅

SessionEvents.after_commit()

QueryEvents.before_compile_delete()

method sqlalchemy.orm.SessionEvents.after_bulk_delete(delete_context: _O) → None¶

用于在调用旧版 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) ...

Changed in version 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¶ –

一个 “删除上下文” 对象，其中包含有关更新的详细信息，包括以下属性

session - 涉及的 Session

query - 调用此更新操作的 Query 对象。

result 作为批量 DELETE 操作的结果返回的 CursorResult。

Changed in version 1.4: update_context 不再有关联的 QueryContext 对象。

另请参阅

SessionEvents.after_bulk_update()

method sqlalchemy.orm.SessionEvents.after_bulk_update(update_context: _O) → None¶

用于在调用旧版 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) ...

Changed in version 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¶ –

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

session - 涉及的 Session

query - 调用此更新操作的 Query 对象。

values 传递给 Query.update() 的 “values” 字典。

result 作为批量 UPDATE 操作的结果返回的 CursorResult。

Changed in version 1.4: update_context 不再有关联的 QueryContext 对象。

另请参阅

QueryEvents.before_compile_update()

SessionEvents.after_bulk_delete()

method sqlalchemy.orm.SessionEvents.after_commit(session: Session) → None¶

在提交发生后执行。

示例参数形式

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() 钩子不是每次 flush 都执行，也就是说，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()

method sqlalchemy.orm.SessionEvents.after_flush(session: Session, flush_context: UOWTransaction) → None¶

在 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) ...

请注意，会话的状态仍处于 pre-flush 状态，即 ‘new’、‘dirty’ 和 ‘deleted’ 列表仍显示 pre-flush 状态以及实例属性的历史记录设置。

警告

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

参数:

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

另请参阅

SessionEvents.after_flush_postexec()

SessionEvents.before_flush()

method sqlalchemy.orm.SessionEvents.after_flush_postexec(session: Session, flush_context: UOWTransaction) → None¶

在刷新完成后以及后执行状态发生后执行。

示例参数形式

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() 可能已经发生，也可能尚未发生，这取决于刷新是否启动了自己的事务或参与了更大的事务。

参数:

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

另请参阅

SessionEvents.after_flush()

method sqlalchemy.orm.SessionEvents.after_rollback(session: Session) → None¶

在真正的 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”状态，因为当前事务无效。要获取在最外层回滚完成后处于活动状态的 Session，请使用 SessionEvents.after_soft_rollback() 事件，并检查 Session.is_active 标志。

参数:: session¶ – 目标 Session。

method sqlalchemy.orm.SessionEvents.after_soft_rollback(session: Session, previous_transaction: SessionTransaction) → None¶

在任何回滚发生后执行，包括实际上未在 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 属性获得。

method sqlalchemy.orm.SessionEvents.after_transaction_create(session: Session, transaction: SessionTransaction) → None¶

当新的 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。

transaction¶ –

目标 SessionTransaction。

要检测这是否是最外层的 SessionTransaction，而不是“子事务”或 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

另请参阅

SessionTransaction

method sqlalchemy.orm.SessionEvents.after_transaction_end(session: Session, transaction: SessionTransaction) → None¶

当 SessionTransaction 的跨度结束时执行。

示例参数形式

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。

transaction¶ –

目标 SessionTransaction。

要检测这是否是最外层的 SessionTransaction，而不是“子事务”或 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

另请参阅

SessionTransaction

SessionEvents.after_attach()

method sqlalchemy.orm.SessionEvents.before_attach(session: Session, instance: _O) → None¶

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

示例参数形式

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) ...

在添加、删除或合并导致对象成为会话一部分之前调用此方法。

另请参阅

SessionEvents.after_commit()

method sqlalchemy.orm.SessionEvents.before_commit(session: Session) → None¶

在调用 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()

method sqlalchemy.orm.SessionEvents.before_flush(session: Session, flush_context: UOWTransaction, instances: Sequence[_O] | None) → None¶

在刷新过程开始之前执行。

示例参数形式

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 对象，用于处理刷新的详细信息。
instances¶ – 通常为 None，这是可以传递给 Session.flush() 方法的对象集合（请注意，不推荐使用此方法）。

另请参阅

SessionEvents.after_flush_postexec()

method sqlalchemy.orm.SessionEvents.deleted_to_detached(session: Session, instance: _O) → None¶

拦截特定对象的“已删除到分离”的转换。

示例参数形式

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 的事务（在其中删除了对象）时；对象从已删除状态移动到分离状态。

当调用 Session.expunge_all() 或 Session.close() 事件时，以及如果通过 Session.expunge() 从其已删除状态单独逐出对象时，也会调用此事件。

另请参阅

method sqlalchemy.orm.SessionEvents.deleted_to_persistent(session: Session, instance: _O) → None¶

拦截特定对象的“已删除到持久”的转换。

示例参数形式

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() 而恢复在刷新中已成功删除的对象时，才会发生此转换。在任何其他情况下都不会调用该事件。

另请参阅

method sqlalchemy.orm.SessionEvents.detached_to_persistent(session: Session, instance: _O) → None¶

拦截特定对象的“分离到持久”的转换。

示例参数形式

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() 调用期间调用（如果对象先前未与 Session 关联）（请注意，标记为“deleted”的对象在刷新进行之前仍保持“持久”状态）。

注意

如果对象由于调用 Session.delete() 而变为持久状态，则在调用此事件时，该对象尚未标记为已删除。要检测已删除的对象，请检查发送到 SessionEvents.persistent_to_detached() 的 deleted 标志，以便在刷新进行后触发事件，或者如果需要在刷新之前拦截已删除的对象，请检查 Session.deleted 集合（在 SessionEvents.before_flush() 事件中）。

参数:

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

另请参阅

attribute sqlalchemy.orm.SessionEvents.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.SessionEventsDispatch object>¶

引用回到 _Dispatch 类。

与 _Dispatch._events 双向关联

method sqlalchemy.orm.SessionEvents.do_orm_execute(orm_execute_state: ORMExecuteState) → None¶

拦截代表 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() 方法调用的所有顶级 SQL 语句以及相关方法（例如 Session.scalars() 和 Session.scalar()）调用。从 SQLAlchemy 1.4 开始，所有通过 Session.execute() 方法以及相关方法 Session.scalars()、Session.scalar() 等运行的 ORM 查询都将参与此事件。此事件挂钩不适用于在 ORM 刷新过程内部发出的查询，即刷新中描述的过程。

注意

SessionEvents.do_orm_execute() 事件钩子仅在 ORM 语句执行时触发，这意味着仅当通过 Session.execute() 以及 Session 对象上的类似方法调用时触发。它不会为仅由 SQLAlchemy Core 调用的语句触发，即直接使用 Connection.execute() 或源自 Engine 对象（不涉及任何 Session）的语句触发。要拦截所有 SQL 执行，无论是否使用 Core 或 ORM API，请参阅 ConnectionEvents 中的事件钩子，例如 ConnectionEvents.before_execute() 和 ConnectionEvents.before_cursor_execute()。

此外，此事件钩子不适用于在 ORM flush 进程内部发出的查询，即 Flushing 中描述的进程；要拦截 flush 进程中的步骤，请参阅 持久化事件 以及 映射器级 Flush 事件 中描述的事件钩子。

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

此钩子旨在取代在 SQLAlchemy 1.4 之前可以子类化的 Query._execute_and_instances 方法的使用。

参数:: orm_execute_state¶ – ORMExecuteState 的一个实例，其中包含有关当前执行的所有信息，以及用于派生其他常用信息的辅助函数。有关详细信息，请参阅该对象。

另请参阅

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

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

ORM 查询事件 - 包括使用 SessionEvents.do_orm_execute() 的示例

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

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

1.4 版本新增。

method sqlalchemy.orm.SessionEvents.loaded_as_persistent(session: Session, instance: _O) → None¶

拦截特定对象的“加载为持久化”转换。

示例参数形式

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 类或实例，而不是映射器或类层次结构，并且与其他会话生命周期事件平滑集成。调用此事件时，对象保证存在于会话的身份映射中。

注意

此事件在加载器进程中调用，在 eager 加载器可能完成之前，并且对象的状态可能不完整。此外，对对象调用行级刷新操作会将对象置于新的加载器上下文中，从而干扰现有的加载上下文。有关使用 SessionEvents.restore_load_context 参数的背景信息，请参阅关于 InstanceEvents.load() 的注释，它与 InstanceEvents.restore_load_context 的工作方式相同，以解决这种情况。

参数:

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

另请参阅

method sqlalchemy.orm.SessionEvents.pending_to_persistent(session: Session, instance: _O) → None¶

拦截特定对象的“pending 到 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 集合。但是，在这种情况下，当调用事件时，对象已经移动到 persistent 状态。

参数:

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

另请参阅

method sqlalchemy.orm.SessionEvents.pending_to_transient(session: Session, instance: _O) → None¶

拦截特定对象的“pending 到 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) ...

当尚未 flush 的 pending 对象从会话中逐出时，会发生这种不太常见的转换；当 Session.rollback() 方法回滚事务，或者当使用 Session.expunge() 方法时，可能会发生这种情况。

参数:

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

另请参阅

method sqlalchemy.orm.SessionEvents.persistent_to_deleted(session: Session, instance: _O) → None¶

拦截特定对象的“persistent 到 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 关联，直到事务完成。

如果事务回滚，则对象再次移动到 persistent 状态，并调用 SessionEvents.deleted_to_persistent() 事件。如果事务提交，则对象变为 detached，这将发出 SessionEvents.deleted_to_detached() 事件。

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

另请参阅

method sqlalchemy.orm.SessionEvents.persistent_to_detached(session: Session, instance: _O) → None¶

拦截特定对象的“persistent 到 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 状态是因为它被标记为已删除并已 flush。

另请参阅

method sqlalchemy.orm.SessionEvents.persistent_to_transient(session: Session, instance: _O) → None¶

拦截特定对象的“persistent 到 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) ...

当已 flush 的 pending 对象从会话中逐出时，会发生这种不太常见的转换；当 Session.rollback() 方法回滚事务时，可能会发生这种情况。

参数:

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

另请参阅

method sqlalchemy.orm.SessionEvents.transient_to_pending(session: Session, instance: _O) → None¶

拦截特定对象的“transient 到 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 映射实例。

另请参阅

after_configured(), after_delete(), after_insert(), after_mapper_constructed(), after_update(), before_configured(), before_delete(), before_insert(), before_mapper_configured(), before_update(), dispatch, instrument_class(), mapper_configured()

映射器事件¶

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

每个对象的持久化操作 - 最流行的映射器钩子是工作单元钩子，例如 MapperEvents.before_insert()、 MapperEvents.after_update() 等。这些事件与更粗粒度的会话级别事件（例如 SessionEvents.before_flush()）形成对比，因为它们在 flush 进程中按每个对象发生；虽然对对象的更细粒度的活动更直接，但 Session 功能的可用性受到限制。
映射器配置事件 - 另一类主要的映射器钩子是在映射类、最终确定映射器以及配置映射器集以相互引用时发生的钩子。这些事件包括单个 Mapper 级别的 MapperEvents.instrument_class()、 MapperEvents.before_mapper_configured() 和 MapperEvents.mapper_configured()，以及 MapperEvents.before_configured() 和 MapperEvents.after_configured() 在 Mapper 对象集合级别。

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

class sqlalchemy.orm.MapperEvents¶

定义特定于映射的事件。

例如：

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 类本身表示监听所有映射器。

映射器事件提供了进入映射器关键部分的钩子，包括与对象检测、对象加载和对象持久化相关的部分。特别是，持久化方法 MapperEvents.before_insert() 和 MapperEvents.before_update() 是增强要持久化的状态的常用位置 - 但是，这些方法在几个重要的限制下运行。建议用户评估 SessionEvents.before_flush() 和 SessionEvents.after_flush() 方法，作为在 flush 期间应用其他数据库状态的更灵活和用户友好的钩子。

当使用 MapperEvents 时，listen() 函数可以使用多个修饰符。

参数:

propagate=False¶ – 当为 True 时，事件监听器应应用于所有继承的映射器和/或继承类的映射器，以及作为此监听器目标的任何映射器。
raw=False¶ – 当为 True 时，传递给适用事件监听器函数的 “target” 参数将是实例的 InstanceState 管理对象，而不是映射的实例本身。
retval=False¶ –
当为 True 时，用户定义的事件函数必须具有返回值，其目的是控制后续事件传播，或以其他方式更改映射器正在进行的操作。可能的返回值是
- sqlalchemy.orm.interfaces.EXT_CONTINUE - 正常继续事件处理。
- sqlalchemy.orm.interfaces.EXT_STOP - 取消链中所有后续事件处理程序。
- 其他值 - 由特定监听器指定的返回值。

成员

类签名

类 sqlalchemy.orm.MapperEvents (sqlalchemy.event.Events)

方法 sqlalchemy.orm.MapperEvents.after_configured() → None¶

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

示例参数形式

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() 通常在首次使用映射时自动调用，并且在每次有新的映射器可用并检测到新的映射器使用时也会调用。

此事件与 MapperEvents.mapper_configured() 事件形成对比，后者在配置操作进行时针对每个映射器调用；与该事件不同，当此事件被调用时，所有交叉配置（例如，反向引用）也将可用于任何待处理的映射器。另请注意与 MapperEvents.before_configured() 的对比，后者在一系列映射器配置之前被调用。

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

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.before_mapper_configured()

MapperEvents.mapper_configured()

MapperEvents.before_configured()

方法 sqlalchemy.orm.MapperEvents.after_delete(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

在发出与该实例对应的 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) ...

注意

此事件仅适用于 session flush 操作，并且不适用于 ORM-Enabled INSERT, UPDATE, and DELETE statements 中描述的 ORM DML 操作。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute()。

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

该事件通常在先前步骤中一次性发出 DELETE 语句后，针对同一类的一批对象调用。

警告

映射器级别的 flush 事件仅允许非常有限的操作，仅限于对正在操作的行本地的属性，并允许在给定的 Connection 上发出任何 SQL。 请完整阅读 映射器级别 Flush 事件中的注释，以获取有关使用这些方法的指南；通常，对于一般的 flush 时更改，应首选 SessionEvents.before_flush() 方法。

参数:

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

返回值:

此事件不支持返回值。

另请参阅

方法 sqlalchemy.orm.MapperEvents.after_insert(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

在发出与该实例对应的 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) ...

注意

此事件仅适用于 session flush 操作，并且不适用于 ORM-Enabled INSERT, UPDATE, and DELETE statements 中描述的 ORM DML 操作。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute()。

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

该事件通常在先前步骤中一次性发出 INSERT 语句后，针对同一类的一批对象调用。在极少数情况下，如果这不可取，则可以使用 batch=False 配置 Mapper 对象，这将导致将批处理实例分解为单独的（且性能较差的）事件->持久化->事件步骤。

警告

映射器级别的 flush 事件仅允许非常有限的操作，仅限于对正在操作的行本地的属性，并允许在给定的 Connection 上发出任何 SQL。 请完整阅读 映射器级别 Flush 事件中的注释，以获取有关使用这些方法的指南；通常，对于一般的 flush 时更改，应首选 SessionEvents.before_flush() 方法。

参数:

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

返回值:

此事件不支持返回值。

另请参阅

方法 sqlalchemy.orm.MapperEvents.after_mapper_constructed(mapper: Mapper[_O], class_: Type[_O]) → None¶

在 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() 方法和 Mapper.iterate_properties 属性访问。

此事件与 MapperEvents.before_mapper_configured() 事件不同，后者在 Mapper 的构造函数中调用，而不是在 registry.configure() 进程中调用。目前，此事件是唯一适用于希望响应此 Mapper 的构建来创建其他映射类的处理程序，这将是 registry.configure() 下次运行时同一配置步骤的一部分。

2.0.2 版本新增。

另请参阅

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

方法 sqlalchemy.orm.MapperEvents.after_update(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

在发出与该实例对应的 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) ...

注意

此事件仅适用于 session flush 操作，并且不适用于 ORM-Enabled INSERT, UPDATE, and DELETE statements 中描述的 ORM DML 操作。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute()。

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

对于所有标记为“脏”的实例，即使那些对其基于列的属性没有净更改的实例，以及没有执行 UPDATE 语句的实例，也会调用此方法。当任何基于列的属性调用了“set attribute”操作或修改了任何集合时，对象将被标记为脏。如果在更新时，没有基于列的属性有任何净更改，则不会发出 UPDATE 语句。这意味着发送到 MapperEvents.after_update() 的实例不能保证已发出 UPDATE 语句。

要检测对象上基于列的属性是否具有净更改，并因此导致 UPDATE 语句，请使用 object_session(instance).is_modified(instance, include_collections=False)。

该事件通常在先前步骤中一次性发出 UPDATE 语句后，针对同一类的一批对象调用。在极少数情况下，如果这不可取，则可以使用 batch=False 配置 Mapper，这将导致将批处理实例分解为单独的（且性能较差的）事件->持久化->事件步骤。

警告

映射器级别的 flush 事件仅允许非常有限的操作，仅限于对正在操作的行本地的属性，并允许在给定的 Connection 上发出任何 SQL。 请完整阅读 映射器级别 Flush 事件中的注释，以获取有关使用这些方法的指南；通常，对于一般的 flush 时更改，应首选 SessionEvents.before_flush() 方法。

参数:

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

返回值:

此事件不支持返回值。

另请参阅

MapperEvents.before_mapper_configured()

方法 sqlalchemy.orm.MapperEvents.before_configured() → None¶

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

示例参数形式

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() 通常在首次使用映射时自动调用，并且在每次有新的映射器可用并检测到新的映射器使用时也会调用。

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

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: Connection, target: _O) → None¶

在发出与该实例对应的 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) ...

注意

此事件仅适用于 session flush 操作，并且不适用于 ORM-Enabled INSERT, UPDATE, and DELETE statements 中描述的 ORM DML 操作。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute()。

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

该事件通常在稍后步骤中一次性发出 DELETE 语句之前，针对同一类的一批对象调用。

警告

映射器级别的 flush 事件仅允许非常有限的操作，仅限于对正在操作的行本地的属性，并允许在给定的 Connection 上发出任何 SQL。 请完整阅读 映射器级别 Flush 事件中的注释，以获取有关使用这些方法的指南；通常，对于一般的 flush 时更改，应首选 SessionEvents.before_flush() 方法。

参数:

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

返回值:

此事件不支持返回值。

另请参阅

方法 sqlalchemy.orm.MapperEvents.before_insert(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

在发出与该实例对应的 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) ...

注意

此事件仅适用于 session flush 操作，并且不适用于 ORM-Enabled INSERT, UPDATE, and DELETE statements 中描述的 ORM DML 操作。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute()。

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

该事件通常在稍后步骤中一次性发出 INSERT 语句之前，针对同一类的一批对象调用。在极少数情况下，如果这不可取，则可以使用 batch=False 配置 Mapper 对象，这将导致将批处理实例分解为单独的（且性能较差的）事件->持久化->事件步骤。

警告

映射器级别的 flush 事件仅允许非常有限的操作，仅限于对正在操作的行本地的属性，并允许在给定的 Connection 上发出任何 SQL。 请完整阅读 映射器级别 Flush 事件中的注释，以获取有关使用这些方法的指南；通常，对于一般的 flush 时更改，应首选 SessionEvents.before_flush() 方法。

参数:

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

返回值:

此事件不支持返回值。

另请参阅

MapperEvents.before_configured()

方法 sqlalchemy.orm.MapperEvents.before_mapper_configured(mapper: Mapper[_O], class_: Type[_O]) → None¶

在即将配置特定映射器之前调用。

示例参数形式

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) ...

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

与其他配置级别事件 MapperEvents.before_configured()、MapperEvents.after_configured() 和 MapperEvents.mapper_configured() 相比，MapperEvents.before_mapper_configured() 事件在注册 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: Connection, target: _O) → None¶

在发出与对象实例对应的 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) ...

注意

此事件仅适用于 session flush 操作，并且不适用于 ORM-Enabled INSERT, UPDATE, and DELETE statements 中描述的 ORM DML 操作。要拦截 ORM DML 事件，请使用 SessionEvents.do_orm_execute()。

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

此方法为所有标记为“脏”的实例调用，即使是那些基于列的属性没有净更改的实例。当任何基于列的属性调用了“set attribute”操作或任何集合被修改时，对象都会被标记为脏。如果在更新时，没有基于列的属性有任何净更改，则不会发出 UPDATE 语句。这意味着发送到 MapperEvents.before_update() 的实例并不能保证会发出 UPDATE 语句，尽管您可以通过修改属性以使其存在净值更改来影响此处的结果。

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

此事件通常为同一类的一批对象调用，然后在后续步骤中一次性发出它们的 UPDATE 语句。在极其罕见的情况下，如果不需要这样做，则可以使用 batch=False 配置 Mapper，这将导致将批量的实例分解为单独的（且性能较差的）事件->持久化->事件步骤。

警告

映射器级别的 flush 事件仅允许非常有限的操作，仅限于对正在操作的行本地的属性，并允许在给定的 Connection 上发出任何 SQL。 请完整阅读 映射器级别 Flush 事件中的注释，以获取有关使用这些方法的指南；通常，对于一般的 flush 时更改，应首选 SessionEvents.before_flush() 方法。

参数:

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

返回值:

此事件不支持返回值。

另请参阅