版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

不推荐使用的ORM事件接口

本节描述了最初存在于SQLAlchemy 0.1中的基于类的ORM事件接口,该事件接口在SQLAlchemy 0.5之前进行了多种事件。非ORM模拟描述于Deprecated Event Interfaces

从版本0.7开始弃用:从SQLAlchemy 0.7开始,Events中描述的新事件系统取代了扩展/ proxy / listener系统,为所有不需要的事件提供一致的接口用于子类。

Mapper事件

class sqlalchemy.orm.interfaces。 MapperExtension

Mapper事件挂钩的基本实现。

注意

MapperExtension is deprecated. 请参阅event.listen()以及MapperEvents

新的扩展类子类MapperExtension,并且使用extension mapper()参数指定,该参数是一个MapperExtension

from sqlalchemy.orm.interfaces import MapperExtension

class MyExtension(MapperExtension):
    def before_insert(self, mapper, connection, instance):
        print "instance %s before insert !" % instance

m = mapper(User, users_table, extension=MyExtension())

一个映射器可以维护MapperExtension对象链。When a particular mapping event occurs, the corresponding method on each MapperExtension is invoked serially, and each method has the ability to halt the chain from proceeding further:

m = mapper(User, users_table, extension=[ext1, ext2, ext3])

每个MapperExtension方法默认返回符号EXT_CONTINUE。这个符号通常意味着“移动到下一个MapperExtension进行处理”。对于返回像翻译行或新对象实例的对象的方法,EXT_CONTINUE表示方法的结果应该被忽略。在某些情况下,需要执行默认的映射器活动,例如将新的实例添加到结果列表中。

符号EXT_STOP在MapperExtension对象链中有意义,当返回这个符号时链将被停止。像EXT_CONTINUE一样,在某些情况下,默认的映射器活动也不会被执行。

after_delete(mapper, connection, instance)

在该实例被删除后接收对象实例。

返回值仅在MapperExtension链中有效;父映射器的行为不会被此方法修改。

after_insert(mapper, connection, instance)

在插入实例后接收对象实例。

返回值仅在MapperExtension链中有效;父映射器的行为不会被此方法修改。

after_update(mapper, connection, instance)

在实例更新后接收对象实例。

返回值仅在MapperExtension链中有效;父映射器的行为不会被此方法修改。

before_delete(mapper, connection, instance)

在该实例被删除之前接收一个对象实例。

请注意,在这里可以修改整个刷新计划的no并且对Session的操作不会产生预期的效果。要操作扩展中的Session,请使用SessionExtension

返回值仅在MapperExtension链中有效;父映射器的行为不会被此方法修改。

before_insert(mapper, connection, instance)

在该实例插入到其表中之前接收一个对象实例。

这是设置主键值的一个好地方,而不是以其他方式处理。

在这个方法中可以修改基于列的属性,这将导致插入新的值。然而,no可能会改变整体刷新计划,Session的操作将不会产生预期的效果。要操作扩展中的Session,请使用SessionExtension

返回值仅在MapperExtension链中有效;父映射器的行为不会被此方法修改。

before_update(mapper, connection, instance)

在更新实例之前接收对象实例。

请注意,为所有标记为“脏”的实例调用此方法,即使那些对其基于列的属性没有净更改的实例也会调用此方法。当一个对象的任何基于列的属性有一个被调用的“set attribute”操作,或者当它的任何一个集合被修改时,这个对象被标记为脏。如果在更新时没有基于列的属性有任何净更改,则不会发布UPDATE语句。这意味着发送到before_update的实例不是保证UPDATE语句将被发出(尽管你可以在这里影响结果)。

要检测对象上的基于列的属性是否有净更改,并因此将生成UPDATE语句,请使用object_session(instance).is_modified(instance, include_collections = False) T2> T0>。

在这个方法中可以修改基于列的属性,这将导致新的值被更新。然而,no可能会改变整体刷新计划,Session的操作将不会产生预期的效果。要操作扩展中的Session,请使用SessionExtension

返回值仅在MapperExtension链中有效;父映射器的行为不会被此方法修改。

init_failed(mapper, class_, oldinit, instance, args, kwargs)

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

这个方法只在一个对象的用户区构造中被调用。从数据库加载对象时不调用它。

返回值仅在MapperExtension链中有效;父映射器的行为不会被此方法修改。

init_instance(mapper, class_, oldinit, instance, args, kwargs)

当它的构造函数被调用时接收一个实例。

这个方法只在一个对象的用户区构造中被调用。从数据库加载对象时不调用它。

返回值仅在MapperExtension链中有效;父映射器的行为不会被此方法修改。

instrument_class(mapper, class_)

