核心事件

本节介绍 SQLAlchemy Core 中提供的事件接口。有关事件侦听 API 的介绍，请参阅事件。ORM 事件在 ORM 事件 中进行了描述。

对象名称	描述
事件	为特定目标类型定义事件侦听函数。

类 sqlalchemy.event.base 中。事件

为特定目标类型定义事件侦听函数。

成员

遣

类签名

类 sqlalchemy.event.Events （） （） sqlalchemy.event._HasEventsDispatch

属性 sqlalchemy.event.base.Events。dispatch： _Dispatch[_ET] = <sqlalchemy.event.base.EventsDispatch 对象>

引用回 _Dispatch 类。

针对 _Dispatch._events 的双向

连接池事件

对象名称	描述
矿池事件	池的可用事件。
PoolResetState	描述 DBAPI 连接在传递给 PoolEvents.reset（） 连接池事件时的状态。

类 sqlalchemy.events 中。PoolEvents（矿池事件

池的可用事件。

此处的方法定义事件的名称以及传递给侦听器函数的成员的名称。

例如：

from sqlalchemy import event


def my_on_checkout(dbapi_conn, connection_rec, connection_proxy):
    "handle an on checkout event"


event.listen(Pool, "checkout", my_on_checkout)

除了接受 Pool 类和 Pool 实例，则 PoolEvents 还接受 Engine 对象和 Engine 类作为目标，它们将被解析为给定引擎的 .pool 属性或 Pool 类：

engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")

# will associate with engine.pool
event.listen(engine, "checkout", my_on_checkout)

成员

checkin（）、checkout（）、close（）、close_detached（）、connect（）、detach（）、dispatch、first_connect（）、invalidate（）、reset（）、soft_invalidate（）

类签名

类 sqlalchemy.events.PoolEvents （sqlalchemy.event.Events）

方法 sqlalchemy.events.PoolEvents 的 PoolEvents 方法。checkin（dbapi_connection：DBAPIConnectionNone， connection_record： ConnectionPoolEntry）→ 无

当连接返回到池时调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'checkin')
def receive_checkin(dbapi_connection, connection_record):
    "listen for the 'checkin' event"

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

请注意，连接可能已关闭，如果连接已失效，则可能为 None。不会为 detached 连接调用 checkin。（他们不会返回游泳池。

参数

• 
  dbapi_connection – 一个 DBAPI 连接。属性 ConnectionPoolEntry.dbapi_connection 。

• 
  connection_record– 管理 DBAPI 连接的 ConnectionPoolEntry。

方法 sqlalchemy.events.PoolEvents 的 PoolEvents 方法。checkout（dbapi_connection：DBAPIConnection，connection_record：ConnectionPoolEntry，connection_proxy：PoolProxiedConnection）→ 无

从池中检索连接时调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'checkout')
def receive_checkout(dbapi_connection, connection_record, connection_proxy):
    "listen for the 'checkout' event"

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

参数

• 
  dbapi_connection – 一个 DBAPI 连接。属性 ConnectionPoolEntry.dbapi_connection 。

• 
  connection_record– 管理 DBAPI 连接的 ConnectionPoolEntry。

• 
  connection_proxy– PoolProxiedConnection 对象，它将在签出的生命周期内代理 DBAPI 连接的公共接口。

如果引发 DisconnectionError，则将释放当前连接并检索新连接。所有签出侦听器的处理将中止并使用新连接重新启动。

另请参阅

ConnectionEvents.engine_connect() - 类似事件 在创建新 Connection 时发生。

方法 sqlalchemy.events.PoolEvents 的 PoolEvents 方法。close（dbapi_connection： DBAPIConnection， connection_record： ConnectionPoolEntry）→ 无

在 DBAPI 连接关闭时调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'close')
def receive_close(dbapi_connection, connection_record):
    "listen for the 'close' event"

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

该事件在关闭发生之前发出。

连接关闭可能会失败;通常，这是因为连接已关闭。如果 close作失败，则丢弃连接。

close（） 事件对应于仍与池关联的连接。要拦截分离连接的关闭事件，请使用 close_detached（）。

参数

• 
  dbapi_connection – 一个 DBAPI 连接。属性 ConnectionPoolEntry.dbapi_connection 。

• 
  connection_record– 管理 DBAPI 连接的 ConnectionPoolEntry。

方法 sqlalchemy.events.PoolEvents 的 PoolEvents 方法。close_detached（dbapi_connection： DBAPIConnection）→ 无

在关闭分离的 DBAPI 连接时调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'close_detached')
def receive_close_detached(dbapi_connection):
    "listen for the 'close_detached' event"

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

该事件在关闭发生之前发出。

连接关闭可能会失败;通常，这是因为连接已关闭。如果 close作失败，则丢弃连接。

参数

dbapi_connection – 一个 DBAPI 连接。属性 ConnectionPoolEntry.dbapi_connection 。

方法 sqlalchemy.events.PoolEvents 的 PoolEvents 方法。connect（dbapi_connection： DBAPIConnection， connection_record： ConnectionPoolEntry）→ 无

在首次为给定池创建特定 DBAPI 连接时调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'connect')
def receive_connect(dbapi_connection, connection_record):
    "listen for the 'connect' event"

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

此事件允许直接捕获点，之后使用 DBAPI 模块级 .connect（） 方法生成新的 DBAPI 连接。

参数

• 
  dbapi_connection – 一个 DBAPI 连接。属性 ConnectionPoolEntry.dbapi_connection 。

• 
  connection_record– 管理 DBAPI 连接的 ConnectionPoolEntry。

方法 sqlalchemy.events.PoolEvents 的 PoolEvents 方法。detach（dbapi_connection： DBAPIConnection， connection_record： ConnectionPoolEntry）→ 无

当 DBAPI 连接与池“分离”时调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'detach')
def receive_detach(dbapi_connection, connection_record):
    "listen for the 'detach' event"

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

此事件在 detach 发生后发出。该连接不再与给定的连接记录关联。

参数

• 
  dbapi_connection – 一个 DBAPI 连接。属性 ConnectionPoolEntry.dbapi_connection 。

• 
  connection_record– 管理 DBAPI 连接的 ConnectionPoolEntry。

属性 sqlalchemy.events.PoolEvents 的 PoolEvents 中。dispatch： _Dispatch[_ET] = <sqlalchemy.event.base.PoolEventsDispatch 对象>

引用回 _Dispatch 类。

针对 _Dispatch._events 的双向

方法 sqlalchemy.events.PoolEvents 的 PoolEvents 方法。first_connect（dbapi_connection： DBAPIConnection， connection_record： ConnectionPoolEntry）→ 无

首次从特定池中签出 DBAPI 连接时，恰好调用一次。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'first_connect')
def receive_first_connect(dbapi_connection, connection_record):
    "listen for the 'first_connect' event"

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

