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）

模式事件

热门文章

最新文章

相关电子书