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

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

模式事件

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()时会发出这些事件。还包括每个对象的创建/删除方法，例如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 的 create/drop 方法范围内触发；并不一定被诸如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 –
  SchemaObject，比如MetaData或Table，但也包括所有创建/删除对象，如Index、Sequence等，这些对象是事件的目标。
  新版本 2.0 中：添加了对所有SchemaItem对象的支持。
  
• connection – Connection，在其中发出了 CREATE 语句或语句。
  
• **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，但也包括所有创建/删除对象，如 Index、Sequence 等，是事件的目标对象。
  新版本 2.0 中：添加了对所有 SchemaItem 对象的支持。
  
• connection – Connection，在其中发出了 DROP 语句或语句。
  
• **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时检索每个‘column info’单元时调用。

示例参数形式：

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类本身，它将对与目标MetaData关联的所有Table对象进行操作。

它也可以应用于整个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)