PoolEvents.first_connect（） 的基本原理 是确定 有关基于特定数据库连接系列的信息 在 Settings used for all connections（用于所有连接的设置）上。 由于特定的 池 指的是单个 “creator” 函数（在 引擎 是指使用的 URL 和连接选项）， 通常，对单个连接进行观察是有效的 可以安全地假设它对所有后续 连接，例如数据库版本、服务器和客户端 编码设置、排序规则设置等。

参数

• 
  dbapi_connection – 一个 DBAPI 连接。属性 ConnectionPoolEntry.dbapi_connection 。

• 
  connection_record– 管理 DBAPI 连接的 ConnectionPoolEntry。

方法 sqlalchemy.events.PoolEvents 的 PoolEvents 方法。invalidate（dbapi_connection： DBAPIConnection， connection_record： ConnectionPoolEntry， exception：BaseExceptionNone）→ 无

当 DBAPI 连接要“失效”时调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'invalidate')
def receive_invalidate(dbapi_connection, connection_record, exception):
    "listen for the 'invalidate' event"

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

每当 ConnectionPoolEntry.invalidate() method 的调用，无论是从 API 使用还是通过“自动失效”调用，而不使用软标志。

该事件发生在最后一次尝试对连接调用 .close（） 之前。

参数

• 
  dbapi_connection – 一个 DBAPI 连接。属性 ConnectionPoolEntry.dbapi_connection 。

• 
  connection_record– 管理 DBAPI 连接的 ConnectionPoolEntry。

• 
  exception —— 与此失效原因相对应的 exception 对象（如果有）。可以是 None。

另请参阅

有关失效的更多信息

方法 sqlalchemy.events.PoolEvents 的 PoolEvents 方法。reset（dbapi_connection：DBAPIConnection，connection_record：ConnectionPoolEntry，reset_state：PoolResetState）→ 无

在对池连接执行 “reset”作之前调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'reset')
def receive_reset(dbapi_connection, connection_record, reset_state):
    "listen for the 'reset' event"

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

# DEPRECATED calling style (pre-2.0, will be removed in a future release)
@event.listens_for(SomeEngineOrPool, 'reset')
def receive_reset(dbapi_connection, connection_record):
    "listen for the 'reset' event"

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

在 2.0 版更改： PoolEvents.reset（） 事件现在接受参数 PoolEvents.reset.dbapi_connection 、 、 PoolEvents.reset.connection_record PoolEvents.reset.reset_state。在未来的发行版中，将删除对接受上面列出的先前参数签名为“已弃用”的侦听器函数的支持。

此事件表示在将 rollback（） 方法返回到池或丢弃之前对 DBAPI 连接调用 rollback（） 方法的时间。可以使用此事件钩子实现自定义 “reset” 策略，也可以与使用 Pool.reset_on_return 参数禁用默认的 “reset” 行为相结合。

PoolEvents.reset（） 和 PoolEvents.checkin（） 事件是 调用 PoolEvents.reset（） 不仅仅是为了池化 连接，以及 使用 Connection.detach（） 方法以及由于在签入连接之前对连接进行垃圾回收而被丢弃的 asyncio 连接。

请注意，对于使用 Connection.invalidate（） 失效的连接，不会调用该事件。这些事件可以使用 PoolEvents.soft_invalidate（） 和 PoolEvents.invalidate（） 事件钩子，并且所有 “connection close” 事件都可以使用 PoolEvents.close（） 进行拦截。

PoolEvents.reset（） 事件通常后跟 PoolEvents.checkin（） 事件，但在重置后立即丢弃连接的情况除外。

参数

• 
  dbapi_connection – 一个 DBAPI 连接。属性 ConnectionPoolEntry.dbapi_connection 。

• 
  connection_record– 管理 DBAPI 连接的 ConnectionPoolEntry。

• reset_state –

  
  PoolResetState 实例，该实例提供有关重置连接的情况的信息。

  
  2.0 版的新Function。

另请参阅

返回时重置

ConnectionEvents.rollback（）

ConnectionEvents.commit（）

方法 sqlalchemy.events.PoolEvents 的 PoolEvents 方法。soft_invalidate（dbapi_connection： DBAPIConnection， connection_record： ConnectionPoolEntry， exception：BaseExceptionNone）→ 无

当 DBAPI 连接要“软失效”时调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'soft_invalidate')
def receive_soft_invalidate(dbapi_connection, connection_record, exception):
    "listen for the 'soft_invalidate' event"

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

每当 ConnectionPoolEntry.invalidate() method 的 SOFT 标志调用。

软失效是指跟踪此连接的连接记录在签入当前连接后强制重新连接。它不会在调用它时主动关闭 dbapi_connection。

参数

• 
  dbapi_connection – 一个 DBAPI 连接。属性 ConnectionPoolEntry.dbapi_connection 。

• 
  connection_record– 管理 DBAPI 连接的 ConnectionPoolEntry。

• 
  exception —— 与此失效原因相对应的 exception 对象（如果有）。可以是 None。

类 sqlalchemy.events 中。PoolResetState（池重置状态

描述 DBAPI 连接在传递给 PoolEvents.reset（） 连接池事件时的状态。

成员

asyncio_safe、terminate_only transaction_was_reset

2.0.0b3 版本的新Function。

属性 sqlalchemy.events.PoolResetState. asyncio_safe：bool

指示 reset作是否发生在 asyncio 应用程序预期存在封闭事件循环的范围内。

如果连接被垃圾回收，则为 False。

属性 sqlalchemy.events.PoolResetState. terminate_only： bool

指示是否立即终止连接，而不检入池。

这种情况发生在已失效的连接，以及未被调用代码干净处理、而是被垃圾回收的 asyncio 连接。在后一种情况下，无法在垃圾回收中的 asyncio 连接上安全地运行作，因为不一定存在事件循环。

属性 sqlalchemy.events.PoolResetState. transaction_was_reset： bool

指示 DBAPI 连接上的事务是否基本上已被 Connection 对象“重置”回来。

如果 Connection 具有事务性 状态，该状态未使用 Connection.rollback（） 或 Connection.commit（） 方法; 相反，事务在 Connection.close（） 方法，因此保证在达到此事件时保持不存在。

SQL 执行和连接事件

对象名称	描述
连接事件	可用于的事件 Connection 和 Engine。
Dialect事件	事件接口。

类 sqlalchemy.events 中。ConnectionEvents（连接事件

可用于的事件 Connection 和 Engine。

此处的方法定义事件的名称以及传递给侦听器函数的成员的名称。

事件侦听器可以与任何 连接或引擎 类或实例，例如 Engine，例如：

from sqlalchemy import event, create_engine


def before_cursor_execute(
    conn, cursor, statement, parameters, context, executemany
):
    log.info("Received statement: %s", statement)


engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
event.listen(engine, "before_cursor_execute", before_cursor_execute)

或具有特定 Connection 的 Connection：

