SqlAlchemy 2.0 中文文档（二十六）（2）

SqlAlchemy 2.0 中文文档（二十六）（1）https://developer.aliyun.com/article/1560472

实例事件

实例事件专注于 ORM 映射实例的构造，包括当它们被实例化为瞬态对象时，当它们从数据库加载并成为持久化对象时，以及当数据库刷新或对象上的过期操作发生时。

class sqlalchemy.orm.InstanceEvents

定义了与对象生命周期特定的事件。

例如：

from sqlalchemy import event
def my_load_listener(target, context):
    print("on load!")
event.listen(SomeClass, 'load', my_load_listener)

可用的目标包括：

• 映射类
  
• 映射或将要映射的类的未映射超类（使用 propagate=True 标志）
  
• Mapper对象
  
• Mapper类本身指示监听所有映射器。
  

实例事件与映射器事件密切相关，但更具体于实例及其仪器，而不是其持久性系统。

在使用InstanceEvents时，listen()函数提供了几个修饰符。

参数：

• propagate=False – 当为 True 时，事件监听器应该应用于所有继承类��以及作为此监听器目标的类。
  
• raw=False – 当为 True 时，传递给适用事件监听器函数的“target”参数将是实例的InstanceState管理对象，而不是映射实例本身。
  
• restore_load_context=False –
  适用于InstanceEvents.load()和InstanceEvents.refresh()事件。在事件挂钩完成时恢复对象的加载器上下文，以便持续的急切加载操作继续适当地针对对象。如果未设置此标志，并且在这些事件之一中将对象移动到新的加载器上下文，则会发出警告。
  自版本 1.3.14 起新增。
  

成员

dispatch, expire(), first_init(), init(), init_failure(), load(), pickle(), refresh(), refresh_flush(), unpickle()

类签名

类sqlalchemy.orm.InstanceEvents (sqlalchemy.event.Events)

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

回溯到 _Dispatch 类。

双向反对 _Dispatch._events

method expire(target: _O, attrs: Iterable[str] | None) → None

在某些属性或其子集已过期后接收对象实例。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass, 'expire')
def receive_expire(target, attrs):
    "listen for the 'expire' event"
    # ... (event handling logic) ...

‘keys’是属性名称列表。如果为 None，则整个状态已过期。

参数：

• target – 映射实例。如果事件配置为raw=True，则这将是与实例关联的InstanceState状态管理对象。
  
• attrs – 已过期的属性名称序列，如果所有属性都已过期，则为 None。
  

method first_init(manager: ClassManager[_O], cls: Type[_O]) → None

在调用特定映射的第一个实例时调用。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass, 'first_init')
def receive_first_init(manager, cls):
    "listen for the 'first_init' event"
    # ... (event handling logic) ...

当为该特定类第一次调用__init__方法时，调用此事件。事件在__init__实际进行之前以及在调用InstanceEvents.init()事件之前被调用。

method init(target: _O, args: Any, kwargs: Any) → None

在构造函数被调用时接收一个实例。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass, 'init')
def receive_init(target, args, kwargs):
    "listen for the 'init' event"
    # ... (event handling logic) ...

这个方法只在对象的用户空间构造期间调用，与对象的构造函数一起，例如它的__init__方法。当对象从数据库加载时不会调用它；请参见InstanceEvents.load()事件以拦截数据库加载。

事件在实际调用对象的__init__构造函数之前被调用。kwargs字典可以被就地修改，以影响传递给__init__的内容。

参数：

• target – 映射的实例。如果事件配置为raw=True，那么这将是与实例关联的InstanceState状态管理对象。
  
• args – 传递给__init__方法的位置参数。这被传递为一个元组，目前是不可变的。
  
• kwargs – 传递给__init__方法的关键字参数。这个结构可以被就地修改。
  

另请参见

InstanceEvents.init_failure()

InstanceEvents.load()

method init_failure(target: _O, args: Any, kwargs: Any) → None

在实例构造函数被调用并引发异常时接收一个实例。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass, 'init_failure')
def receive_init_failure(target, args, kwargs):
    "listen for the 'init_failure' event"
    # ... (event handling logic) ...

这个方法只在对象的用户空间构造期间调用，与对象的构造函数一起，例如它的__init__方法。当对象从数据库加载时不会调用它。

事件在__init__方法引发异常后被调用。事件被调用后，原始异常被重新引发，以便对象的构造仍然引发异常。引发的实际异常和堆栈跟踪应该存在于sys.exc_info()中。

参数：

