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: The SessionEvents.after_bulk_delete() 事件现在接受参数 SessionEvents.after_bulk_delete.delete_context. 对接受上述作为“已弃用”的先前参数签名的监听器函数的支持将在未来版本中删除。

遗留功能

从 SQLAlchemy 2.0 开始，SessionEvents.after_bulk_delete() 方法是一个遗留的事件钩子。该事件不参与使用在 ORM UPDATE 和 DELETE 具有自定义 WHERE 条件中记录的 delete() 的 2.0 风格调用。对于 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: The SessionEvents.after_bulk_update() 事件现在接受参数 SessionEvents.after_bulk_update.update_context. 对接受上述作为“已弃用”的先前参数签名的监听器函数的支持将在未来版本中删除。

遗留功能

从 SQLAlchemy 2.0 开始，SessionEvents.after_bulk_update() 方法是一个遗留的事件钩子。该事件不参与使用在 ORM UPDATE 和 DELETE 具有自定义 WHERE 条件中记录的 update() 的 2.0 风格调用。对于 2.0 风格的使用，SessionEvents.do_orm_execute() 钩子将拦截这些调用。

参数：:

update_context¶ –

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

session - 所涉及的 Session。

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

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

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

注意

The SessionEvents.after_commit() hook is not per-flush, that is, the Session can emit SQL to the database many times within the scope of a transaction. For interception of these events, use the SessionEvents.before_flush(), SessionEvents.after_flush(), or SessionEvents.after_flush_postexec() events.

注意

The Session is not in an active transaction when the SessionEvents.after_commit() event is invoked, and therefore can not emit SQL. To emit SQL corresponding to every transaction, use the SessionEvents.before_commit() event.

参数：:: session¶ – The target 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) ...

请注意，会话的状态仍然处于 flush 之前，即“new”、“dirty”和“deleted”列表仍然显示 flush 之前的状态以及实例属性上的历史记录设置。

警告

此事件在 Session 已向数据库发出 SQL 以修改数据库之后运行，但在它更改其内部状态以反映这些更改之前运行，包括新插入的对象被放置到身份映射中。从版本 1.3.9 开始，SQLAlchemy 会对这种情况发出警告。

参数：:

session¶ – The target Session.
flush_context¶ – Internal UOWTransaction object which handles the details of the flush.

另请参见

SessionEvents.after_flush_postexec()

SessionEvents.before_flush()

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

在 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¶ – The target Session.
flush_context¶ – Internal UOWTransaction object which handles the details of the flush.

另请参见

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

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

参数：:: session¶ – The target 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 可以在最外层回滚后首先检查 Session.is_active 标志后用于调用 SQL 和 Session.query() 操作。

@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¶ – The target Session.
previous_transaction¶ – The SessionTransaction transactional marker object which was just closed. The current SessionTransaction for the given Session is available via the Session.transaction attribute.

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 是最外层的 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 是最外层的 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¶

在调用提交之前执行。

示例参数形式

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 关联（请注意，标记为“已删除”的对象将保持“持久化”状态，直到刷新进行）。

注意

如果该对象在调用 Session.delete() 时变为持久化，则在调用此事件时，该对象不会被标记为已删除。若要检测已删除的对象，请在刷新进行后检查发送到 SessionEvents.persistent_to_detached() 的 deleted 标志，或者在 SessionEvents.before_flush() 事件中检查 Session.deleted 集合，如果需要在刷新之前拦截已删除的对象。

参数：:

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 刷新过程中内部发出的查询，即刷新中描述的过程；要拦截刷新过程中的步骤，请参阅持久化事件以及映射器级别的刷新事件中描述的事件钩子。

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

注意

此事件在加载器过程内部被调用，在急切加载器完成之前，并且对象的 state 可能不完整。此外，在对象上调用行级刷新操作将把对象置于新的加载器上下文中，干扰现有的加载上下文。有关使用 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¶

拦截特定对象的“待处理到持久化”转换。

示例参数形式

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

此事件在刷新过程中被调用，类似于在 SessionEvents.after_flush() 事件中扫描 Session.new 集合。但是，在这种情况下，当事件被调用时，对象已经被移动到持久化状态。

参数：:

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

另请参见

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

拦截特定对象的“待处理到瞬态”转换。

示例参数形式

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.rollback() 方法回滚事务时，或者当 Session.expunge() 方法被使用时，就会发生这种情况。

参数：:

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

另请参见

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

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

示例参数形式

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

当持久对象的标识在冲洗操作中从数据库中删除时，会触发此事件，但该对象仍然与 Session 关联，直到事务完成。

如果事务回滚，该对象将再次移至持久状态，并调用 SessionEvents.deleted_to_persistent() 事件。如果事务提交，该对象将变为分离状态，这将发出 SessionEvents.deleted_to_detached() 事件。

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

另请参见

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

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

示例参数形式

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，则表示该对象移至分离状态，因为它被标记为已删除并已冲洗。

另请参见

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

拦截特定对象的“持久到瞬态”转换。