with engine.begin() as conn:

    @event.listens_for(conn, "before_cursor_execute")
    def before_cursor_execute(
        conn, cursor, statement, parameters, context, executemany
    ):
        log.info("Received statement: %s", statement)

当使用语句参数调用方法时，例如 after_cursor_execute（） 或 before_cursor_execute（） 中，该语句是准备传输到连接的 Dialect 中的 DBAPI 游标的确切 SQL 字符串。

before_execute（） 和 before_cursor_execute（） 还可以使用 retval=True 标志建立事件，该标志允许修改语句和参数以发送到数据库。before_cursor_execute（） 事件在这里特别有用，可用于将临时字符串转换（例如注释）添加到所有执行中：

from sqlalchemy.engine import Engine
from sqlalchemy import event


@event.listens_for(Engine, "before_cursor_execute", retval=True)
def comment_sql_calls(
    conn, cursor, statement, parameters, context, executemany
):
    statement = statement + " -- some comment"
    return statement, parameters

注意

ConnectionEvents 可以在 Engine、Connection、 也 作为每个类的实例。 所有事件 将针对给定的 实例触发四个范围 连接。 但是，出于性能原因， Connection 对象在实例化时确定其父 Engine 是否建立了事件侦听器。添加到 Engine 的事件侦听器 class 或 Engine 实例实例化后，通常会 在该 Connection 实例上不可用。 新的 添加的侦听器将改为 连接 在这些事件侦听器之后创建的实例 建立在父 Engine 类或实例上。

参数

retval=False– 适用于 before_execute（） 和 仅限 before_cursor_execute（） 事件。当 True 时，用户定义的事件函数必须具有返回值，该值是替换给定语句和参数的参数元组。有关特定 return 参数的描述，请参阅这些方法。

成员

after_cursor_execute（）， after_execute（）， before_cursor_execute（）， before_execute（）， begin（）， begin_twophase（）， commit（）， commit_twophase（）， dispatch， engine_connect（）， engine_disposed（）， prepare_twophase（）， release_savepoint（）、回滚（）、rollback_savepoint（）、rollback_twophase（）、保存点（）、set_connection_execution_options（）、set_engine_execution_options（）

类签名

类 sqlalchemy.events.ConnectionEvents （sqlalchemy.event.Events）

方法 sqlalchemy.events.ConnectionEvents. after_cursor_execute（conn：连接，游标：DBAPICursor，语句：str，参数： _DBAPIAnyExecuteParams， context：ExecutionContextNone， executemany： bool）→ None

执行后拦截低级游标 execute（） 事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'after_cursor_execute')
def receive_after_cursor_execute(conn, cursor, statement, parameters, context, executemany):
    "listen for the 'after_cursor_execute' event"

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

参数

• 
  conn – 连接对象

• 
  cursor– DBAPI 游标对象。如果语句是 SELECT，则结果将挂起，但不应使用这些结果，因为 CursorResult 需要它们。

• 
  statement– 字符串 SQL 语句，传递给 DBAPI

• 
  parameters– 传递给 DBAPI 游标的 execute（） 或 executemany（） 方法的字典、元组或参数列表。在某些情况下，可能是 None。

• 
  context– 正在使用的 ExecutionContext 对象。可以是 None。

• 
  executemany – 布尔值，如果为 True，则为 executemany（） call，如果为 False，则为 execute（） 调用。

方法 sqlalchemy.events.ConnectionEvents. after_execute（conn： 连接， clauseelement： 可执行， multiparams： _CoreMultiExecuteParams， params： _CoreSingleExecuteParams， execution_options： _ExecuteOptions， result： Result[Any]）→ 无

执行后拦截高级 execute（） 事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'after_execute')
def receive_after_execute(conn, clauseelement, multiparams, params, execution_options, result):
    "listen for the 'after_execute' event"

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

# DEPRECATED calling style (pre-1.4, will be removed in a future release)
@event.listens_for(SomeEngine, 'after_execute')
def receive_after_execute(conn, clauseelement, multiparams, params, result):
    "listen for the 'after_execute' event"

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

在 1.4 版本发生变更： 该 ConnectionEvents.after_execute() 事件现在接受参数 ConnectionEvents.after_execute.conn 、 、 ConnectionEvents.after_execute.clauseelement 、 ConnectionEvents.after_execute.multiparams ConnectionEvents.after_execute.params 、 ConnectionEvents.after_execute.execution_options 、 ConnectionEvents.after_execute.result 。在未来的发行版中，将删除对接受上面列出的先前参数签名为“已弃用”的侦听器函数的支持。

参数

• 
  conn – 连接对象

• 
  clauseelement– SQL 表达式结构，已编译 实例或传递给 Connection.execute（） 的 Connection.execute（） 中。

• 
  multiparams– 多个参数集，字典列表。

• 
  params– 单个参数集，单个字典。

• execution_options –

  
  与语句一起传递的执行选项字典（如果有）。这是将使用的所有选项的合并，包括 statement、connection 的选项以及传递给 2.0 执行样式的方法本身的选项。

• 
  result- 执行生成的 CursorResult。

方法 sqlalchemy.events.ConnectionEvents. before_cursor_execute（conn：连接，游标：DBAPICursor，语句：str，参数： _DBAPIAnyExecuteParams， context：ExecutionContextNone， executemany： bool）→Tuple[str，_DBAPIAnyExecuteParams]None

在执行之前拦截低级游标 execute（） 事件，接收要针对游标调用的字符串 SQL 语句和特定于 DBAPI 的参数列表。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'before_cursor_execute')
def receive_before_cursor_execute(conn, cursor, statement, parameters, context, executemany):
    "listen for the 'before_cursor_execute' event"

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

此事件是记录和延迟修改 SQL 字符串的不错选择。除了特定于目标后端的参数修改外，它不太适合参数修改。

可以选择使用 retval=True 建立此事件 旗。 在这种情况下，statement 和 parameters 参数应以双元组的形式返回：

@event.listens_for(Engine, "before_cursor_execute", retval=True)
def before_cursor_execute(
    conn, cursor, statement, parameters, context, executemany
):
    # do something with statement, parameters
    return statement, parameters

请参阅 ConnectionEvents 中的示例。

参数

• 
  conn – 连接对象

• 
  cursor– DBAPI 游标对象

• 
  statement – 字符串 SQL 语句，要传递给 DBAPI

• 
  parameters– 传递给 DBAPI 游标的 execute（） 或 executemany（） 方法的字典、元组或参数列表。在某些情况下，可能是 None。

• 
  context– 正在使用的 ExecutionContext 对象。可以是 None。

• 
  executemany – 布尔值，如果为 True，则为 executemany（） call，如果为 False，则为 execute（） 调用。

另请参阅

before_execute（）

after_cursor_execute（）

method sqlalchemy.events.ConnectionEvents. before_execute（conn： 连接， clauseelement： 可执行文件， multiparams： _CoreMultiExecuteParams， params： _CoreSingleExecuteParams， execution_options： _ExecuteOptions）→Tuple[Executable，_CoreMultiExecuteParams，_CoreSingleExecuteParams]无