• target – 映射的实例。如果事件配置为raw=True，那么这将是与实例关联的InstanceState状态管理对象。
  
• args – 传递给__init__方法的位置参数。
  
• kwargs – 传递给__init__方法的关键字参数。
  

另请参见

InstanceEvents.init()

InstanceEvents.load()

method load(target: _O, context: QueryContext) → None

在通过__new__创建对象实例并进行初始属性填充后接收对象实例。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass, 'load')
def receive_load(target, context):
    "listen for the 'load' event"
    # ... (event handling logic) ...

这通常发生在基于传入结果行创建实例时，并且仅在该实例的生命周期中调用一次。

警告

在结果行加载期间，当处理此实例接收到的第一行时，将调用此事件。当使用集合导向属性进行急加载时，尚未发生要加载/处理的附加行，以便加载后续集合项。这既导致集合不会完全加载，也导致如果在此事件处理程序中发生操作，该操作会为对象发出另一个数据库加载操作，则对象的“加载上下文”可能会发生变化并干扰现有的急加载器仍在进行中。

可能导致事件处理程序内“加载上下文”更改的示例包括但不限于：

• 访问未包含在行中的延迟属性将触发“取消延迟”操作并刷新对象
  
• 访问联合继承子类上不属于行的属性将触发刷新操作。
  

从 SQLAlchemy 1.3.14 开始，当发生此情况时会发出警告。可以在事件上使用InstanceEvents.restore_load_context选项来防止此警告；这将确保在调用事件后保持对象的现有加载上下文：

@event.listens_for(
    SomeClass, "load", restore_load_context=True)
def on_load(instance, context):
    instance.some_unloaded_attribute

从版本 1.3.14 开始更改：添加了InstanceEvents.restore_load_context和SessionEvents.restore_load_context标志，适用于“加载”事件，确保在事件钩子完成时恢复对象的加载上下文；如果对象的加载上下文在未设置此标志的情况下发生更改，则会发出警告。

InstanceEvents.load() 事件也可以以类方法装饰器的形式使用，称为reconstructor()。

参数：

• target – 映射实例。如果事件配置为raw=True，则这将是与实例关联的InstanceState状态管理对象。
  
• context – 与当前进行中的Query对应的QueryContext。如果加载不对应于Query，例如在Session.merge()期间，此参数可能为None���
  

另请参阅

在加载过程中保持非映射状态

InstanceEvents.init()

InstanceEvents.refresh()

SessionEvents.loaded_as_persistent()

method pickle(target: _O, state_dict: _InstanceDict) → None

在关联状态被 pickle 时接收一个对象实例。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass, 'pickle')
def receive_pickle(target, state_dict):
    "listen for the 'pickle' event"
    # ... (event handling logic) ...

参数：

• target – 映射实例。如果事件配置为raw=True，则这将是与实例关联的InstanceState状态管理对象。
  
• state_dict – 由__getstate__返回的包含要 pickle 的状态的字典。
  

method refresh(target: _O, context: QueryContext, attrs: Iterable[str] | None) → None

在从查询中刷新一个或多个属性后接收一个对象实例。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass, 'refresh')
def receive_refresh(target, context, attrs):
    "listen for the 'refresh' event"
    # ... (event handling logic) ...

与InstanceEvents.load()方法形成对比，该方法在对象首次从查询中加载时被调用。

注意

在加载程序完成之前，此事件在加载程序进程中被调用，对象的状态可能不完整。此外，在对象上调用行级刷新操作将使对象进入新的加载程序上下文，干扰现有的加载上下文。有关如何使用InstanceEvents.restore_load_context参数解决此情况的背景，请参阅有关InstanceEvents.load()的注释。

参数：

• target – 映射实例。如果事件配置为raw=True，则这将是与实例关联的InstanceState状态管理对象。
  
• context – 与当前进行中的Query对应的QueryContext。
  
• attrs – 已填充的属性名称序列，如果所有列映射的非延迟属性都已填充，则为 None。
  

另请参阅

在加载时保持未映射状态

InstanceEvents.load()

method refresh_flush(target: _O, flush_context: UOWTransaction, attrs: Iterable[str] | None) → None

在对象状态持久化期间，接收一个包含一个或多个包含列级默认值或更新处理程序的属性已被刷新的对象实例。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass, 'refresh_flush')
def receive_refresh_flush(target, flush_context, attrs):
    "listen for the 'refresh_flush' event"
    # ... (event handling logic) ...

