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

SqlAlchemy 2.0 中文文档（四十六）（4）https://developer.aliyun.com/article/1563037

SQL 执行和连接事件

对象名称	描述
ConnectionEvents	对于`Connection`和`Engine`可用的事件。
DialectEvents	用于执行替换函数的事件接口。

class sqlalchemy.events.ConnectionEvents

对于Connection和Engine可用的事件。

这里的方法定义了事件的名称以及传递给监听器函数的成员的名称。

事件监听器可以与任何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：

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()中，语句是传输到连接的 DBAPIcursor中准备的确切 SQL 字符串，该连接的Dialect。

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实例，所有四个作用域的事件都将触发。但是，出于性能原因，Connection对象在实例化时确定其父Engine是否已建立事件侦听器。在依赖的Connection实例实例化之后，添加到Engine类或Engine实例的事件侦听器通常不会在该Connection实例上可用。新添加的侦听器将取代对父Engine类或实例建立事件侦听器后创建的Connection实例。

参数：

retval=False – 仅适用于before_execute()和before_cursor_execute()事件。当值为 True 时，用户定义的事件函数必须有一个返回值，即替换给定语句和参数的参数元组。查看这些方法以获取特定返回参数的描述。

成员

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(), rollback_savepoint(), rollback_twophase(), savepoint(), set_connection_execution_options(), set_engine_execution_options()

类签名

类sqlalchemy.events.ConnectionEvents (sqlalchemy.event.Events)

method after_cursor_execute(conn: Connection, cursor: DBAPICursor, statement: str, parameters: _DBAPIAnyExecuteParams, context: ExecutionContext | None, 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 – Connection对象
cursor – DBAPI 游标对象。如果语句是 SELECT，则将有待处理的结果，但不应消耗这些结果，因为它们将被CursorResult所需。
statement – 字符串 SQL 语句，如传递给 DBAPI
parameters – 字典、元组或传递给 DBAPI cursor的execute()或executemany()方法的参数列表。在某些情况下可能为None。
context – 正在使用的ExecutionContext对象。可能为None。
executemany – 布尔值，如果为True，则这是一个executemany()调用，如果为False，则这是一个execute()调用。

method after_execute(conn: Connection, clauseelement: Executable, multiparams: _CoreMultiExecuteParams, params: _CoreSingleExecuteParams, execution_options: _ExecuteOptions, result: Result[Any]) → None

在执行后拦截高级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 – Connection 对象
clauseelement – SQL 表达式构造，Compiled 实例，或传递给 Connection.execute() 的字符串语句。
multiparams – 多个参数集，一个字典列表。
params – 单个参数集，一个字典。
execution_options –
传递给语句的执行选项字典，如果有的话。这是将要使用的所有选项的合并，包括语句、连接和传递给方法本身的那些选项，用于执行 2.0 风格。
result – 执行生成的 CursorResult。

method before_cursor_execute(conn: Connection, cursor: DBAPICursor, statement: str, parameters: _DBAPIAnyExecuteParams, context: ExecutionContext | None, 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 – Connection 对象
cursor – DBAPI 游标对象
statement – 要传递给 DBAPI 的字符串 SQL 语句
parameters – 正在传递给 DBAPI cursor 的 execute() 或 executemany() 方法的参数的字典、元组或列表。在某些情况下可能为 None。
context – ExecutionContext 对象正在使用。可能为 None。
executemany – 布尔值，如果为 True，则这是一个 executemany() 调用，如果为 False，则这是一个 execute() 调用。

另请参阅

before_execute()

after_cursor_execute()

method before_execute(conn: Connection, clauseelement: Executable, multiparams: _CoreMultiExecuteParams, params: _CoreSingleExecuteParams, execution_options: _ExecuteOptions) → Tuple[Executable, _CoreMultiExecuteParams, _CoreSingleExecuteParams] | None

拦截高级 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 – Connection 对象
clauseelement – SQL 表达式构造，Compiled 实例，或传递给Connection.execute()的字符串语句。
multiparams – 多参数集合，一个字典列表。
params – 单参数集合，一个字典。
execution_options –
执行选项字典随语句一起传递，如果有的话。这是将被使用的所有选项的合并，包括语句、连接和传递给方法本身的 2.0 执行风格的选项。

另请参阅

before_cursor_execute()

method begin(conn: Connection) → None

拦截begin()事件。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeEngine, 'begin')
def receive_begin(conn):
    "listen for the 'begin' event"
    # ... (event handling logic) ...

参数：

conn – Connection 对象

method begin_twophase(conn: Connection, xid: Any) → None

拦截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 – Connection 对象
xid – 两阶段 XID 标识符

method commit(conn: Connection) → None

拦截由Transaction发起的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标志设置为值'commit'，Pool也可能在检入时“自动提交”DBAPI 连接。要拦截此提交，请使用PoolEvents.reset()钩子。

参数：

conn – Connection 对象

method commit_twophase(conn: Connection, xid: Any, is_prepared: bool) → None

拦截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 – Connection 对象
xid – 两阶段 XID 标识符
is_prepared – 布尔值，指示是否调用了TwoPhaseTransaction.prepare()。

attribute dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.ConnectionEventsDispatch object>

引用回 _Dispatch 类。

双向针对 _Dispatch._events

method engine_connect(conn: Connection) → None

拦截创建新的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 连接的更高级别Connection包装器。

它还与PoolEvents.checkout()事件不同，后者特定于Connection对象，而不是PoolEvents.checkout()处理的 DBAPI 连接，尽管此 DBAPI 连接可通过Connection.connection属性在此处获取。但请注意，在单个Connection对象的生命周期内，实际上可以有多个PoolEvents.checkout()事件，如果该Connection被使无效并重新建立。

参数：

conn – Connection 对象。

另请参见

PoolEvents.checkout() 是针对单个 DBAPI 连接的低级别池检出事件。

method engine_disposed(engine: Engine) → None

拦截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()方法指示引擎“处理”其连接池（例如Pool)，并用新的替换它。处理旧池的效果是关闭现有的已检入连接。新池在首次使用之前不会建立任何新连接。

可以使用此事件指示应清理与Engine相关的资源，需要注意的是Engine仍然可以用于新请求，此时会重新获取连接资源。

method prepare_twophase(conn: Connection, xid: Any) → None

拦截 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 – Connection 对象
xid – 两阶段 XID 标识符

method release_savepoint(conn: Connection, name: str, context: None) → 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) ...

SqlAlchemy 2.0 中文文档（四十六）（6）https://developer.aliyun.com/article/1563040

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

SQL 执行和连接事件

热门文章

最新文章

相关电子书