核心事件

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

class sqlalchemy.event.base.Events

Object Name	Description
PoolEvents	的可用事件 Pool .

class sqlalchemy.events.PoolEvents

Object Name	Description
ConnectionEvents	的可用事件 Connectable ，其中包括 Connection 和 Engine .
DialectEvents	执行替换函数的事件接口。

class sqlalchemy.events.ConnectionEvents

Object Name	Description
DDLEvents	为模式对象定义事件侦听器，即， SchemaItem 等 SchemaEventTarget 子类，包括 MetaData ， Table ， Column .
SchemaEventTarget	作为目标的元素的基类 DDLEvents 事件。

class sqlalchemy.events.DDLEvents¶

为模式对象定义事件侦听器，即， SchemaItem 等 SchemaEventTarget 子类，包括 MetaData ， Table ， Column .

MetaData 和 Table 支持特定于何时将创建和删除DDL发送到数据库的事件。

当子架构元素与父级相关联时，也会提供附件事件以自定义行为，例如，当 Column 与其关联 Table 当A ForeignKeyConstraint 与 Table 等。

示例使用 after_create 事件：

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

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

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

event.listen(some_table, "after_create", after_create)

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

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

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

为了所有 DDLEvent 事件， propagate=True 关键字参数将确保将给定的事件处理程序传播到使用 Table.to_metadata() 方法：

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

new_table = some_table.to_metadata(new_metadata)

以上 DDL 对象也将与 Table 对象由表示 new_table .

参见

事件

DDLElement

DDL

控制DDL序列

类签名

class sqlalchemy.events.DDLEvents (sqlalchemy.event.Events)

method sqlalchemy.events.DDLEvents.after_create(target, connection, **kw)¶

在发出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) ...

参数

• target¶ -- 这个 MetaData 或 Table 对象，它是事件的目标。

• connection¶ -- 这个 Connection 其中发出了一个或多个create语句。

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

listen() 也接受 propagate=True 此事件的修饰符；如果为true，则将为目标对象的任何副本建立侦听器函数，即在 Table.to_metadata() 使用。

method sqlalchemy.events.DDLEvents.after_drop(target, connection, **kw)¶

在发出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) ...

参数

• target¶ -- 这个 MetaData 或 Table 对象，它是事件的目标。

• connection¶ -- 这个 Connection 已发出DROP语句的位置。

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

listen() 也接受 propagate=True 此事件的修饰符；如果为true，则将为目标对象的任何副本建立侦听器函数，即在 Table.to_metadata() 使用。

method sqlalchemy.events.DDLEvents.after_parent_attach(target, parent)¶

打电话后 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() 使用。

method sqlalchemy.events.DDLEvents.before_create(target, connection, **kw)¶

在发出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) ...

参数

• target¶ -- 这个 MetaData 或 Table 对象，它是事件的目标。

• connection¶ -- 这个 Connection 其中将发出一个或多个create语句。

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

listen() 接受 propagate=True 此事件的修饰符；如果为True，则将为目标对象的任何副本(即在以下情况下生成的副本)建立侦听器函数 Table.to_metadata() 是使用的。

listen() 接受 insert=True 修饰符；如果为True，则侦听器函数在发现时将优先于内部事件列表，并在不传递此参数的已注册侦听器函数之前执行。

method sqlalchemy.events.DDLEvents.before_drop(target, connection, **kw)¶

在发出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) ...

参数

• target¶ -- 这个 MetaData 或 Table 对象，它是事件的目标。

• connection¶ -- 这个 Connection 其中将发出一个或多个drop语句。

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

listen() 也接受 propagate=True 此事件的修饰符；如果为true，则将为目标对象的任何副本建立侦听器函数，即在 Table.to_metadata() 使用。

method sqlalchemy.events.DDLEvents.before_parent_attach(target, parent)¶

前调用 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() 使用。

method sqlalchemy.events.DDLEvents.column_reflect(inspector, table, column_info)¶

当 Table 正在被反映。

示例参数形式：

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() 钩子现在可以应用于 MetaData 对象以及 MetaData 在所有人都会发生的地方给自己上课 Table 与目标对象关联的对象 MetaData .

它也可以应用于 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 在使用 Table.listeners 参数：：

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

将来的版本将允许它与特定的 MetaData 对象也是如此。

通过方言返回的列信息字典，可以修改。字典是在列表的每个元素中返回的 Inspector.get_columns() ：

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

• type -此列的类型，应为 TypeEngine ，应用于 Column.type 参数

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

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

在对此字典执行任何操作之前调用该事件，并且可以修改内容；可以向字典中添加以下附加键以进一步修改 Column 建造：

• key -将用于访问此的字符串键 Column 在 .c 集合；将应用于 Column.key 参数。也用于ORM映射。参见章节 从反射表自动化列命名方案 举个例子。

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

• info -随附的任意数据字典 Column ，应用于 Column.info 参数。

listen() 也接受 propagate=True 此事件的修饰符；如果为true，则将为目标对象的任何副本建立侦听器函数，即在 Table.to_metadata() 使用。

参见

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

截取列定义 -在 自动程序 文档

使用数据库不可知类型反映 -在 反映数据库对象 文档

class sqlalchemy.events.SchemaEventTarget¶

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

这包括 SchemaItem 以及 SchemaType .