这个事件与 InstanceEvents.refresh() 相同，只是在工作单元刷新过程中调用，并且仅包括具有列级默认值或更新处理程序的非主键列，包括 Python 可调用对象以及可能通过 RETURNING 子句获取的服务器端默认值和触发器。

注意

当 InstanceEvents.refresh_flush() 事件触发时，对于一个被插入的对象以及一个被更新的对象，该事件主要针对更新过程；这主要是一个内部工件，指出插入动作也可以触发此事件，注意插入行的主键列在此事件中被明确省略。为了拦截对象的新插入状态，SessionEvents.pending_to_persistent() 和 MapperEvents.after_insert() 是更好的选择。

参数：

• target – 映射实例。如果事件配置为 raw=True，则此处将是与实例关联的 InstanceState 状态管理对象。
  
• flush_context – 处理刷新细节的内部 UOWTransaction 对象。
  
• attrs – 已填充的属性名称序列。
  

另请参阅

在加载时保持未映射状态

获取服务器生成的默认值

列插入/更新默认值

method unpickle(target: _O, state_dict: _InstanceDict) → None

在相关联的状态被反序列化后，接收一个对象实例。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass, 'unpickle')
def receive_unpickle(target, state_dict):
    "listen for the 'unpickle' event"
    # ... (event handling logic) ...

参数：

• target – 映射实例。如果事件配置为 raw=True，则此处将是与实例关联的 InstanceState 状态管理对象。
  
• state_dict – 发送到 __setstate__ 的字典，包含被序列化的状态字典。
  

属性事件

属性事件在 ORM 映射对象的各个属性发生时触发。这些事件为诸如自定义验证函数和反向引用处理程序等功能奠定了基础。

另请参阅

更改属性行为

class sqlalchemy.orm.AttributeEvents

定义对象属性的事件。

这些通常在目标类的类绑定描述符上定义。

例如，要注册一个将接收AttributeEvents.append()事件的监听器：

from sqlalchemy import event
@event.listens_for(MyClass.collection, 'append', propagate=True)
def my_append_listener(target, value, initiator):
    print("received append event for target: %s" % target)

当AttributeEvents.retval标志传递给listen()或listens_for()时，监听器可以选择返回可能修改的值，如下所示，使用AttributeEvents.set()事件进行说明：

def validate_phone(target, value, oldvalue, initiator):
    "Strip non-numeric characters from a phone number"
    return re.sub(r'\D', '', value)
# setup listener on UserContact.phone attribute, instructing
# it to use the return value
listen(UserContact.phone, 'set', validate_phone, retval=True)

像上面的验证函数也可以引发异常，如ValueError以停止操作。

当应用监听器到具有映射子类的映射类时，AttributeEvents.propagate标志也很重要，例如在使用映射器继承模式时：

@event.listens_for(MySuperClass.attr, 'set', propagate=True)
def receive_set(target, value, initiator):
    print("value set: %s" % target)

下面是可用于listen()和listens_for()函数的修饰符的完整列表。

参数：

• active_history=False – 当为 True 时，表示“set”事件希望无条件地接收被替换的“旧”值，即使这需要触发数据库加载。请注意，active_history也可以通过column_property()和relationship()直接设置。
  
• propagate=False – 当为 True 时，监听器函数将不仅为给定的类属性建立，还将为该类的所有当前子类以及该类的所有未来子类上具有相同名称的属性建立，使用一个额外的监听器来监听仪器事件。
  
• raw=False – 当为 True 时，事件的“target”参数将是InstanceState管理对象，而不是映射实例本身。
  
• retval=False – 当为 True 时，用户定义的事件监听必须从函数中返回“value”参数。这使得监听函数有机会更改最终用于“set”或“append”事件的值。
  

成员

append(), append_wo_mutation(), bulk_replace(), dispatch,  dispose_collection(), init_collection(), init_scalar(), modified(),  remove(), set()

类签名

类 sqlalchemy.orm.AttributeEvents (sqlalchemy.event.Events)

method append(target: _O, value: _T, initiator: Event, *, key: EventConstants = EventConstants.NO_KEY) → _T | None

接收集合附加事件。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass.some_attribute, 'append')
def receive_append(target, value, initiator):
    "listen for the 'append' event"
    # ... (event handling logic) ...

在每个元素被附加到集合时，都会调用附加事件。这适用于单个项的附加以及“批量替换”操作。

参数:

• target – 接收事件的对象实例。如果监听器以 raw=True 注册，这将是 InstanceState 对象。
  
• value – 被附加的值。如果此监听器以 retval=True 注册，则监听函数必须返回此值，或者替换它的新值。
  
