SQLAlchemy 1.4 Documentation

SessionEvents.before_commit()

method sqlalchemy.orm.SessionEvents.after_begin(session, transaction, connection)¶

在连接上开始事务后执行

示例参数形式：

from sqlalchemy import event


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

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

参数

session¶ -- 目标 Session .
transaction¶ -- 这个 SessionTransaction .
connection¶ -- 这个 Connection 将用于SQL语句的对象。

参见

SessionEvents.after_commit()

QueryEvents.before_compile_delete()

method sqlalchemy.orm.SessionEvents.after_bulk_delete(delete_context)¶

在调用了WHERE表达式的ORM DELETE之后执行。

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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(SomeSessionOrFactory, '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 版后已移除: 这个 after_bulk_delete 事件现在接受参数 delete_context . 对接受上面列出的“已弃用”参数签名的侦听器函数的支持将在将来的版本中删除。

这是由于 Query.delete() 方法。

参数: delete_context¶ -- “删除上下文”对象，其中包含有关更新的详细信息，包括以下属性： * session - the Session involved * query - Query 调用此更新操作的对象。* result 这个 CursorResult 作为批量删除操作的结果返回。

在 1.4 版更改: update_上下文不再具有 QueryContext 与之关联的对象。

参见

SessionEvents.after_bulk_update()

method sqlalchemy.orm.SessionEvents.after_bulk_update(update_context)¶

在针对WHERE表达式调用ORM更新后执行。

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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(SomeSessionOrFactory, '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 版后已移除: 这个 after_bulk_update 事件现在接受参数 update_context . 对接受上面列出的“已弃用”参数签名的侦听器函数的支持将在将来的版本中删除。

这是由于 Query.update() 方法。

参数: update_context¶ -- “更新上下文”对象，其中包含有关更新的详细信息，包括以下属性： * session - the Session involved * query - Query 调用此更新操作的对象。 * values The "values" dictionary that was passed to Query.update(). * result 这个 CursorResult 作为批量更新操作的结果返回。

在 1.4 版更改: update_上下文不再具有 QueryContext 与之关联的对象。

参见

QueryEvents.before_compile_update()

SessionEvents.after_bulk_delete()

method sqlalchemy.orm.SessionEvents.after_commit(session)¶

在提交之后执行。

示例参数形式：

from sqlalchemy import event


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

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

注解

这个 SessionEvents.after_commit() 钩子是 not 每次冲洗，即 Session 可以在事务范围内多次向数据库发出SQL。要拦截这些事件，请使用 SessionEvents.before_flush() ， SessionEvents.after_flush() 或 SessionEvents.after_flush_postexec() 事件。

注解

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

参数: session¶ -- 目标 Session .

参见

SessionEvents.before_commit()

SessionEvents.after_begin()

SessionEvents.before_flush()

method sqlalchemy.orm.SessionEvents.after_flush(session, flush_context)¶

在刷新完成后但在调用提交之前执行。

示例参数形式：

from sqlalchemy import event


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

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

请注意，会话的状态仍然处于预刷新状态，即“新”、“脏”和“已删除”列表仍然显示预刷新状态以及实例属性的历史设置。

警告

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

参数

session¶ -- 目标 Session .
flush_context¶ -- 内部的 UOWTransaction 处理刷新详细信息的对象。

参见

SessionEvents.after_flush_postexec()

SessionEvents.before_flush()

method sqlalchemy.orm.SessionEvents.after_flush_postexec(session, flush_context)¶

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

示例参数形式：

from sqlalchemy import event


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

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

这将在“新”、“脏”和“已删除”列表处于最终状态时进行。实际的commit（）可能已经发生，也可能没有发生，这取决于刷新是否启动了自己的事务或是否参与了更大的事务。

参数

session¶ -- 目标 Session .
flush_context¶ -- 内部的 UOWTransaction 处理刷新详细信息的对象。

参见

SessionEvents.after_flush()

method sqlalchemy.orm.SessionEvents.after_rollback(session)¶

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

示例参数形式：

from sqlalchemy import event


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

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

请注意，此事件仅在 实际的 对数据库执行回滚-执行回滚 not 每次开火 Session.rollback() 如果基础DBAPI事务已回滚，则调用方法。在许多情况下， Session 在此事件期间不会处于“活动”状态，因为当前事务无效。获得一个 Session 在进行最外层回滚之后，使用 SessionEvents.after_soft_rollback() 事件，检查 Session.is_active 旗帜。

参数: session¶ -- 目标 Session .

method sqlalchemy.orm.SessionEvents.after_soft_rollback(session, previous_transaction)¶

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

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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("select * from some_table")

参数

session¶ -- 目标 Session .
previous_transaction¶ -- 这个 SessionTransaction 刚刚关闭的事务标记对象。电流 SessionTransaction 对于给定的 Session 可通过 Session.transaction 属性。

method sqlalchemy.orm.SessionEvents.after_transaction_create(session, transaction)¶

当新的 SessionTransaction 创建。

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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.parent 属性是 None ：：@event.listens_for（session，“after_transaction_create”）def after_transaction_create（session，transaction）：if transaction.parent is none:使用顶级事务检测 SessionTransaction 是保存点，请使用 SessionTransaction.nested 属性：：@event.listens_for（session，“after_transaction_create”）def after_transaction_create（session，transaction）：if transaction.nested:使用保存点事务

参见

SessionTransaction

method sqlalchemy.orm.SessionEvents.after_transaction_end(session, transaction)¶

当 SessionTransaction 末端。

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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.parent 属性是 None ：：@event.listens_for（session，“after_transaction_create”）def after_transaction_end（session，transaction）：if transaction.parent is none:使用顶级事务检测 SessionTransaction 是保存点，请使用 SessionTransaction.nested 属性：：@event.listens_for（session，“after_transaction_create”）def after_transaction_end（session，transaction）：if transaction.nested:使用保存点事务

参见

SessionTransaction

SessionEvents.after_attach()

method sqlalchemy.orm.SessionEvents.before_attach(session, instance)¶

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

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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)¶

在调用提交之前执行。

示例参数形式：

from sqlalchemy import event


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

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

注解

这个 SessionEvents.before_commit() 钩子是 not 每次冲洗，即 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, flush_context, instances)¶