当映射器第一次构建时接收一个类,并将映射应用到映射类。

返回值仅在MapperExtension链中有效;父映射器的行为不会被此方法修改。

reconstruct_instance(mapper, instance)

通过__new__创建对象实例后,在初始属性填充发生后接收对象实例。

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

请注意,在结果行加载期间,将在为此实例接收的第一行调用此方法。请注意,根据结果行中的内容,某些属性和集合可能被加载,甚至可能不被加载或甚至被初始化。

返回值仅在MapperExtension链中有效;父映射器的行为不会被此方法修改。

会话事件

class sqlalchemy.orm.interfaces。 SessionExtension

Session事件挂钩的基本实现。

注意

SessionExtension is deprecated. 请参阅event.listen()以及SessionEvents

子类可以使用extension关键字参数安装到Session(或sessionmaker)中:

from sqlalchemy.orm.interfaces import SessionExtension

class MySessionExtension(SessionExtension):
    def before_commit(self, session):
        print "before commit!"

Session = sessionmaker(extension=MySessionExtension())

同一个SessionExtension实例可以用于任意数量的会话。

after_attach sessioninstance

在实例附加到会话后执行。

这是在添加,删除或合并之后调用的。

after_begin(session, transaction, connection)

在连接开始事务后执行

transaction is the SessionTransaction. 在连接上启动引擎级事务之后调用此方法。

after_bulk_delete sessionqueryquery_contextresult t5 > ) T6> ¶ T7>

对会话进行批量删除操作后执行。

这是在session.query(...)。delete()之后调用的。

query is the query object that this delete operation was called on. query_context was the query context object. result is the result object returned from the bulk operation.

after_bulk_update sessionqueryquery_contextresult t5 > ) T6> ¶ T7>

对会话执行批量更新操作后执行。

这是在session.query(...)。update()之后调用的。

query is the query object that this update operation was called on. query_context was the query context object. result is the result object returned from the bulk operation.

after_commit T0> ( T1> 会话 T2> ) T3> ¶ T4>

提交发生后执行。

请注意,如果长时间运行的事务正在进行,这可能不是每次刷新。

after_flush sessionflush_context

刷新完成后执行,但在调用之前执行。

请注意,会话状态仍处于预先刷新状态,即“新建”,“脏”和“已删除”列表仍显示预刷新状态以及实例属性的历史记录设置。

after_flush_postexec sessionflush_context

刷新完成后,执行后状态发生后执行。

这将是当“新”,“脏”和“删除”列表处于最终状态时。一个实际的提交()可能会或可能不会发生,取决于flush是否开始自己的事务或参与一个更大的事务。

after_rollback T0> ( T1> 会话 T2> ) T3> ¶ T4>

在发生回滚之后执行。

请注意,如果长时间运行的事务正在进行,这可能不是每次刷新。

before_commit T0> ( T1> 会话 T2> ) T3> ¶ T4>

在调用commit之前执行。

请注意,如果长时间运行的事务正在进行,这可能不是每次刷新。

before_flush(session, flush_context, instances)

在刷新过程开始之前执行。

实例是传递给flush()方法的对象的可选列表。

属性事件

class sqlalchemy.orm.interfaces。 AttributeExtension

AttributeImpl事件挂钩的基本实现,在用户代码中触发属性突变的事件。

注意

AttributeExtension已弃用。请参阅event.listen()以及AttributeEvents

AttributeExtension用于侦听设置,删除和追加单个映射属性上的事件。它使用column_property()relationship()和其他的扩展参数在单独映射的属性上建立:

from sqlalchemy.orm.interfaces import AttributeExtension
from sqlalchemy.orm import mapper, relationship, column_property

class MyAttrExt(AttributeExtension):
    def append(self, state, value, initiator):
        print "append event !"
        return value

    def set(self, state, value, oldvalue, initiator):
        print "set event !"
        return value

mapper(SomeClass, sometable, properties={
    'foo':column_property(sometable.c.foo, extension=MyAttrExt()),
    'bar':relationship(Bar, extension=MyAttrExt())
})

请注意,AttributeExtension方法append()set()需要返回value参数。返回的值用作有效值,并允许扩展更改最终保留的内容。

AttributeExtension在与映射类关联的描述符中组装。

active_history = True

表明set()方法希望收到“老”的值,即使这意味着发射懒惰可调用。

请注意,active_history也可以直接通过column_property()relationship()来设置。

append(state, value, initiator)

接收收藏追加事件。

返回的值将被用作要追加的实际值。

remove(state, value, initiator)

接收删除事件。

没有定义返回值。

set(state, value, oldvalue, initiator)

收到一个设定的事件。

返回的值将被用作要设置的实际值。