拦截高级 execute（） 事件，在渲染到 SQL 之前接收未编译的 SQL 结构和其他对象。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'before_execute')
def receive_before_execute(conn, clauseelement, multiparams, params, execution_options):
    "listen for the 'before_execute' event"

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

# DEPRECATED calling style (pre-1.4, will be removed in a future release)
@event.listens_for(SomeEngine, 'before_execute')
def receive_before_execute(conn, clauseelement, multiparams, params):
    "listen for the 'before_execute' event"

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

在 1.4 版本发生变更： 该 ConnectionEvents.before_execute() 事件现在接受参数 ConnectionEvents.before_execute.conn 、 、 ConnectionEvents.before_execute.clauseelement ConnectionEvents.before_execute.multiparams 、 ConnectionEvents.before_execute.params 、 ConnectionEvents.before_execute.execution_options 。在未来的发行版中，将删除对接受上面列出的先前参数签名为“已弃用”的侦听器函数的支持。

此事件适用于调试 SQL 编译问题以及早期作发送到数据库的参数，因为此处的参数列表将采用一致的格式。

可以选择使用 retval=True 建立此事件 旗。 clauseelement、multiparams 和 params 在这种情况下，参数应以三元组的形式返回：

@event.listens_for(Engine, "before_execute", retval=True)
def before_execute(conn, clauseelement, multiparams, params):
    # do something with clauseelement, multiparams, params
    return clauseelement, multiparams, params

参数

• 
  conn – 连接对象

• 
  clauseelement– SQL 表达式结构，已编译 实例或传递给 Connection.execute（） 的 Connection.execute（） 中。

• 
  multiparams– 多个参数集，字典列表。

• 
  params– 单个参数集，单个字典。

• execution_options –

  
  与语句一起传递的执行选项字典（如果有）。这是将使用的所有选项的合并，包括 statement、connection 的选项以及传递给 2.0 执行样式的方法本身的选项。

另请参阅

before_cursor_execute（）

method sqlalchemy.events.ConnectionEvents. begin（conn： Connection）→ 无

拦截 begin（） 事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'begin')
def receive_begin(conn):
    "listen for the 'begin' event"

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

参数

conn – 连接对象

方法 sqlalchemy.events.ConnectionEvents. begin_twophase（conn： Connection， xid： Any）→ 无

拦截 begin_twophase（） 事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'begin_twophase')
def receive_begin_twophase(conn, xid):
    "listen for the 'begin_twophase' event"

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

参数

• 
  conn – 连接对象

• 
  xid– 两相 XID 标识符

method sqlalchemy.events.ConnectionEvents. commit（conn： Connection）→ 无

拦截 commit（） 事件，由 交易。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'commit')
def receive_commit(conn):
    "listen for the 'commit' event"

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

请注意，如果 reset_on_return flag 设置为值 'commit'。要拦截此提交，请使用 PoolEvents.reset（） 钩子。

参数

conn – 连接对象

方法 sqlalchemy.events.ConnectionEvents. commit_twophase（conn： Connection， xid： Any， is_prepared： bool）→ 无

拦截 commit_twophase（） 事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'commit_twophase')
def receive_commit_twophase(conn, xid, is_prepared):
    "listen for the 'commit_twophase' event"

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

参数

• 
  conn – 连接对象

• 
  xid– 两相 XID 标识符

• 
  is_prepared – 布尔值，表示 TwoPhaseTransaction.prepare（） 被调用。

属性 sqlalchemy.events.ConnectionEvents. 分派： _Dispatch[_ET] = <sqlalchemy.event.base.ConnectionEventsDispatch object>

引用回 _Dispatch 类。

针对 _Dispatch._events 的双向

方法 sqlalchemy.events.ConnectionEvents. engine_connect（conn： Connection）→ 无

拦截新 Connection 的创建。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'engine_connect')
def receive_engine_connect(conn):
    "listen for the 'engine_connect' event"

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

# DEPRECATED calling style (pre-2.0, will be removed in a future release)
@event.listens_for(SomeEngine, 'engine_connect')
def receive_engine_connect(conn, branch):
    "listen for the 'engine_connect' event"

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

在 2.0 版更改： 该 ConnectionEvents.engine_connect() 事件现在接受参数 ConnectionEvents.engine_connect.conn 。在未来的发行版中，将删除对接受上面列出的先前参数签名为“已弃用”的侦听器函数的支持。

此事件通常作为调用 Engine.connect（） 方法的直接结果而被调用。

它与 PoolEvents.connect（） 方法不同，后者 是指与 DBAPI 级别的数据库的实际连接; DBAPI 连接可以共用并重复使用用于许多作。 相比之下，此事件仅指更高级别的生产 此类 DBAPI 连接的连接包装器。

它与 PoolEvents.checkout（） 事件的不同之处在于，它特定于 Connection 对象，而不是 PoolEvents.checkout（） 处理的 DBAPI 连接。 虽然 此 DBAPI 连接可通过 Connection.connection 属性。但请注意，实际上可以有多个 PoolEvents.checkout（） 生命周期内的事件 的 连接 无效并重新建立。

参数

conn - 连接对象。

另请参阅

PoolEvents.checkout（） 较低级别的 Pool Checkout 事件 对于单个 DBAPI 连接

方法 sqlalchemy.events.ConnectionEvents. engine_disposed（engine： Engine）→ 无

在调用 Engine.dispose（） 方法时进行拦截。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'engine_disposed')
def receive_engine_disposed(engine):
    "listen for the 'engine_disposed' event"

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

Engine.dispose（） 方法指示引擎 “dispose” 它的连接池（例如 Pool），并将其替换为新的连接池。处置旧池的效果是关闭现有的签入连接。新池在首次使用之前不会建立任何新连接。

此事件可用于指示与 发动机也应该清理干净， 请记住， 发动机 仍可用于新请求，在这种情况下 它会重新获取连接资源。

方法 sqlalchemy.events.ConnectionEvents. prepare_twophase（conn： Connection， xid： Any）→ 无

拦截 prepare_twophase（） 事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'prepare_twophase')
def receive_prepare_twophase(conn, xid):
    "listen for the 'prepare_twophase' event"

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

参数

• 
  conn – 连接对象

• 
  xid– 两相 XID 标识符

method sqlalchemy.events.ConnectionEvents. release_savepoint（conn： Connection， name： str， context： None）→ 无

拦截 release_savepoint（） 事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'release_savepoint')
def receive_release_savepoint(conn, name, context):
    "listen for the 'release_savepoint' event"

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

参数

• 
  conn – 连接对象

• 
  name – 用于 Savepoint 的指定名称。

• 
  context – 未使用

method sqlalchemy.events.ConnectionEvents. rollback（conn： Connection）→ None（无

拦截 rollback（） 事件，由 交易。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'rollback')
def receive_rollback(conn):
    "listen for the 'rollback' event"

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