在刷新进程启动之前执行。

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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, instance)¶

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

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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() .

1.1 新版功能.

参见

method sqlalchemy.orm.SessionEvents.deleted_to_persistent(session, instance)¶

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

示例参数形式：

from sqlalchemy import event


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

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

只有当由于调用而还原刷新中成功删除的对象时，才会发生此转换。 Session.rollback() . 在任何其他情况下都不会调用该事件。

1.1 新版功能.

参见

method sqlalchemy.orm.SessionEvents.detached_to_persistent(session, instance)¶

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

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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() 对象是 not 但在调用此事件时标记为已删除。要检测已删除的对象，请检查 deleted 标志发送到 SessionEvents.persistent_to_detached() 在冲洗进行后发生事件，或检查 Session.deleted 在 SessionEvents.before_flush() 事件，如果在刷新之前需要截取已删除的对象。

参数

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

1.1 新版功能.

参见

method sqlalchemy.orm.SessionEvents.do_orm_execute(orm_execute_state)¶

根据 Session .

示例参数形式：

from sqlalchemy import event


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

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

对于从中调用的所有顶级SQL语句调用此事件 Session.execute() 方法。从SQLAlchemy 1.4开始，所有代表 Session 将流经此方法，因此此事件钩子提供一个点，在调用所有类型的ORM查询之前，可以在该点截获这些查询，并用不同的进程替换它们的执行。

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

这个钩子打算用 Query._execute_and_instances 方法，该方法可以在SQLAlchemy 1.4之前子类化。

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

参见

执行事件 - top level documentation on how to use SessionEvents.do_orm_execute()

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

ORM查询事件 - includes examples of using SessionEvents.do_orm_execute()

狗堆缓存 -一个如何将Dogpile缓存与ORM集成的示例 Session 利用 SessionEvents.do_orm_execute() 事件挂钩。

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

1.4 新版功能.

method sqlalchemy.orm.SessionEvents.loaded_as_persistent(session, instance)¶

截取特定对象的“作为永久加载”转换。

示例参数形式：

from sqlalchemy import event


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

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

此事件在ORM加载过程中被调用，并且被调用与 InstanceEvents.load() 事件。然而，这里的事件与 Session 类或实例，而不是映射器或类层次结构，并与其他会话生命周期事件顺利集成。当调用此事件时，该对象保证存在于会话的标识映射中。

注解

此事件在加载器进程中调用，在预先加载程序完成之前，并且对象的状态可能未完成。另外，对对象调用行级刷新操作会将对象放入新的加载程序上下文中，从而干扰现有的加载上下文。请参见 InstanceEvents.load() 关于利用 SessionEvents.restore_load_context 参数，其工作方式与 InstanceEvents.restore_load_context ，以解决此问题。

参数

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

1.1 新版功能.

参见

method sqlalchemy.orm.SessionEvents.pending_to_persistent(session, instance)¶

截获特定对象的“挂起到永久”转换。

示例参数形式：

from sqlalchemy import event


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

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

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

参数

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

1.1 新版功能.

参见

method sqlalchemy.orm.SessionEvents.pending_to_transient(session, instance)¶

拦截特定对象的“挂起到暂时”转换。

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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映射实例。

1.1 新版功能.

参见

method sqlalchemy.orm.SessionEvents.persistent_to_deleted(session, instance)¶

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

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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() 因此，在刷新结束时调用事件。

1.1 新版功能.

参见

method sqlalchemy.orm.SessionEvents.persistent_to_detached(session, instance)¶

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

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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，则表示此对象已移动到分离状态，因为它已标记为已删除和刷新。

1.1 新版功能.

参见

method sqlalchemy.orm.SessionEvents.persistent_to_transient(session, instance)¶

截取特定对象的“持续到暂时”转换。

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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映射实例。

1.1 新版功能.

参见

method sqlalchemy.orm.SessionEvents.transient_to_pending(session, instance)¶

