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

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

模式事件

对象名称	描述
DDLEvents	为模式对象定义事件监听器，即`SchemaItem`和其他`SchemaEventTarget`子类，包括`MetaData`、`Table`、`Column`等。
SchemaEventTarget	用于`DDLEvents`事件的目标元素的基类。

class sqlalchemy.events.DDLEvents

为模式对象定义事件监听器，即SchemaItem和其他SchemaEventTarget子类，包括MetaData、Table、Column等。

创建/删除事件

当 CREATE 和 DROP 命令发送到数据库时发出的事件。此类别中的事件挂钩包括DDLEvents.before_create()，DDLEvents.after_create()，DDLEvents.before_drop()和DDLEvents.after_drop()。

当使用模式级方法（例如MetaData.create_all()和MetaData.drop_all()）时，会发出这些事件。还包括每个对象的 create/drop 方法，如Table.create()，Table.drop()，Index.create()，以及特定于方言的方法，如ENUM.create()。

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

事件挂钩可以直接附加到Table对象或MetaData集合，以及任何可通过单独的 SQL 命令创建和删除的SchemaItem类或对象。此类包括Index，Sequence以及特定于方言的类，例如ENUM。

使用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)

约束对象，如ForeignKeyConstraint、UniqueConstraint、CheckConstraint，也可以订阅这些事件，但通常不会产生事件，因为这些对象通常是内联渲染在一个包含的CREATE TABLE语句中，并且在DROP TABLE语句中隐式地被删除。

对于Index构造，事件钩子将被触发为CREATE INDEX，但是当删除表时，SQLAlchemy 通常不会发出DROP INDEX，因为这再次隐含在DROP TABLE语句中。

新版本 2.0 中：支持SchemaItem对象的创建/删除事件从其先前对MetaData和Table的支持扩展到还包括Constraint和所有子类、Index、Sequence以及一些与类型相关的构造，比如ENUM。

注意

这些事件钩子仅在 SQLAlchemy 的创建/删除方法范围内触发；它们不一定受到诸如alembic之类的工具的支持。

附加事件

附加事件提供了自定义行为的机会，每当一个子模式元素与父元素相关联时，比如当一个Column与其Table相关联时，当一个ForeignKeyConstraint与一个Table相关联时等。这些事件包括DDLEvents.before_parent_attach()和DDLEvents.after_parent_attach()。

反射事件

DDLEvents.column_reflect()事件用于拦截和修改数据库表反射进行时的数据库列的 Python 中定义。

与通用 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对象将与some_table和new_table``Table对象的DDLEvents.after_create()事件相关联。

另请参阅

事件

ExecutableDDLElement

DDL

控制 DDL 序列

成员

after_create()、after_drop()、after_parent_attach()、before_create()、before_drop()、before_parent_attach()、column_reflect()、dispatch

类签名

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

method after_create(target: SchemaEventTarget, connection: Connection, **kw: Any) → None

在发出 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，但也包括所有创建/删除对象，如Index、Sequence等。
版本 2.0 新增：添加对所有SchemaItem对象的支持。
connection – 发出 CREATE 语句或语句的Connection。
**kw – 与事件相关的附加关键字参数。此字典的内容可能会在不同版本之间变化，并包括在元数据级事件中生成的表列表、checkfirst 标志以及内部事件使用的其他元素。

listen() 还接受propagate=True修饰符，用于此事件；当为 True 时，监听器函数将为目标对象的任何副本建立，即在使用Table.to_metadata() 生成的那些副本。

method after_drop(target: SchemaEventTarget, connection: Connection, **kw: Any) → None

在发出 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 –
事件目标的SchemaObject，例如MetaData或Table，但也包括所有 create/drop 对象，如Index、Sequence 等对象。
新版本 2.0 中添加了对所有SchemaItem对象的支持。
connection – 发出 DROP 语句或语句的Connection。
**kw – 与事件相关的附加关键字参数。此字典的内容可能会在不同版本之间变化，并包括在元数据级事件中生成的表列表、checkfirst 标志以及内部事件使用的其他元素。

listen() 还接受propagate=True修饰符，用于此事件；当为 True 时，监听器函数将为目标对象的任何副本建立，即在使用Table.to_metadata() 生成的那些副本。

method after_parent_attach(target: SchemaEventTarget, parent: SchemaItem) → None

在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 before_create(target: SchemaEventTarget, connection: Connection, **kw: Any) → None

在生成 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 –
SchemaObject，比如MetaData或Table，还包括所有的创建/删除对象，比如Index、Sequence等，这些对象是事件的目标。
2.0 版新增：对所有SchemaItem对象的支持已添加。
connection – 将发出 CREATE 语句或语句的Connection。
**kw – 与事件相关的其他关键字参数。此字典的内容可能会在不同版本之间变化，并包括元数据级事件生成的表列表、checkfirst 标志和内部事件使用的其他元素。

listen()接受propagate=True修饰符用于此事件；当为 True 时，监听函数将为目标对象的任何副本建立，即在使用Table.to_metadata()时生成的那些副本。

listen()接受insert=True修饰符用于此事件；当为 True 时，监听函数将被添加到内部事件列表的开头，并在未传递此参数的已注册监听函数之前执行。

method before_drop(target: SchemaEventTarget, connection: Connection, **kw: Any) → None

在生成 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 –
SchemaObject，比如MetaData或Table，还包括所有的创建/删除对象，比如Index、Sequence等，这些对象是事件的目标。
2.0 版新增：对所有SchemaItem对象的支持已添加。
connection – 发出 DROP 语句的Connection。
**kw – 与事件相关的附加关键字参数。此字典的内容可能因发布而异，包括用于元数据级事件生成表的表列表，checkfirst 标志和内部事件使用的其他元素。

listen()也接受propagate=True修饰符用于此事件；当为 True 时，监听器函数将为目标对象的任何副本建立，即在使用Table.to_metadata()生成的那些副本。

method before_parent_attach(target: SchemaEventTarget, parent: SchemaItem) → None

在将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 column_reflect(inspector: Inspector, table: Table, column_info: ReflectedColumn) → None

在对反射的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实例来使用，在该实例中，它将对该MetaData中的所有Table对象产生影响，这些对象在反射时进行。

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.listeners参数反射的特定Table上：

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的字符串键；将应用于Column.key参数。也用于 ORM 映射。参见从反射表自动命名列方案一节的示例。

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

info - 一个包含任意数据的字典，用于跟踪Column，应用于Column.info参数。

listen()还接受propagate=True修改器用于此事件；当为 True 时，监听器函数将为目标对象的任何副本建立，即使用Table.to_metadata()生成的那些副本。

另请参阅

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

拦截列定义 - 在 Automap 文档中

反映与数据库无关的类型 - 在反射数据库对象文档中

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

回引到 _Dispatch 类。

双向与 _Dispatch._events 相对

class sqlalchemy.events.SchemaEventTarget

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

这包括SchemaItem以及SchemaType。

类签名

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

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

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

模式事件

热门文章

最新文章

相关电子书

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

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

模式事件

热门文章

最新文章

相关电子书