请注意，如果 reset_on_return flag 设置为其默认值 'rollback'。要拦截此回滚，请使用 PoolEvents.reset（） 钩子。

参数

conn – 连接对象

另请参阅

PoolEvents.reset（）

method sqlalchemy.events.ConnectionEvents. rollback_savepoint（conn： Connection， name： str， context： None）→ 无

拦截 rollback_savepoint（） 事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'rollback_savepoint')
def receive_rollback_savepoint(conn, name, context):
    "listen for the 'rollback_savepoint' event"

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

参数

• 
  conn – 连接对象

• 
  name – 用于 Savepoint 的指定名称。

• 
  context – 未使用

方法 sqlalchemy.events.ConnectionEvents. rollback_twophase（conn： Connection， xid： Any， is_prepared： bool）→ 无

拦截 rollback_twophase（） 事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'rollback_twophase')
def receive_rollback_twophase(conn, xid, is_prepared):
    "listen for the 'rollback_twophase' event"

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

参数

• 
  conn – 连接对象

• 
  xid– 两相 XID 标识符

• 
  is_prepared – 布尔值，表示 TwoPhaseTransaction.prepare（） 被调用。

method sqlalchemy.events.ConnectionEvents. savepoint（conn： Connection， name： str）→ 无

拦截 savepoint（） 事件。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'savepoint')
def receive_savepoint(conn, name):
    "listen for the 'savepoint' event"

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

参数

• 
  conn – 连接对象

• 
  name – 用于 Savepoint 的指定名称。

方法 sqlalchemy.events.ConnectionEvents. set_connection_execution_options（conn： Connection， opts： Dict[str， Any]）→ 无

Intercept 当 Connection.execution_options() 方法。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'set_connection_execution_options')
def receive_set_connection_execution_options(conn, opts):
    "listen for the 'set_connection_execution_options' event"

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

该方法在 new Connection 之后调用 已经 produced 的 Programmable S Collections 中，但 在 Dialect 对任何这些新选项采取行动之前。

请注意，当新的 连接 生成，它从其父级继承执行选项 发动机;要拦截此条件，请使用 ConnectionEvents.engine_connect() 事件。

参数

• 
  conn– 新复制的 Connection 对象

• 
  选项 –

  
  传递给 Connection.execution_options() 方法。此字典可以就地修改以影响生效的最终选项。

  
  2.0 版中的新功能： opts 字典可以就地修改。

另请参阅

ConnectionEvents.set_engine_execution_options() -事件 在 Engine.execution_options（） 时调用 被调用。

方法 sqlalchemy.events.ConnectionEvents. set_engine_execution_options（engine： Engine， opts： Dict[str， Any]）→ 无

当 Engine.execution_options（） 方法。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'set_engine_execution_options')
def receive_set_engine_execution_options(engine, opts):
    "listen for the 'set_engine_execution_options' event"

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

Engine.execution_options（） 方法生成 Engine 的浅表副本，用于存储新选项。 那个新的 Engine 在此处传递。此方法的一个特定应用是添加 ConnectionEvents.engine_connect() 事件 handler 添加到给定的 Engine 这将执行一些 特定于这些执行选项的 Connection 任务。

参数

• 
  conn– 新复制的 Engine 对象

• 
  选项 –

  
  传递给 Connection.execution_options() 方法。此字典可以就地修改以影响生效的最终选项。

  
  2.0 版中的新功能： opts 字典可以就地修改。

另请参阅

ConnectionEvents.set_connection_execution_options() -事件 Connection.execution_options() 在 是 叫。

类 sqlalchemy.events 中。Dialect事件

事件接口。

这些事件允许直接插桩和替换与 DBAPI 交互的关键方言函数。

注意

DialectEvents 钩子应被视为半公开 和实验性的。 这些钩子不是一般用途，仅适用于这些情况 其中 DBAPI 机制的复杂重述必须注入到 一种现有的方言。 对于通用的语句拦截事件， 请使用 ConnectionEvents 接口。

另请参阅

ConnectionEvents.before_cursor_execute()

ConnectionEvents.before_execute()

ConnectionEvents.after_cursor_execute()

ConnectionEvents.after_execute()

成员

调度、do_connect（）、do_execute（）、do_execute_no_params（）、do_executemany（）、do_setinputsizes（）、handle_error（）

类签名

类 sqlalchemy.events.DialectEvents （sqlalchemy.event.Events）

属性 sqlalchemy.events.DialectEvents. dispatch： _Dispatch[_ET] = <sqlalchemy.event.base.DialectEventsDispatch object>

引用回 _Dispatch 类。

针对 _Dispatch._events 的双向

方法 sqlalchemy.events.DialectEvents. do_connect（dialect： 方言， conn_rec： ConnectionPoolEntry， cargs： Tuple[Any、 ...]， cparams： Dict[str， Any]）→DBAPIConnectionNone

在建立连接之前接收连接参数。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_connect')
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    "listen for the 'do_connect' event"

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

此事件非常有用，因为它允许处理程序作 carg 和/或 cparams 集合，用于控制 DBAPI connect（） 函数。cargs 将始终是一个可以就地更改的 Python 列表，而 cparams 是一个也可以更改的 Python 字典：

e = create_engine("postgresql+psycopg2://user@host/dbname")


@event.listens_for(e, "do_connect")
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    cparams["password"] = "some_password"

事件钩子也可以用来覆盖对 connect（） 的调用 完全通过返回非 None DBAPI 连接对象：

e = create_engine("postgresql+psycopg2://user@host/dbname")


@event.listens_for(e, "do_connect")
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    return psycopg2.connect(*cargs, **cparams)

另请参阅

自定义 DBAPI connect（） 参数/连接例程

方法 sqlalchemy.events.DialectEvents. do_execute（光标：DBAPICursor，语句：str，参数：_DBAPISingleExecuteParams，上下文： ExecutionContext）→Literal[true]无

接收要调用 execute（） 的游标。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_execute')
def receive_do_execute(cursor, statement, parameters, context):
    "listen for the 'do_execute' event"

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

返回值 True 以停止调用更多事件，并指示游标执行已在事件处理程序中进行。

方法 sqlalchemy.events.DialectEvents. do_execute_no_params（游标：DBAPICursor，语句：str，上下文：ExecutionContext）→Literal[True]None

接收一个游标，其中 execute（） 没有调用任何参数。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_execute_no_params')
def receive_do_execute_no_params(cursor, statement, context):
    "listen for the 'do_execute_no_params' event"

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

返回值 True 以停止调用更多事件，并指示游标执行已在事件处理程序中进行。

方法 sqlalchemy.events.DialectEvents. do_executemany（cursor： DBAPICursor， statement： str， parameters： _DBAPIMultiExecuteParams， context： ExecutionContext）→Literal[True]无