截取特定对象的“暂时到挂起”转换。

示例参数形式：

from sqlalchemy import event


@event.listens_for(SomeSessionOrFactory, '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映射实例。

1.1 新版功能.

参见

MapperEvents.before_mapper_configured()

映射事件¶

映射器事件钩子包含与单个或多个相关的事件 Mapper 对象，它是将用户定义的类映射到 Table 对象。发生在 Mapper 级别包括：

Per-object persistence operations -最流行的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 物体。

Object Name	Description
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 类本身和 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 - continue event processing normally. * sqlalchemy.orm.interfaces.EXT_STOP -取消链中的所有后续事件处理程序。*其他值-特定侦听器指定的返回值。

类签名

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

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

将此事件与 MapperEvents.mapper_configured() 事件，在配置操作进行时按映射器调用；与此事件不同，当调用此事件时，所有交叉配置（例如backrefs）也将对挂起的任何映射器可用。也与 MapperEvents.before_configured() ，在配置映射器系列之前调用。

这个事件可以 only 应用于 Mapper 类或 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.mapper_configured()

MapperEvents.before_configured()

method sqlalchemy.orm.MapperEvents.after_delete(mapper, connection, target)¶

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

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

在上一步中，当同一类的一批对象的DELETE语句同时发出后，通常会调用该事件。

警告

映射器级别刷新事件仅允许 非常有限的操作 ，并允许在给定的 Connection . 请详细阅读 笔记在映射器级别事件关于使用这些方法的指南；一般来说， SessionEvents.before_flush() 对于一般的刷新更改，应首选方法。

参数

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

返回

此事件不支持返回值。

参见

method sqlalchemy.orm.MapperEvents.after_insert(mapper, connection, target)¶

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

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

在上一步中，一次发出insert语句后，通常会为同一类的一批对象调用该事件。在极为罕见的情况下，这是不可取的， mapper() 可配置为 batch=False ，这将导致成批的实例被分解为单独的（性能更差的）事件->持久化->事件步骤。

警告

参数

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

返回

此事件不支持返回值。

参见

method sqlalchemy.orm.MapperEvents.after_update(mapper, connection, target)¶

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

示例参数形式：

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

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

对标记为“脏”的所有实例调用此方法， even those which have no net changes to their column-based attributes ，并且没有执行任何更新语句。当对象的任何基于列的属性调用了“set attribute”操作或修改了其任何集合时，该对象被标记为脏对象。如果在更新时，没有基于列的属性有任何净更改，则不会发出更新语句。这意味着一个实例被发送到 MapperEvents.after_update() 是 not 已发布更新声明的保证。

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

在上一步中，一批同一类的对象的update语句一次发出之后，通常会调用该事件。在极为罕见的情况下，这是不可取的， mapper() 可配置为 batch=False ，这将导致成批的实例被分解为单独的（性能更差的）事件->持久化->事件步骤。

警告

参数

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

返回

此事件不支持返回值。

参见

MapperEvents.before_mapper_configured()

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

这个事件可以 only 应用于 Mapper 类或 mapper() 函数，而不是单个映射或映射类。它仅对作为整体的所有映射调用：：

from sqlalchemy.orm import mapper

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

将此事件与 MapperEvents.after_configured() ，在配置了一系列映射器之后调用，以及 MapperEvents.before_mapper_configured() 和 MapperEvents.mapper_configured() ，两者都是在每个映射器的基础上调用的。

from sqlalchemy.orm import mapper

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

0.9.3 新版功能.

参见

MapperEvents.mapper_configured()

MapperEvents.after_configured()

method sqlalchemy.orm.MapperEvents.before_delete(mapper, connection, target)¶

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

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

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

警告

参数

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

返回

此事件不支持返回值。

参见

method sqlalchemy.orm.MapperEvents.before_insert(mapper, connection, target)¶

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

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

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

警告

参数

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

返回

此事件不支持返回值。

参见

MapperEvents.before_configured()

method sqlalchemy.orm.MapperEvents.before_mapper_configured(mapper, class_)¶

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

示例参数形式：

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() ，则：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, connection, target)¶

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

示例参数形式：

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

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

对标记为“脏”的所有实例调用此方法， even those which have no net changes to their column-based attributes . 当对象的任何基于列的属性调用了“set attribute”操作或修改了其任何集合时，该对象被标记为脏对象。如果在更新时，没有基于列的属性有任何净更改，则不会发出更新语句。这意味着一个实例被发送到 MapperEvents.before_update() 是 not 保证将发出更新语句，尽管您可以通过修改属性来影响此处的结果，从而使值确实存在净变化。

若要检测对象上基于列的属性是否有净更改，从而生成更新语句，请使用 object_session(instance).is_modified(instance, include_collections=False) .

在稍后的步骤中，在一次发出更新语句之前，通常会为同一类的一批对象调用事件。在极为罕见的情况下，这是不可取的， mapper() 可配置为 batch=False ，这将导致成批的实例被分解为单独的（性能更差的）事件->持久化->事件步骤。

警告

参数

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

返回

此事件不支持返回值。

参见