SqlAlchemy 2.0 中文文档（四十六）（1）-阿里云开发者社区

核心事件

原文：docs.sqlalchemy.org/en/20/core/events.html

本节描述了 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

SqlAlchemy 2.0 中文文档（四十六）（1）

核心事件

连接池事件

热门文章

最新文章

相关电子书