接收一个游标以调用 executemany（）。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_executemany')
def receive_do_executemany(cursor, statement, parameters, context):
    "listen for the 'do_executemany' event"

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

返回值 True 以停止调用更多事件，并指示游标执行已在事件处理程序中进行。

方法 sqlalchemy.events.DialectEvents. do_setinputsizes（inputsizes： Dict[BindParameter[Any]， Any]， cursor： DBAPICursor， 语句： str， 参数： _DBAPIAnyExecuteParams， context： ExecutionContext）→ 无

接收 setinputsizes 字典以进行可能的修改。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_setinputsizes')
def receive_do_setinputsizes(inputsizes, cursor, statement, parameters, context):
    "listen for the 'do_setinputsizes' event"

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

如果方言使用 DBAPI cursor.setinputsizes（） 方法，则发出此事件，该方法传递有关 参数绑定。 给定的 inputsizes 字典将包含 BindParameter 对象 作为键，作为值链接到特定于 DBAPI 的类型对象;为 参数，它们会使用 None 作为值，这意味着不会包含该参数 在最终的 setInputSizes 调用中。 该事件可用于检查 和/或记录正在绑定的数据类型，以及修改 字典就位。 可以添加、修改或删除参数 来自这本词典。 调用方通常需要检查 BindParameter.type 属性，以便对 DBAPI 对象做出决策。

事件发生后，inputsizes 字典将转换为要传递给 cursor.setinputsizes 的相应数据结构;位置绑定参数执行样式的列表，或者命名绑定参数执行样式的 DBAPI 类型对象的字符串参数键字典。

setinputsizes 钩子总体上仅用于包含标志 use_setinputsizes=True 的方言。使用此方言包括 python-oracledb、cx_Oracle、pg8000、asyncpg 和 pyodbc 方言。

注意

要与 pyodbc 一起使用，必须将 use_setinputsizes 标志传递给方言，例如：

create_engine("mssql+pyodbc://...", use_setinputsizes=True)

另请参阅

setinputsizes 支持

在 1.2.9 版本加入.

另请参阅

使用 setinputsizes 对 cx_Oracle 数据绑定性能进行精细控制

方法 sqlalchemy.events.DialectEvents. handle_error（exception_context： ExceptionContext）→BaseExceptionNone

拦截 Dialect，通常但不限于在 Connection 范围内发出的方言。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeEngine, 'handle_error')
def receive_handle_error(exception_context):
    "listen for the 'handle_error' event"

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

在 2.0 版本发生变更： DialectEvents.handle_error（） 事件已移至 DialectEvents 类，从 ConnectionEvents 类，以便它也可以参与 配置了 create_engine.pool_pre_ping 参数。通过使用 Engine 作为事件目标，该事件将保持注册状态，但请注意，不再支持将 Connection 用作 DialectEvents.handle_error（） 的事件目标。

这包括 DBAPI 以及 SQLAlchemy 的语句调用过程中发出的所有异常，包括编码错误和其他语句验证错误。调用事件的其他区域包括事务开始和结束、结果行获取、游标创建。

请注意，handle_error（） 可能随时支持新类型的异常和新的调用方案。使用此事件的代码必须预期次要版本中会出现新的调用模式。

为了支持对应于异常的各种成员， 以及允许事件的可扩展性，而无需向后 不兼容，则收到的唯一参数是 ExceptionContext 的 ExceptionContext 中。此对象包含表示有关异常的详细信息的数据成员。

此 hook 支持的用例包括：

• 
  用于日志记录和调试目的的只读低级异常处理

• 
  确定 DBAPI 连接错误消息是否指示需要重新连接数据库连接，包括某些方言使用的 “pre_ping” 处理程序

• 
  建立或禁用连接或拥有连接池是否因特定异常而失效或过期

• 
  异常重写

当失败作的游标（如果有）仍处于打开状态且可访问时，将调用钩子。可以对此游标调用特殊的清理作;SQLAlchemy 将在调用此钩子后尝试关闭此游标。

从 SQLAlchemy 2.0 开始，pre_ping使用 对于这些方言，create_engine.pool_pre_ping 参数也将参与 handle_error（） 过程 依赖于 DISCONNECT 代码来检测数据库活动性。请注意，某些方言（如 psycopg、psycopg2 和大多数 MySQL 方言）使用 DBAPI 提供的本机 ping（） 方法，该方法不使用断开连接代码。

在 2.0.0 版本发生变更： DialectEvents.handle_error（） 事件钩子参与连接池的 “pre-ping”作。 在此用法中，ExceptionContext.engine 属性将为 None，但是正在使用的方言始终可通过 ExceptionContext.dialect 属性获得。

在 2.0.5 版本发生变更： 已添加ExceptionContext.is_pre_ping 属性，该属性将设置为 True，当 DialectEvents.handle_error（） 事件钩子在连接池预 ping作中触发。

在 2.0.5 版本发生变更： 修复了一个问题，该问题允许使用 PostgreSQL psycopg 和 psycopg2 驱动程序，以及所有 MySQL 驱动程序中，要正确参与 DialectEvents.handle_error（） 连接池 “pre-ping”作期间的事件钩子;以前，这些驱动程序的实现不起作用。

处理程序函数有两个选项，用于将 SQLAlchemy 构造的异常替换为用户定义的异常。它可以直接引发这个新的异常，在这种情况下，所有其他事件侦听器都将被绕过，并且在进行适当的清理后将引发异常：

@event.listens_for(Engine, "handle_error")
def handle_exception(context):
    if isinstance(
        context.original_exception, psycopg2.OperationalError
    ) and "failed" in str(context.original_exception):
        raise MySpecialException("failed operation")

警告

因为 DialectEvents.handle_error（） event 专门规定了要作为 失败语句引发的最终异常 如果用户定义的事件处理程序本身失败并引发意外异常，则堆栈跟踪将具有误导性;堆栈跟踪可能无法说明失败的实际代码行！建议在此处仔细编码，并在发生意外异常时使用日志记录和/或内联调试。

或者，可以使用 “链式” 风格的事件处理，方法是使用 retval=True 配置处理程序 修饰符并从 功能。 在这种情况下，事件处理将继续处理到 next 处理程序。 “chained” 异常可以使用 ExceptionContext.chained_exception ：

@event.listens_for(Engine, "handle_error", retval=True)
def handle_exception(context):
    if (
        context.chained_exception is not None
        and "special" in context.chained_exception.message
    ):
        return MySpecialException(
            "failed", cause=context.chained_exception
        )

返回 None 的处理程序可以在链中使用;当处理程序返回 None 时，前一个异常实例（如果有）将维护为传递给下一个处理程序的当前异常。

当引发或返回自定义异常时，SQLAlchemy 会引发 这个新的异常原样，它没有被任何 SQLAlchemy 包装 对象。 如果异常不是 sqlalchemy.exc.StatementError，则某些功能可能不可用;目前，这包括 ORM 的功能，即向 autoflush 进程中引发的异常添加有关 “autoflush” 的详细信息提示。

