核心事件
本节描述了 SQLAlchemy Core 中提供的事件接口。有关事件监听 API 的介绍，请参阅 Events。ORM 事件在 ORM Events 中描述。
| 对象名称 | 描述 |
| Events | 为特定目标类型定义事件监听函数。 |
class sqlalchemy.event.base.Events
为特定目标类型定义事件监听函数。
成员
dispatch
类签名
类sqlalchemy.event.Events (sqlalchemy.event._HasEventsDispatch)
attribute dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.EventsDispatch object>
参考 _Dispatch class。
对抗 _Dispatch._events
连接池事件
| 对象名称 | 描述 |
| PoolEvents | Pool的可用事件。 |
| PoolResetState | 描述传递给PoolEvents.reset()连接池事件的 DBAPI 连接的状态。 |
class sqlalchemy.events.PoolEvents
Pool的可用事件。
这里的方法定义了事件的名称以及传递给监听器函数的成员的名称。
例如:
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)
method checkin(dbapi_connection: DBAPIConnection | None, connection_record: ConnectionPoolEntry) → None
当连接返回到池时调用。
示例参数形式:
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。对于分离连接，不会调用checkin（它们不会返回到池中）。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。
method checkout(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, connection_proxy: PoolProxiedConnection) → None
当从连接池中检索到连接时调用。
示例参数形式：
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时。
method close(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None
当关闭 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_detached()。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。
method close_detached(dbapi_connection: DBAPIConnection) → None
当分离的 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) ...
在关闭发生之前发出事件。
连接的关闭可能失败；通常是因为连接已关闭。如果关闭操作失败，则连接将被丢弃。
参数：
dbapi_connection – 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection 属性。
method connect(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None
在给定的 Pool 中首次创建特定 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。
method detach(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None
当一个 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) ...
此事件在分离发生后发出。连接不再与给定的连接记录关联。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。
attribute dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.PoolEventsDispatch object>
回到 _Dispatch 类的引用。
双向针对 _Dispatch._events
method first_connect(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None
当第一次从特定的 Pool 中检出 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() 的理由是根据所有连接使用的设置确定有关特定系列数据库连接的信息。由于特定的 Pool 引用单个“创建者”函数（在 Engine 中引用 URL 和连接选项使用），通常可以假定关于单个连接的观察结果对所有后续连接都是有效的，例如数据库版本，服务器和客户端编码设置，排序规则设置等等。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。
method invalidate(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, exception: BaseException | None) → None
在要“失效”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()方法时，无论是通过 API 使用还是通过“自动失效”，都会触发此事件，而且没有soft标志。
事件发生在对连接调用.close()的最终尝试之前。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。exception– 对应于此失效原因的异常对象，如果有的话。可能为None。
另请参阅
更多关于失效的信息
method reset(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, reset_state: PoolResetState) → None
在池化连接发生“重置”操作之前调用。
示例参数形式：
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。支持接受先前参数签名的监听器函数将在将来的版本中删除。
此事件表示在将 DBAPI 连接返回到池中或丢弃之前调用rollback()方法时发生。可以使用此事件钩子实现自定义“重置”策略，也可以结合使用Pool.reset_on_return参数禁用默认的“重置”行为。
PoolEvents.reset() 和 PoolEvents.checkin() 事件的主要区别在于 PoolEvents.reset() 不仅适用于将返回池的池化连接，还适用于使用 Connection.detach() 方法分离的连接以及由于连接在被检入之前发生垃圾回收而被丢弃的 asyncio 连接。
请注意，不会为使用 Connection.invalidate() 使无效的连接调用此事件。这些事件可以通过 PoolEvents.soft_invalidate() 和 PoolEvents.invalidate() 事件钩子拦截，并且所有“连接关闭”事件可以通过 PoolEvents.close() 拦截。
PoolEvents.reset() 事件通常紧跟着 PoolEvents.checkin() 事件，在连接在重置后立即被丢弃的情况下除外。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。reset_state–PoolResetState实例，提供有关正在重置连接的情况的信息。
从版本 2.0 开始新增。
另请参见
返回时重置
ConnectionEvents.rollback()
ConnectionEvents.commit()
method soft_invalidate(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, exception: BaseException | None) → None
当要“软使无效” 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) ...
每当使用 soft 标志调用 ConnectionPoolEntry.invalidate() 方法时，都会调用此事件。
软失效是指跟踪此连接的连接记录将在当前连接签入后强制重新连接。它不会在调用它的点主动关闭 dbapi_connection。
参数：
dbapi_connection– 一个 DBAPI 连接。ConnectionPoolEntry.dbapi_connection属性。connection_record– 管理 DBAPI 连接的ConnectionPoolEntry。exception– 无效原因对应的异常对象，如果没有则可能是None。
class sqlalchemy.events.PoolResetState
描述 DBAPI 连接在传递给PoolEvents.reset()连接池事件时的状态。
成员
asyncio_safe, terminate_only, transaction_was_reset
在版本 2.0.0b3 中新增。
attribute asyncio_safe: bool
指示重置操作是否发生在期望在 asyncio 应用程序中存在的封闭事件循环范围内。
如果连接正在被垃圾回收，则为 False。
attribute terminate_only: bool
指示连接是否立即终止并且不被签入到池中。
这发生在失效的连接以及未被调用代码清理地处理的 asyncio 连接，而是被垃圾回收时。在后一种情况下，不能在垃圾回收中安全地运行 asyncio 连接上的操作，因为不一定存在事件循环。
attribute transaction_was_reset: bool
指示 DBAPI 连接上的事务是否已经由Connection对象实质上“重置”。
如果Connection上有事务状态，并且然后没有使用Connection.rollback()或Connection.commit()方法关闭事务；相反，事务在Connection.close()方法内联关闭，因此在到达此事件时保证保持不存在。
SqlAlchemy 2.0 中文文档（四十六）（2）https://developer.aliyun.com/article/1563035