• initiator – 表示事件启动的 Event 实例。可能会被后向引用处理程序修改以控制链接的事件传播，以及被检查以获取有关事件源的信息。
  
• key –
  当使用 AttributeEvents.include_key 参数设置为 True 来建立事件时，这将是操作中使用的键，例如 collection[some_key_or_index] = value。如果未使用 AttributeEvents.include_key 设置事件，将根本不传递此参数给事件；这是为了允许与不包括 key 参数的现有事件处理程序向后兼容。
  版本 2.0 中的新功能。
  

返回:

如果事件以 retval=True 注册，则应返回给定值或新的有效值。

另请参阅

AttributeEvents - 关于监听器选项的背景信息，例如传播到子类。

AttributeEvents.bulk_replace()

method append_wo_mutation(target: _O, value: _T, initiator: Event, *, key: EventConstants = EventConstants.NO_KEY) → None

接收集合附加事件，其中集合实际上未被改变。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass.some_attribute, 'append_wo_mutation')
def receive_append_wo_mutation(target, value, initiator):
    "listen for the 'append_wo_mutation' event"
    # ... (event handling logic) ...

此事件与 AttributeEvents.append() 不同，因为它是为去重集合（如集合和字典）触发的，当对象已存在于目标集合中时。该事件没有返回值，并且给定对象的标识不能更改。

当集合已通过后向引用事件发生变异时，该事件用于将对象级联到Session中。

参数：

• target – 接收事件的对象实例。如果侦听器以 raw=True 注册，这将是 InstanceState 对象。
  
• value – 如果对象在集合中尚不存在，则将追加的值。
  
• initiator – 一个表示事件启动的Event实例。可以通过后向引用处理程序修改其原始值，以控制链接的事件传播，也可以检查有关事件源的信息。
  
• key –
  当使用 AttributeEvents.include_key 参数设置为 True 建立事件时，这将是操作中使用的键，例如 collection[some_key_or_index] = value。如果未使用 AttributeEvents.include_key 设置事件，根本不会将参数传递给事件；这是为了与不包含 key 参数的现有事件处理程序向后兼容。
  在版本 2.0 中新增。
  

返回：

没有为此事件定义返回值。

在版本 1.4.15 中新增。

method bulk_replace(target: _O, values: Iterable[_T], initiator: Event, *, keys: Iterable[EventConstants] | None = None) → Non

接收一个集合“批量替换”事件。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass.some_attribute, 'bulk_replace')
def receive_bulk_replace(target, values, initiator):
    "listen for the 'bulk_replace' event"
    # ... (event handling logic) ...

此事件在作为 ORM 对象处理之前的批量集合设置操作的传入值序列上被调用，可以在值被视为 ORM 对象之前就地修改。这是一个“早期挂钩”，在批量替换例程尝试协调哪些对象已经存在于集合中，哪些对象正在被净替换操作移除之前运行。

通常情况下，此方法与AttributeEvents.append()事件的使用结合。当同时使用这两个事件时，请注意，批量替换操作将为所有新项目调用AttributeEvents.append()事件，即使在为整个集合调用AttributeEvents.bulk_replace()之后，也会调用AttributeEvents.append()事件。为了确定AttributeEvents.append()事件是否属于批量替换，请使用符号attributes.OP_BULK_REPLACE来测试传入的 initiator：

from sqlalchemy.orm.attributes import OP_BULK_REPLACE
@event.listens_for(SomeObject.collection, "bulk_replace")
def process_collection(target, values, initiator):
    values[:] = [_make_value(value) for value in values]
@event.listens_for(SomeObject.collection, "append", retval=True)
def process_collection(target, value, initiator):
    # make sure bulk_replace didn't already do it
    if initiator is None or initiator.op is not OP_BULK_REPLACE:
        return _make_value(value)
    else:
        return value

版本 1.2 中的新内容。

参数：

• target – 接收事件的对象实例。如果监听器注册为raw=True，这将是InstanceState对象。
  
• value – 正在设置的值的序列（例如列表）。处理程序可以直接修改此列表。
  
• initiator – 代表事件启动的Event实例。
  
• keys –
  当使用AttributeEvents.include_key参数设置为 True 来建立事件时，这将是操作中使用的键序列，通常仅用于字典更新。如果未使用AttributeEvents.include_key来设置事件，则根本不会将参数传递给事件；这是为了允许与不包括key参数的现有事件处理程序保持向后兼容性。
  版本 2.0 中的新内容。
  