参数

context —— 一个 ExceptionContext 对象。有关所有可用成员的详细信息，请参阅此类。

另请参阅

支持断开连接场景的新数据库错误代码

Schema 事件

对象名称	描述
DDLEvents	定义架构对象的事件侦听器，即 SchemaItem 和其他 SchemaEventTarget 子类，包括 MetaData、Table、 柱等
SchemaEventTarget	作为 DDLEvents 目标的元素的基类 事件。

类 sqlalchemy.events 中。DDLEvents

定义架构对象的事件侦听器，即 SchemaItem 和其他 SchemaEventTarget 子类，包括 MetaData、Table、 柱等

创建/删除事件

将 CREATE 和 DROP 命令发送到数据库时发出的事件。此类别中的事件钩子包括 DDLEvents.before_create（）、 DDLEvents.after_create（）、DDLEvents.before_drop（） 和 DDLEvents.after_drop（） 中。

这些事件在使用 schema 级方法（如 MetaData.create_all（） 和 MetaData.drop_all（） 的 API 中。每个对象的创建/删除方法，例如 Table.create（）、Table.drop（）、 还包括 Index.create（） 以及特定于方言的方法，例如 ENUM.create（）。

2.0 新版功能： DDLEvents 事件钩子现在发生在非表对象上，包括约束、索引和特定于方言的模式类型。

事件钩子可以直接附加到 Table 对象或 MetaData 集合，以及任何 SchemaItem 类或对象，可以使用不同的 SQL 命令单独创建和删除。此类类包括 Index、 Sequence 和特定于方言的类（例如 枚举。

使用 DDLEvents.after_create（） 事件的示例，其中自定义事件钩子将在发出 CREATE TABLE 后在当前连接上发出 ALTER TABLE 命令：

from sqlalchemy import create_engine
from sqlalchemy import event
from sqlalchemy import Table, Column, Metadata, Integer

m = MetaData()
some_table = Table("some_table", m, Column("data", Integer))


@event.listens_for(some_table, "after_create")
def after_create(target, connection, **kw):
    connection.execute(
        text("ALTER TABLE %s SET name=foo_%s" % (target.name, target.name))
    )


some_engine = create_engine("postgresql://scott:tiger@host/test")

# will emit "CREATE TABLE some_table" as well as the above
# "ALTER TABLE" statement afterwards
m.create_all(some_engine)

Constraint 对象，例如 ForeignKeyConstraint、 UniqueConstraint 和 CheckConstraint 也可以订阅这些事件，但是它们通常不会产生事件，因为这些对象通常在封闭的 CREATE TABLE 语句中内联呈现，并从 DROP TABLE 语句。

对于 Index 构造，将为 CREATE INDEX 发出事件钩子，但 SQLAlchemy 通常不会发出 DROP INDEX，因为这再次隐含在 DROP TABLE 语句。

2.0 版本中的新功能： 支持 SchemaItem 对象 for create/drop 事件已从之前对 MetaData 和 Table 中还包括 Constraint 和所有子类、Index、 Sequence 和一些与类型相关的结构，例如 枚举。

注意

这些事件钩子仅在 SQLAlchemy 的 create/drop 方法范围内发出;它们不一定受 Alembic 等工具的支持。

附件事件

提供附件事件以在子架构元素与父元素关联时自定义行为，例如，当 Column 与其 Table 关联时，当 ForeignKeyConstraint 的 与 Table 关联，等等。 这些事件包括 DDLEvents.before_parent_attach() 和 DDLEvents.after_parent_attach() 。

Reflection 事件

DDLEvents.column_reflect（） 事件用于拦截 并在 继续对数据库表进行反射。

与泛型 DDL 一起使用

DDL 事件与 DDL 类和 DDL 子句构造的 ExecutableDDLElement 层次结构，它们本身适合用作侦听器可调用对象：

from sqlalchemy import DDL

event.listen(
    some_table,
    "after_create",
    DDL("ALTER TABLE %(table)s SET name=foo_%(table)s"),
)

事件传播到 MetaData 副本

对于所有 DDLEvent 事件，propagate=True 关键字参数将确保给定的事件处理程序传播到对象的副本，这些副本是在使用 Table.to_metadata（） 时创建的 方法：

from sqlalchemy import DDL

metadata = MetaData()
some_table = Table("some_table", metadata, Column("data", Integer))

event.listen(
    some_table,
    "after_create",
    DDL("ALTER TABLE %(table)s SET name=foo_%(table)s"),
    propagate=True,
)

new_metadata = MetaData()
new_table = some_table.to_metadata(new_metadata)

上述 DDL 对象将与 DDLEvents.after_create（） 事件new_table some_table。

另请参阅

事件

ExecutableDDLElement

DDL

控制 DDL 序列

成员

after_create（）， after_drop（）， after_parent_attach（）， before_create（）， before_drop（）， before_parent_attach（）， column_reflect（）， 调度

类签名

类 sqlalchemy.events.DDLEvents （sqlalchemy.event.Events）

方法 sqlalchemy.events.DDLEvents 中。after_create（target： SchemaEventTarget， connection： Connection， **kw： Any）→ 无

在发出 CREATE 语句后调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'after_create')
def receive_after_create(target, connection, **kw):
    "listen for the 'after_create' event"

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

参数

• 
  目标 –

  
  SchemaObject（例如 元数据或表 还包括所有 create/drop 对象，例如 Index、Sequence 等对象，该对象是事件的目标。

  
  2.0 版本中的新功能： 添加了对所有 SchemaItem 对象的支持。

• 
  connection- 发出 CREATE 语句或语句的 Connection。

• 
  **kw —— 与事件相关的其他关键字参数。此词典的内容可能因版本而异，包括为元数据级事件生成的表列表、checkfirst 标志以及内部事件使用的其他元素。

listen（） 也接受 propagate=True 修饰符;当 True 时，侦听器函数将 为目标对象创建的任何副本建立， 即在 使用 Table.to_metadata（） 。

方法 sqlalchemy.events.DDLEvents 中。after_drop（target： SchemaEventTarget， connection： Connection， **kw： Any）→ 无

在发出 DROP 语句后调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'after_drop')
def receive_after_drop(target, connection, **kw):
    "listen for the 'after_drop' event"

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

参数

• 
  目标 –

  
  SchemaObject（例如 元数据或表 还包括所有 create/drop 对象，例如 Index、Sequence 等对象，该对象是事件的目标。

  
  2.0 版本中的新功能： 添加了对所有 SchemaItem 对象的支持。

• 
  connection- 发出 DROP 语句或语句的 Connection。

• 
  **kw —— 与事件相关的其他关键字参数。此词典的内容可能因版本而异，包括为元数据级事件生成的表列表、checkfirst 标志以及内部事件使用的其他元素。

listen（） 也接受 propagate=True 修饰符;当 True 时，侦听器函数将 为目标对象创建的任何副本建立， 即在 使用 Table.to_metadata（） 。