示例参数形式

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.rollback() 方法回滚事务时，就会发生这种情况。

参数：:

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

另请参见

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

拦截特定对象的“瞬态到挂起”转换。

示例参数形式

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()）形成对比，因为它们在冲洗过程中按对象进行，虽然在对象上进行更细粒度的活动更直接，但 Session 功能的可用性有限。
映射器配置事件 - 另一类主要的映射器钩子是在映射类、完成映射器以及配置映射器集合以相互引用时发生的钩子。这些事件包括 MapperEvents.instrument_class()、MapperEvents.before_mapper_configured() 和 MapperEvents.mapper_configured() 在单个 Mapper 级别，以及 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() 方法，作为更灵活和用户友好的钩子，用于在刷新期间应用额外的数据库状态。

使用 MapperEvents 时，listen() 函数提供了一些修饰符。

参数：:

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

成员

类签名

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

method 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() 事件进行对比，后者是在配置操作进行时针对每个映射器调用的；与该事件不同，当调用此事件时，所有交叉配置（例如 backrefs）也将对任何待处理的映射器可用。还与 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()

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

注意

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

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

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

警告

映射器级刷新事件只允许执行 **非常有限的操作**，这些操作仅限于正在操作的行上的本地属性，并且允许在给定的 Connection 上发出任何 SQL。 **请仔细阅读** 映射器级刷新事件中的说明，了解有关使用这些方法的指南；通常，SessionEvents.before_flush() 方法应优先用于一般刷新更改。

参数：:

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

返回值:

此事件不支持返回值。

另请参见

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

注意

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

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

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

警告

映射器级刷新事件只允许执行 **非常有限的操作**，这些操作仅限于正在操作的行上的本地属性，并且允许在给定的 Connection 上发出任何 SQL。 **请仔细阅读** 映射器级刷新事件中的说明，了解有关使用这些方法的指南；通常，SessionEvents.before_flush() 方法应优先用于一般刷新更改。

参数：:

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

返回值:

此事件不支持返回值。

另请参见

method 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() 事件来创建新的映射器，以记录对象的变化审核历史。

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

注意

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

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

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

若要检测对象的基于列的属性是否具有净变化，以及因此是否导致了 UPDATE 语句，请使用 object_session(instance).is_modified(instance, include_collections=False)。

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

警告

映射器级刷新事件只允许执行 **非常有限的操作**，这些操作仅限于正在操作的行上的本地属性，并且允许在给定的 Connection 上发出任何 SQL。 **请仔细阅读** 映射器级刷新事件中的说明，了解有关使用这些方法的指南；通常，SessionEvents.before_flush() 方法应优先用于一般刷新更改。

参数：:

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

返回值:

此事件不支持返回值。

另请参见

MapperEvents.before_mapper_configured()

method 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()

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

注意

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

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

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

警告

映射器级刷新事件只允许执行 **非常有限的操作**，这些操作仅限于正在操作的行上的本地属性，并且允许在给定的 Connection 上发出任何 SQL。 **请仔细阅读** 映射器级刷新事件中的说明，了解有关使用这些方法的指南；通常，SessionEvents.before_flush() 方法应优先用于一般刷新更改。

参数：:

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

返回值:

此事件不支持返回值。

另请参见

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

注意

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

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

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

警告

映射器级刷新事件只允许执行 **非常有限的操作**，这些操作仅限于正在操作的行上的本地属性，并且允许在给定的 Connection 上发出任何 SQL。 **请仔细阅读** 映射器级刷新事件中的说明，了解有关使用这些方法的指南；通常，SessionEvents.before_flush() 方法应优先用于一般刷新更改。

参数：:

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

返回值:

此事件不支持返回值。

另请参见

MapperEvents.before_configured()

method 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）应在当前配置运行中跳过。当一个或多个映射器被跳过时，he “new mappers” 标志将保持设置状态，这意味着当使用映射器时，configure_mappers() 函数将继续被调用，以继续尝试配置所有可用的映射器。

与其他配置级事件相比，MapperEvents.before_configured()，MapperEvents.after_configured() 和 MapperEvents.mapper_configured()，:meth;`.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()

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

注意

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

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

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

要检测对象上的基于列的属性是否有净变化，并且因此会生成 UPDATE 语句，请使用 object_session(instance).is_modified(instance, include_collections=False)。

该事件通常会针对一批相同类的对象调用，然后在稍后的步骤中一次性发出它们的 UPDATE 语句。在极少数情况下，如果这不是可取的，则可以将 Mapper 配置为 batch=False，这会导致实例批次被分解成单个（并且性能更差）的事件->持久化->事件步骤。

警告

映射器级刷新事件只允许执行 **非常有限的操作**，这些操作仅限于正在操作的行上的本地属性，并且允许在给定的 Connection 上发出任何 SQL。 **请仔细阅读** 映射器级刷新事件中的说明，了解有关使用这些方法的指南；通常，SessionEvents.before_flush() 方法应优先用于一般刷新更改。

参数：:

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

返回值:

此事件不支持返回值。

另请参见