另请参阅

AttributeEvents - 关于监听器选项的背景，例如传播到子类。

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

参考回 _Dispatch 类。

双向反对 _Dispatch._events

method dispose_collection(target: _O, collection: Collection[Any], collection_adapter: CollectionAdapter) → None

收到一个“collection dispose”事件。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass.some_attribute, 'dispose_collection')
def receive_dispose_collection(target, collection, collection_adapter):
    "listen for the 'dispose_collection' event"
    # ... (event handling logic) ...

当集合被替换时，此事件将触发基于集合的属性，即：

u1.addresses.append(a1)
u1.addresses = [a2, a3]  # <- old collection is disposed

旧集合将包含其先前的内容。

版本 1.2 中的更改：传递给AttributeEvents.dispose_collection()的集合现在将在处理之前保持其内容；以前，集合将为空。

另请参阅

AttributeEvents - 关于监听器选项的背景，例如传播到子类。

method init_collection(target: _O, collection: Type[Collection[Any]], collection_adapter: CollectionAdapter) → None

收到一个“collection init”事件。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass.some_attribute, 'init_collection')
def receive_init_collection(target, collection, collection_adapter):
    "listen for the 'init_collection' event"
    # ... (event handling logic) ...

当为空属性首次生成初始“空集合”时，以及当集合被替换为新集合时（例如通过设置事件），将触发此事件。

例如，假设User.addresses是基于关系的集合，事件在此处触发：

u1 = User()
u1.addresses.append(a1)  #  <- new collection

在替换操作期间也会发生：

u1.addresses = [a2, a3]  #  <- new collection

参数：

• target – 接收事件的对象实例。如果监听器以raw=True注册，这将是InstanceState对象。
  
• collection – 新集合。这将始终从relationship.collection_class指定的内容生成，并且始终为空。
  
• collection_adapter – 将调解对集合的内部访问的CollectionAdapter。
  

另请参阅

AttributeEvents - 关于监听器选项的背景，例如传播到子类。

AttributeEvents.init_scalar() - 此事件的“标量”版本。

method init_scalar(target: _O, value: _T, dict_: Dict[Any, Any]) → None

接收一个标量“init”事件。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass.some_attribute, 'init_scalar')
def receive_init_scalar(target, value, dict_):
    "listen for the 'init_scalar' event"
    # ... (event handling logic) ...

当访问未初始化的、未持久化的标量属性时，例如读取时，将调用此事件：

x = my_object.some_attribute

当未初始化属性发生此事件时，ORM 的默认行为是返回值None；请注意，这与 Python 通常引发AttributeError的行为不同。此处的事件可用于自定义实际返回的值，假设事件监听器将镜像配置在 Core Column对象上的默认生成器。

由于Column上的默认生成器也可能产生像时间戳这样的变化值，因此AttributeEvents.init_scalar()事件处理程序也可用于设置新返回的值，以便 Core 级别的默认生成函数实际上只触发一次，但在访问非持久化对象上的属性时。通常，当访问未初始化属性时，不会对对象的状态进行任何更改（在较旧的 SQLAlchemy 版本中实际上会更改对象的状态）。

如果列上的默认生成器返回特定常量，则可以使用处理程序如下：

SOME_CONSTANT = 3.1415926
class MyClass(Base):
    # ...
    some_attribute = Column(Numeric, default=SOME_CONSTANT)
@event.listens_for(
    MyClass.some_attribute, "init_scalar",
    retval=True, propagate=True)
def _init_some_attribute(target, dict_, value):
    dict_['some_attribute'] = SOME_CONSTANT
    return SOME_CONSTANT

在上面的示例中，我们将属性MyClass.some_attribute初始化为SOME_CONSTANT的值。上述代码包括以下特性：

• 通过在给定的dict_中设置值SOME_CONSTANT，我们表明这个值将被持久化到数据库中。这取代了在Column的默认生成器中使用SOME_CONSTANT的方法。在属性仪器化中给出的active_column_defaults.py示例演示了对于变化的默认值使用相同方法的情况，例如时间戳生成器。在这个特定的例子中，这样做并不是严格必要的，因为无论如何SOME_CONSTANT都会成为 INSERT 语句的一部分。
  
• 通过建立retval=True标志，我们从函数返回的值将被属性获取器返回。如果没有这个标志，事件被认为是被动观察者，我们函数的返回值将被忽略。
  
• 如果映射类包括继承的子类，则propagate=True标志是重要的，这些子类也将使用此事件监听器。如果没有这个标志，继承的子类将不使用我们的事件处理程序。
  