方法 sqlalchemy.events.DDLEvents 中。after_parent_attach（目标：SchemaEventTarget，父级：SchemaItem）→ 无

在 SchemaItem 与父 SchemaItem 关联后调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'after_parent_attach')
def receive_after_parent_attach(target, parent):
    "listen for the 'after_parent_attach' event"

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

参数

• 
  target —— 目标对象

• 
  parent – 目标所附加到的父级。

listen（） 也接受 propagate=True 修饰符;当 True 时，侦听器函数将 为目标对象创建的任何副本建立， 即在 使用 Table.to_metadata（） 。

方法 sqlalchemy.events.DDLEvents 中。before_create（target： SchemaEventTarget， connection： Connection， **kw： Any）→ 无

在发出 CREATE 语句之前调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'before_create')
def receive_before_create(target, connection, **kw):
    "listen for the 'before_create' event"

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

参数

• 
  目标 –

  
  SchemaObject（例如 元数据或表 还包括所有 create/drop 对象，例如 Index、Sequence 等对象，该对象是事件的目标。

  
  2.0 版本中的新功能： 添加了对所有 SchemaItem 对象的支持。

• 
  connection- 将发出 CREATE 语句或语句的 Connection。

• 
  **kw —— 与事件相关的其他关键字参数。此词典的内容可能因版本而异，包括为元数据级事件生成的表列表、checkfirst 标志以及内部事件使用的其他元素。

listen（） 接受 propagate=True 修饰符;当 True 时，侦听器函数将 为目标对象创建的任何副本建立， 即在 使用 Table.to_metadata（） 。

listen（） 接受 insert=True 修饰符;当 True 时，侦听器函数将 在发现事件时添加到内部事件列表的前面，并执行 之前注册的侦听器函数，这些函数不传递此参数。

方法 sqlalchemy.events.DDLEvents 中。before_drop（target： SchemaEventTarget， connection： Connection， **kw： Any）→ 无

在发出 DROP 语句之前调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'before_drop')
def receive_before_drop(target, connection, **kw):
    "listen for the 'before_drop' event"

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

参数

• 
  目标 –

  
  SchemaObject（例如 元数据或表 还包括所有 create/drop 对象，例如 Index、Sequence 等对象，该对象是事件的目标。

  
  2.0 版本中的新功能： 添加了对所有 SchemaItem 对象的支持。

• 
  connection 将发出 DROP 语句或语句的 Connection。

• 
  **kw —— 与事件相关的其他关键字参数。此词典的内容可能因版本而异，包括为元数据级事件生成的表列表、checkfirst 标志以及内部事件使用的其他元素。

listen（） 也接受 propagate=True 修饰符;当 True 时，侦听器函数将 为目标对象创建的任何副本建立， 即在 使用 Table.to_metadata（） 。

方法 sqlalchemy.events.DDLEvents 中。before_parent_attach（目标：SchemaEventTarget，父级：SchemaItem）→无

在 SchemaItem 与父 SchemaItem 关联之前调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'before_parent_attach')
def receive_before_parent_attach(target, parent):
    "listen for the 'before_parent_attach' event"

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

参数

• 
  target —— 目标对象

• 
  parent – 目标所附加到的父级。

listen（） 也接受 propagate=True 修饰符;当 True 时，侦听器函数将 为目标对象创建的任何副本建立， 即在 使用 Table.to_metadata（） 。

方法 sqlalchemy.events.DDLEvents 中。column_reflect（检查器：检查器，表：表，column_info：ReflectedColumn）→无

为反映 Table 时检索到的每个 'column info' 单元调用。

参数形式示例：

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'column_reflect')
def receive_column_reflect(inspector, table, column_info):
    "listen for the 'column_reflect' event"

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

此事件最容易使用，方法是将其应用于特定的 MetaData 实例，它将对该实例中的所有 Table 对象生效 进行反射的 MetaData：

metadata = MetaData()


@event.listens_for(metadata, "column_reflect")
def receive_column_reflect(inspector, table, column_info):
    # receives for all Table objects that are reflected
    # under this MetaData
    ...


# will use the above event hook
my_table = Table("my_table", metadata, autoload_with=some_engine)

1.4.0b2 版本中的新功能： DDLEvents.column_reflect（） hook 现在可以应用于 MetaData 对象以及 MetaData 类本身，它将发生在与目标 MetaData 关联的所有 Table 对象中。

它也可以全面应用于 Table 类：

from sqlalchemy import Table


@event.listens_for(Table, "column_reflect")
def receive_column_reflect(inspector, table, column_info):
    # receives for all Table objects that are reflected
    ...

它也可以应用于 点，该点正在使用 Table.listeners 参数：

t1 = Table(
    "my_table",
    autoload_with=some_engine,
    listeners=[("column_reflect", receive_column_reflect)],
)

传递方言返回的列信息字典，并且可以修改。字典是 Inspector.get_columns（） 返回的列表的每个元素中返回的字典：

• 
  name - 列的名称应用于 Column.name 参数

• 
  type - 此列的类型（应该是 TypeEngine 的实例）应用于 Column.type 参数

• 
  nullable - 如果列为 NULL 或 NOT NULL，则布尔标志应用于 Column.nullable 参数

• 
  default - 列的服务器默认值。这通常被指定为纯字符串 SQL 表达式，但是该事件也可以传递 FetchedValue、DefaultClause 或 text（） 对象。 应用于 Column.server_default 参数

在对此字典执行任何作之前，将调用该事件，并且可以修改内容;可以将以下附加键添加到字典中，以进一步修改 Column 的构造方式：

• 
  key - 将用于访问此 .c 集合中的列;将应用于 Column.key 参数。也被使用 用于 ORM 映射。 请参阅该部分 例如，从反射表中自动执行列命名方案。

• 
  quote - 对列名称强制或取消强制引用;应用于 Column.quote 参数。

• 
  info - 与 Column 一起遵循的任意数据的字典，应用于 Column.info 参数。

listen（） 也接受 propagate=True 修饰符;当 True 时，侦听器函数将 为目标对象创建的任何副本建立， 即在 使用 Table.to_metadata（） 。

另请参阅

从反射表中自动化列命名方案 - 在 ORM 映射文档中

截获列定义 - 在 Automap 文档中

使用与数据库无关的类型进行反射 - 在“反射数据库对象”文档中

属性 sqlalchemy.events.DDLEvents。dispatch： _Dispatch[_ET] = <sqlalchemy.event.base.DDLEventsDispatch 对象>

引用回 _Dispatch 类。

针对 _Dispatch._events 的双向

类 sqlalchemy.events 中。SchemaEventTarget（模式事件目标

作为 DDLEvents 目标的元素的基类 事件。

这包括 SchemaItem 和 SchemaType。

类签名

类 sqlalchemy.events.SchemaEventTarget （ sqlalchemy.event.registry.EventTarget ）