在上面的例子中，当我们将我们的值应用到给定的dict_时，属性设置事件AttributeEvents.set()以及由validates提供的相关验证功能都不会被调用。要使这些事件响应我们新生成的值，将该值应用到给定对象作为正常的属性设置操作：

SOME_CONSTANT = 3.1415926
@event.listens_for(
    MyClass.some_attribute, "init_scalar",
    retval=True, propagate=True)
def _init_some_attribute(target, dict_, value):
    # will also fire off attribute set events
    target.some_attribute = SOME_CONSTANT
    return SOME_CONSTANT

当设置了多个监听器时，值的生成会从一个监听器“链式”传递到下一个监听器，通过将前一个指定retval=True的监听器返回的值作为下一个监听器的value参数传递。

参数：

• target – 接收事件的对象实例。如果监听器注册为raw=True，这将是InstanceState对象。
  
• value – 在此事件监听器被调用之前要返回的值。这个值最初为None，但是如果存在多个监听器，则将是上一个事件处理程序函数的返回值。
  
• dict_ – 此映射对象的属性字典。这通常是对象的__dict__，但在所有情况下都表示属性系统用于访问此属性的实际值的目标。将值放入该字典中的效果是该值将在工作单元生成的 INSERT 语句中使用。
  

另请参阅

AttributeEvents.init_collection() - 此事件的集合版本

AttributeEvents - 关于监听器选项的背景信息，如传播到子类。

属性仪表化 - 参见 active_column_defaults.py 示例。

method modified(target: _O, initiator: Event) → None

接收一个‘修改’事件。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass.some_attribute, 'modified')
def receive_modified(target, initiator):
    "listen for the 'modified' event"
    # ... (event handling logic) ...

当使用 flag_modified() 函数在未设置任何特定值的情况下触发修改事件时，将触发此事件。

1.2 版中的新内容。

参数：

• target – 接收事件的对象实例。如果监听器使用 raw=True 注册，这将是 InstanceState 对象。
  
• initiator – 一个代表事件启动的 Event 实例。
  

另请参阅

AttributeEvents - 关于监听器选项的背景，例如传播到子类。

method remove(target: _O, value: _T, initiator: Event, *, key: EventConstants = EventConstants.NO_KEY) → None

接收一个集合移除事件。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass.some_attribute, 'remove')
def receive_remove(target, value, initiator):
    "listen for the 'remove' event"
    # ... (event handling logic) ...

参数：

• target – 接收事件的对象实例。如果监听器使用 raw=True 注册，这将是 InstanceState 对象。
  
• value – 被移除的值。
  
• initiator – 一个代表事件启动的 Event 实例。可以通过 backref 处理程序修改其原始值，以控制链式事件传播。
  
• key –
  当使用 AttributeEvents.include_key 参数设置为 True 建立事件时，这将是操作中使用的键，例如 del collection[some_key_or_index]。如果未使用 AttributeEvents.include_key 设置事件，参数根本不会传递给事件；这是为了允许现有事件处理程序与不包含 key 参数的事件处理程序向后兼容。
  2.0 版中的新内容。
  

返回：

未为此事件定义返回值。

另请参阅

AttributeEvents - 关于监听器选项的背景，例如传播到子类。

method set(target: _O, value: _T, oldvalue: _T, initiator: Event) → None

接收一个标量集合事件。

示例参数形式：

from sqlalchemy import event
@event.listens_for(SomeClass.some_attribute, 'set')
def receive_set(target, value, oldvalue, initiator):
    "listen for the 'set' event"
    # ... (event handling logic) ...

参数：

• target – 接收事件的对象实例。如果监听器使用 raw=True 注册，这将是 InstanceState 对象。
  
• value – 被设置的值。如果此监听器使用 retval=True 注册，监听器函数必须返回此值，或替换它的新值。
  
• oldvalue – 被替换的先前值。这也可以是符号 NEVER_SET 或 NO_VALUE。如果监听器使用 active_history=True 注册，当现有值当前未加载或过期时，将从数据库加载属性的先前值。
  
• initiator – 代表事件启动的Event实例。可能会被 backref 处理程序从其原始值修改，以控制链式事件传播。
  

返回：

如果事件是以retval=True注册的，则应返回给定值或新的有效值。

另请参见

AttributeEvents - 关于侦听器选项的背景，例如传播到子类。

SqlAlchemy 2.0 中文文档（二十六）（3）https://developer.aliyun.com/article/1560474