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

SQLAlchemy 1.1文档

ORM事件

ORM包含各种可用于订阅的钩子。

有关最常用的ORM事件的介绍,请参见Tracking Object and Session Changes with Events部分。一般的事件系统在Events讨论。Non-ORM events such as those regarding connections and low-level statement execution are described in Core Events.

属性事件

class sqlalchemy.orm.events。 AttributeEvents

基础:sqlalchemy.event.base.Events

定义对象属性的事件。

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

例如。:

from sqlalchemy import event

def my_append_listener(target, value, initiator):
    print "received append event for target: %s" % target

event.listen(MyClass.collection, 'append', my_append_listener)

retval=True标志被传递给listen()时,监听器可以选择返回值的可能修改版本。

def validate_phone(target, value, oldvalue, initiator):
    "Strip non-numeric characters from a phone number"

    return re.sub(r'(?![0-9])', '', value)

# setup listener on UserContact.phone attribute, instructing
# it to use the return value
listen(UserContact.phone, 'set', validate_phone, retval=True)

类似上面的验证函数也会引发一个异常,如ValueError来暂停操作。

listen()函数有几个修饰符可用。

参数:
  • active_history=False – When True, indicates that the “set” event would like to receive the “old” value being replaced unconditionally, even if this requires firing off database loads. 请注意,active_history也可以直接通过column_property()relationship()来设置。
  • propagate=False – When True, the listener function will be established not just for the class attribute given, but for attributes of the same name on all current subclasses of that class, as well as all future subclasses of that class, using an additional listener that listens for instrumentation events.
  • raw=False – When True, the “target” argument to the event will be the InstanceState management object, rather than the mapped instance itself.
  • retval=False – when True, the user-defined event listening must return the “value” argument from the function. 这使得监听功能有机会改变最终用于“设置”或“追加”事件的值。
append(target, value, initiator)

接收收藏追加事件。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass.some_attribute, 'append')
def receive_append(target, value, initiator):
    "listen for the 'append' event"

    # ... (event handling logic) ...
参数:
  • 目标 - 接收事件的对象实例。如果侦听器注册了raw=True,这将是InstanceState对象。
  • value – the value being appended. 如果此侦听器使用retval=True进行注册,那么侦听器函数必须返回该值或替换它的新值。
  • 发起人 -

    表示事件启动的attributes.Event实例。可以通过backref处理程序从其原始值进行修改,以控制链式事件传播。

    在0.9.0版本中改变: initiator参数现在作为attributes.Event对象传递,并且可以由反向链接事件链。

返回:

如果事件使用retval=True进行注册,则应返回给定值或新的有效值。

dispose_collection(target, collection, collection_adpater)

收到“收集处理”事件。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass.some_attribute, 'dispose_collection')
def receive_dispose_collection(target, collection, collection_adpater):
    "listen for the 'dispose_collection' event"

    # ... (event handling logic) ...

当一个集合被替换时,这个事件被触发为一个基于集合的属性,即:

u1.addresses.append(a1)

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

事件的机制通常包括给定的集合是空的,即使在被替换时存储对象。

版本1.0.0新增: AttributeEvents.init_collection()AttributeEvents.dispose_collection()事件取代collection.linker

init_collection(target, collection, collection_adapter)

接收“集合初始化”事件。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@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
参数:

版本1.0.0新增: AttributeEvents.init_collection()AttributeEvents.dispose_collection()事件取代collection.linker

init_scalar(target, value, dict_)

接收标量“init”事件。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass.some_attribute, 'init_scalar')
def receive_init_scalar(target, value, dict_):
    "listen for the 'init_scalar' event"

    # ... (event handling logic) ...

当访问未初始化的未加标量的标量属性时,将调用此事件。在这种情况下通常会返回None的值;对象的状态没有改变。

事件处理程序可以通过两种方式来改变这种行为。一个是可以返回None以外的值。另一个是可以将该值作为对象状态的一部分来建立,这也将具有持续的效果。

典型的用途是在访问时建立属性的一个特定的默认值:

SOME_CONSTANT = 3.1415926

@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,我们指示该值将被持久化到数据库。如果我们明确地将它与对象关联起来,给定的值只能保存到数据库中。假定默认的属性检测系统就位,给出的dict_是映射对象的__dict__元素。
  • 通过建立retval=True标志,我们从函数返回的值将由属性getter返回。没有这个标志,事件被认为是一个被动的观察者,我们的函数的返回值被忽略。
  • 如果映射的类包含继承子类,那么propagate=True标志是有意义的,这也会利用这个事件监听器。没有这个标志,继承的子类将不会使用我们的事件处理程序。

当我们在给定字典中建立值时,该值将被用在由工作单元建立的INSERT语句中。通常情况下,None的默认返回值不是作为对象的一部分建立的,以避免响应正常被动的“get”操作而发生的对象突变问题,也避免了这个问题是否在属性访问操作期间,AttributeEvents.set()事件是否应该被不正当地触发。这不会影响INSERT操作,因为None的值与NULL的值无论如何都会进入数据库;请注意,在INSERT期间会跳过None,以确保列和SQL级别的默认功能可以触发。

当我们应用我们的值时,属性设置事件AttributeEvents.set()以及由orm.validates提供的相关验证功能到给定的dict_要使这些事件响应我们新生成的值而调用,请将该值作为普通属性设置操作应用于给定对象:

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

可以使用AttributeEvents.init_scalar()事件从映射的Column对象上建立的默认值和/或可调参数中提取值。查看Attribute Instrumentation中的“active column defaults”示例。

版本1.1中的新功能

参数:
  • 目标 - 接收事件的对象实例。如果侦听器注册了raw=True,这将是InstanceState对象。
  • value – the value that is to be returned before this event listener were invoked. 该值以None值开始,但如果存在多个侦听器,则该值将是前一个事件处理函数的返回值。
  • dict _ - 此映射对象的属性字典。这通常是对象的__dict__,但在任何情况下都代表属性系统用来获取此属性实际值的目标。在此字典中放置值会影响该值将在由工作单元生成的INSERT语句中使用。

也可以看看

Attribute Instrumentation - 请参阅active_column_defaults.py示例。

remove(target, value, initiator)

接收收集移除事件。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass.some_attribute, 'remove')
def receive_remove(target, value, initiator):
    "listen for the 'remove' event"

    # ... (event handling logic) ...
参数:
  • 目标 - 接收事件的对象实例。如果侦听器注册了raw=True,这将是InstanceState对象。
  • - 被删除的值。
  • 发起人 -

    表示事件启动的attributes.Event实例。可以通过backref处理程序从其原始值进行修改,以控制链式事件传播。

    在0.9.0版本中改变: initiator参数现在作为attributes.Event对象传递,并且可以由反向链接事件链。

返回:

没有为这个事件定义返回值。

set(target, value, oldvalue, initiator)

接收标量设置事件。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass.some_attribute, 'set')
def receive_set(target, value, oldvalue, initiator):
    "listen for the 'set' event"

    # ... (event handling logic) ...

# named argument style (new in 0.9)
@event.listens_for(SomeClass.some_attribute, 'set', named=True)
def receive_set(**kw):
    "listen for the 'set' event"
    target = kw['target']
    value = kw['value']

    # ... (event handling logic) ...
参数:
  • 目标 - 接收事件的对象实例。如果侦听器注册了raw=True,这将是InstanceState对象。
  • - 正在设置的值。如果此侦听器使用retval=True进行注册,那么侦听器函数必须返回该值或替换它的新值。
  • oldvalue - 之前的值被替换。这也可以是NEVER_SETNO_VALUE的符号。如果侦听器注册了active_history=True,那么如果当前的值已经被卸载或过期,那么属性的前一个值将从数据库加载。
  • 发起人 -

    表示事件启动的attributes.Event实例。可以通过backref处理程序从其原始值进行修改,以控制链式事件传播。

    在0.9.0版本中改变: initiator参数现在作为attributes.Event对象传递,并且可以由反向链接事件链。

返回:

如果事件使用retval=True进行注册,则应返回给定值或新的有效值。

Mapper事件

class sqlalchemy.orm.events。 MapperEvents

基础:sqlalchemy.event.base.Events

定义特定于映射的事件。

例如。:

from sqlalchemy import event

def my_before_insert_listener(mapper, connection, target):
    # execute a stored procedure upon INSERT,
    # apply the value to the row to be inserted
    target.calculated_value = connection.scalar(
                                "select my_special_function(%d)"
                                % target.special_number)

# associate the listener function with SomeClass,
# to execute during the "before_insert" hook
event.listen(
    SomeClass, 'before_insert', my_before_insert_listener)

可用目标包括:

  • 映射类
  • 未映射的映射或待映射类的超类(使用propagate=True标志)
  • Mapper对象
  • Mapper类本身和mapper()函数指示侦听所有映射器。

版本0.8.0更改:映​​射器事件可以与映射类的未映射超类相关联。

Mapper事件提供了映射器关键部分的钩子,包括与对象检测,对象加载和对象持久性有关的部分。In particular, the persistence methods before_insert(), and before_update() are popular places to augment the state being persisted - however, these methods operate with several significant restrictions. The user is encouraged to evaluate the SessionEvents.before_flush() and SessionEvents.after_flush() methods as more flexible and user-friendly hooks in which to apply additional database state during a flush.

当使用MapperEvents时,event.listen()函数可以使用几个修饰符。

参数:
  • propagate=False – When True, the event listener should be applied to all inheriting mappers and/or the mappers of inheriting classes, as well as any mapper which is the target of this listener.
  • raw=False – When True, the “target” argument passed to applicable event listener functions will be the instance’s InstanceState management object, rather than the mapped instance itself.
  • retval = False -

    当为True时,用户定义的事件函数必须有一个返回值,其目的是控制后续的事件传播,或者另外改变映射器正在进行的操作。可能的返回值是:

    • sqlalchemy.orm.interfaces.EXT_CONTINUE - 继续正常处理事件。
    • sqlalchemy.orm.interfaces.EXT_STOP - cancel all subsequent event handlers in the chain.
    • 其他值 - 特定侦听器指定的返回值。
after_configured T0> ( T1> ) T2> ¶ T3>

在一系列映射器被配置之后调用。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'after_configured')
def receive_after_configured():
    "listen for the 'after_configured' event"

    # ... (event handling logic) ...

The MapperEvents.after_configured() event is invoked each time the orm.configure_mappers() function is invoked, after the function has completed its work. orm.configure_mappers() is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected.

Contrast this event to the MapperEvents.mapper_configured() event, which is called on a per-mapper basis while the configuration operation proceeds; unlike that event, when this event is invoked, all cross-configurations (e.g. backrefs) will also have been made available for any mappers that were pending. 也可以与MapperEvents.before_configured()进行比较,在配置一系列映射器之前调用该映射。

This event can only be applied to the Mapper class or mapper() function, and not to individual mappings or mapped classes. 它只是针对整个映射而被调用的:

from sqlalchemy.orm import mapper

@event.listens_for(mapper, "after_configured")
def go():
    # ...

理论上这个事件在每个应用程序中被调用一次,但实际上在任何时候调用新的映射器都会受到orm.configure_mappers()调用的影响。如果在现有的映射已被使用之后构建新的映射,则可能再次调用该事件。为了确保一个特定的事件只被调用一次而不再进行,可以应用once=True参数(0.9.4中的新值):

from sqlalchemy.orm import mapper

@event.listens_for(mapper, "after_configured", once=True)
def go():
    # ...
after_delete(mapper, connection, target)

在与该实例相对应的DELETE语句发出后接收对象实例。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'after_delete')
def receive_after_delete(mapper, connection, target):
    "listen for the 'after_delete' event"

    # ... (event handling logic) ...

此事件用于在给定的连接上发出额外的SQL语句,以及执行与删除事件有关的特定于应用程序的簿记。

这个事件通常在之前的一个步骤中一次发出DELETE语句之后,被调用一批同一类的对象。

警告

映射级别刷新事件只允许非常有限的操作,只对本地行的属性进行操作,以及允许在给定的Connection上发送任何SQL。Please read fully the notes at Mapper-level Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

参数:
  • mapper – the Mapper which is the target of this event.
  • connection – the Connection being used to emit DELETE statements for this instance. 这提供了特定于此实例的目标数据库上的当前事务的句柄。
  • target - 被删除的映射实例。如果事件配置为raw=True,则这将是与该实例关联的InstanceState状态管理对象。
返回:

此事件不支持返回值。

也可以看看

Persistence Events

after_insert(mapper, connection, target)

在对应于该实例的INSERT语句发出后接收对象实例。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'after_insert')
def receive_after_insert(mapper, connection, target):
    "listen for the 'after_insert' event"

    # ... (event handling logic) ...

此事件用于在发生INSERT之后修改实例中的纯Python内部状态,以及在给定连接上发出额外的SQL语句。

在上一步中一次发出INSERT语句之后,通常会调用该事件的一批对象。在极少数情况下,这是不可取的,可以使用batch=False来配置mapper(),这会导致批次的实例被分解为单个和更差的表演)事件 - >坚持 - >事件步骤。

警告

映射级别刷新事件只允许非常有限的操作,只对本地行的属性进行操作,以及允许在给定的Connection上发送任何SQL。Please read fully the notes at Mapper-level Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

参数:
  • mapper – the Mapper which is the target of this event.
  • connection – the Connection being used to emit INSERT statements for this instance. 这提供了特定于此实例的目标数据库上的当前事务的句柄。
  • target – the mapped instance being persisted. 如果事件配置为raw=True,则这将是与该实例关联的InstanceState状态管理对象。
返回:

此事件不支持返回值。

也可以看看

Persistence Events

after_update(mapper, connection, target)

在对应于该实例的UPDATE语句发出后接收对象实例。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'after_update')
def receive_after_update(mapper, connection, target):
    "listen for the 'after_update' event"

    # ... (event handling logic) ...

在发生UPDATE之后,此事件用于修改实例中的仅Python内部状态,以及在给定连接上发出其他SQL语句。

This method is called for all instances that are marked as “dirty”, even those which have no net changes to their column-based attributes, and for which no UPDATE statement has proceeded. 当一个对象的任何基于列的属性有一个被调用的“set attribute”操作,或者当它的任何一个集合被修改时,这个对象被标记为脏。如果在更新时没有基于列的属性有任何净更改,则不会发布UPDATE语句。这意味着发送到after_update()的实例不是保证UPDATE语句已经发出。

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

这个事件通常会在上一步中一次发送UPDATE语句之后被调用同一类的一批对象。在极少数情况下,这是不可取的,可以使用batch=False来配置mapper(),这会导致批次的实例被分解为单个和更差的表演)事件 - >坚持 - >事件步骤。

警告

映射级别刷新事件只允许非常有限的操作,只对本地行的属性进行操作,以及允许在给定的Connection上发送任何SQL。Please read fully the notes at Mapper-level Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

参数:
  • mapper – the Mapper which is the target of this event.
  • connection – the Connection being used to emit UPDATE statements for this instance. 这提供了特定于此实例的目标数据库上的当前事务的句柄。
  • target – the mapped instance being persisted. 如果事件配置为raw=True,则这将是与该实例关联的InstanceState状态管理对象。
返回:

此事件不支持返回值。

也可以看看

Persistence Events

before_configured T0> ( T1> ) T2> ¶ T3>

在一系列映射器被配置之前调用。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'before_configured')
def receive_before_configured():
    "listen for the 'before_configured' event"

    # ... (event handling logic) ...

The MapperEvents.before_configured() event is invoked each time the orm.configure_mappers() function is invoked, before the function has done any of its work. orm.configure_mappers() is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected.

This event can only be applied to the Mapper class or mapper() function, and not to individual mappings or mapped classes. 它只是针对整个映射而被调用的:

from sqlalchemy.orm import mapper

@event.listens_for(mapper, "before_configured")
def go():
    # ...

将这个事件约束到MapperEvents.after_configured(),该映射在配置了一系列映射器之后调用,以及MapperEvents.mapper_configured()按照每个映射器的基础,尽可能地配置每个映射器。

理论上这个事件在每个应用程序中被调用一次,但实际上在任何时候调用新的映射器都会受到orm.configure_mappers()调用的影响。如果在现有的映射已被使用之后构建新的映射,则可能再次调用该事件。为了确保一个特定的事件只被调用一次而不再进行,可以应用once=True参数(0.9.4中的新值):

from sqlalchemy.orm import mapper

@event.listens_for(mapper, "before_configured", once=True)
def go():
    # ...

版本0.9.3中新增。

before_delete(mapper, connection, target)

在与该实例相对应的DELETE语句发出之前接收一个对象实例。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'before_delete')
def receive_before_delete(mapper, connection, target):
    "listen for the 'before_delete' event"

    # ... (event handling logic) ...

此事件用于在给定的连接上发出额外的SQL语句,以及执行与删除事件有关的特定于应用程序的簿记。

在稍后的步骤中一次发出DELETE语句之前,通常会调用该事件的一批对象。

警告

映射级别刷新事件只允许非常有限的操作,只对本地行的属性进行操作,以及允许在给定的Connection上发送任何SQL。Please read fully the notes at Mapper-level Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

参数:
  • mapper – the Mapper which is the target of this event.
  • connection – the Connection being used to emit DELETE statements for this instance. 这提供了特定于此实例的目标数据库上的当前事务的句柄。
  • target - 被删除的映射实例。如果事件配置为raw=True,则这将是与该实例关联的InstanceState状态管理对象。
返回:

此事件不支持返回值。

也可以看看

Persistence Events

before_insert(mapper, connection, target)

在对应于该实例的INSERT语句发出之前接收对象实例。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'before_insert')
def receive_before_insert(mapper, connection, target):
    "listen for the 'before_insert' event"

    # ... (event handling logic) ...

在发生INSERT之前,此事件用于修改实例上的本地非对象相关属性,以及在给定连接上发出额外的SQL语句。

在稍后的步骤中一次发出INSERT语句之前,事件通常被称为一批同一类的对象。在极少数情况下,这是不可取的,可以使用batch=False来配置mapper(),这会导致批次的实例被分解为单个和更差的表演)事件 - >坚持 - >事件步骤。

警告

映射级别刷新事件只允许非常有限的操作,只对本地行的属性进行操作,以及允许在给定的Connection上发送任何SQL。Please read fully the notes at Mapper-level Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

参数:
  • mapper – the Mapper which is the target of this event.
  • connection – the Connection being used to emit INSERT statements for this instance. 这提供了特定于此实例的目标数据库上的当前事务的句柄。
  • target – the mapped instance being persisted. 如果事件配置为raw=True,则这将是与该实例关联的InstanceState状态管理对象。
返回:

此事件不支持返回值。

也可以看看

Persistence Events

before_update(mapper, connection, target)

在对应于该实例的UPDATE语句发出之前接收对象实例。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'before_update')
def receive_before_update(mapper, connection, target):
    "listen for the 'before_update' event"

    # ... (event handling logic) ...

此事件用于在UPDATE发生之前修改实例上的本地非对象相关属性,以及在给定连接上发出其他SQL语句。

This method is called for all instances that are marked as “dirty”, even those which have no net changes to their column-based attributes. 当一个对象的任何基于列的属性有一个被调用的“set attribute”操作,或者当它的任何一个集合被修改时,这个对象被标记为脏。如果在更新时没有基于列的属性有任何净更改,则不会发布UPDATE语句。这意味着发送到before_update()的实例不是保证会发出UPDATE语句,尽管您可以通过修改属性来影响结果,净价值变化确实存在。

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

在稍后的步骤中一次发送UPDATE语句之前,事件通常被称为一批同一类的对象。在极少数情况下,这是不可取的,可以使用batch=False来配置mapper(),这会导致批次的实例被分解为单个和更差的表演)事件 - >坚持 - >事件步骤。

警告

映射级别刷新事件只允许非常有限的操作,只对本地行的属性进行操作,以及允许在给定的Connection上发送任何SQL。Please read fully the notes at Mapper-level Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

参数:
  • mapper – the Mapper which is the target of this event.
  • connection – the Connection being used to emit UPDATE statements for this instance. 这提供了特定于此实例的目标数据库上的当前事务的句柄。
  • target – the mapped instance being persisted. 如果事件配置为raw=True,则这将是与该实例关联的InstanceState状态管理对象。
返回:

此事件不支持返回值。

也可以看看

Persistence Events

instrument_class(mapper, class_)

在映射器首次构建时接收一个类,然后将映射应用到映射类。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'instrument_class')
def receive_instrument_class(mapper, class_):
    "listen for the 'instrument_class' event"

    # ... (event handling logic) ...

这个事件是mapper建设的最早阶段。映射器的大多数属性尚未初始化。

这个监听器既可以应用于整个Mapper类,也可以应用于作为将要映射的类的基础的任何未映射的类(使用propagate=True旗):

Base = declarative_base()

@event.listens_for(Base, "instrument_class", propagate=True)
def on_new_class(mapper, cls_):
    " ... "
参数:
  • mapper – the Mapper which is the target of this event.
  • class _ - 映射的类。
mapper_configured(mapper, class_)

当特定映射器在configure_mappers()调用的范围内完成自己的配置时调用。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'mapper_configured')
def receive_mapper_configured(mapper, class_):
    "listen for the 'mapper_configured' event"

    # ... (event handling logic) ...

orm.configure_mappers()函数继续执行尚未配置的映射器的当前列表时,会为每个映射器调用MapperEvents.mapper_configured()事件。orm.configure_mappers() is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected.

When the event is called, the mapper should be in its final state, but not including backrefs that may be invoked from other mappers; they might still be pending within the configuration operation. orm.relationship.back_populates参数替代配置的双向关系将完全可用,因为这种关系式不依赖于其他可能未配置的映射器知道它们存在。

对于一个确保所有映​​射器准备好的事件,包括仅在其他映射中定义的backrefs,使用MapperEvents.after_configured()事件;此事件只有在所有已知的映射完全配置后才会调用。

The MapperEvents.mapper_configured() event, unlike MapperEvents.before_configured() or MapperEvents.after_configured(), is called for each mapper/class individually, and the mapper is passed to the event itself. 它也被称为一次特定的映射器。因此,事件对于配置步骤是有用的,因为在特定的映射器基础上被调用一次,而不需要“backref”配置必须准备好。

参数:
  • mapper – the Mapper which is the target of this event.
  • class _ - 映射的类。

实例事件

class sqlalchemy.orm.events。 InstanceEvents

基础:sqlalchemy.event.base.Events

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

例如。:

from sqlalchemy import event

def my_load_listener(target, context):
    print "on load!"

event.listen(SomeClass, 'load', my_load_listener)

可用目标包括:

  • 映射类
  • 未映射的映射或待映射类的超类(使用propagate=True标志)
  • Mapper对象
  • Mapper类本身和mapper()函数指示侦听所有映射器。

Changed in version 0.8.0: instance events can be associated with unmapped superclasses of mapped classes.

实例事件与映射器事件密切相关,但对于实例及其实现更具体,而不是持久化系统。

当使用InstanceEvents时,event.listen()函数可以使用几个修饰符。

参数:
  • propagate=False – When True, the event listener should be applied to all inheriting classes as well as the class which is the target of this listener.
  • raw=False – When True, the “target” argument passed to applicable event listener functions will be the instance’s InstanceState management object, rather than the mapped instance itself.
expire targetattrs

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

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'expire')
def receive_expire(target, attrs):
    "listen for the 'expire' event"

    # ... (event handling logic) ...

“键”是属性名称的列表。如果没有,整个州都过期了。

参数:
  • target - 映射的实例。如果事件配置为raw=True,则这将是与该实例关联的InstanceState状态管理对象。
  • attrs – sequence of attribute names which were expired, or None if all attributes were expired.
first_init(manager, cls)

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

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'first_init')
def receive_first_init(manager, cls):
    "listen for the 'first_init' event"

    # ... (event handling logic) ...

当一个类的__init__方法被称为该特定类的第一次时,这个事件被调用。在调用InstanceEvents.init()事件之前,事件在__init__实际进行之前调用。

init targetargskwargs ¶ T6>

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

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'init')
def receive_init(target, args, kwargs):
    "listen for the 'init' event"

    # ... (event handling logic) ...

这种方法只能在对象的用户区构造过程中与对象的构造函数一起被调用,例如,它的__init__方法。从数据库加载对象时不调用它;请参阅InstanceEvents.load()事件以拦截数据库负载。

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

参数:
  • target - 映射的实例。如果事件配置为raw=True,则这将是与该实例关联的InstanceState状态管理对象。
  • args – positional arguments passed to the __init__ method. 这是作为一个元组传递的,目前是不可变的。
  • kwargs – keyword arguments passed to the __init__ method. 这个结构可以被修改。
init_failure tt> targetargskwargs ¶ T6>

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

示例参数表单:

from sqlalchemy import event

# standard decorator style
@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 – positional arguments that were passed to the __init__ method.
  • kwargs – keyword arguments that were passed to the __init__ method.
load(target, context)

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

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'load')
def receive_load(target, context):
    "listen for the 'load' event"

    # ... (event handling logic) ...

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

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

参数:
  • target - 映射的实例。如果事件配置为raw=True,则这将是与该实例关联的InstanceState状态管理对象。
  • context – the QueryContext corresponding to the current Query in progress. 如果加载不对应于Query,例如在Session.merge()期间,则此参数可能为None
pickle(target, state_dict)

接收一个对象实例,当其关联的状态正在酸洗。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@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 – the dictionary returned by InstanceState.__getstate__, containing the state to be pickled.
refresh(target, context, attrs)

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

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeClass, 'refresh')
def receive_refresh(target, context, attrs):
    "listen for the 'refresh' event"

    # ... (event handling logic) ...

将它与InstanceEvents.load()方法进行比较,该方法在从查询中首次加载对象时调用。

参数:
  • target - 映射的实例。如果事件配置为raw=True,则这将是与该实例关联的InstanceState状态管理对象。
  • context – the QueryContext corresponding to the current Query in progress.
  • attrs – sequence of attribute names which were populated, or None if all column-mapped, non-deferred attributes were populated.

也可以看看

InstanceEvents.load()

refresh_flush tt> targetflush_contextattrs ¶ T6>

在对象的持久性内刷新一个或多个属性后接收对象实例。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@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()相同,除了它在工作单元冲突过程中调用,并且这里的值通常来自处理INSERT或UPDATE的过程,例如通过RETURNING子句或从Python方面的默认值。

新版本1.0.5.

参数:
  • target - 映射的实例。如果事件配置为raw=True,则这将是与该实例关联的InstanceState状态管理对象。
  • flush_context – Internal UOWTransaction object which handles the details of the flush.
  • attrs – sequence of attribute names which were populated.
unpickle targetstate_dict

在其关联状态已取消之后接收对象实例。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@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 – the dictionary sent to InstanceState.__setstate__, containing the state dictionary which was pickled.

会话事件

class sqlalchemy.orm.events。 SessionEvents

基础:sqlalchemy.event.base.Events

定义特定于Session生命周期的事件。

例如。:

from sqlalchemy import event
from sqlalchemy.orm import sessionmaker

def my_before_commit(session):
    print "before commit!"

Session = sessionmaker()

event.listen(Session, "before_commit", my_before_commit)

listen()函数将接受Session对象以及sessionmaker()scoped_session()

此外,它还接受Session类,该类将侦听器全局应用于所有Session实例。

after_attach sessioninstance

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

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'after_attach')
def receive_after_attach(session, instance):
    "listen for the 'after_attach' event"

    # ... (event handling logic) ...

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

注意

从0.8开始,此事件在项目与会话完全关联之后触发,与以前的版本不同。对于要求对象尚未成为会话状态一部分的事件处理程序(例如在目标对象尚未完成时可能自动刷新的处理程序),请考虑新的before_attach()事件。

after_begin(session, transaction, connection)

在连接开始事务后执行

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'after_begin')
def receive_after_begin(session, transaction, connection):
    "listen for the 'after_begin' event"

    # ... (event handling logic) ...
参数:
after_bulk_delete T0> ( T1> delete_context T2> ) T3> ¶ T4>

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

示例参数表单:

from sqlalchemy import event

# standard decorator style (arguments as of 0.9)
@event.listens_for(SomeSessionOrFactory, 'after_bulk_delete')
def receive_after_bulk_delete(delete_context):
    "listen for the 'after_bulk_delete' event"

    # ... (event handling logic) ...

# legacy calling style (pre-0.9)
@event.listens_for(SomeSessionOrFactory, 'after_bulk_delete')
def receive_after_bulk_delete(session, query, query_context, result):
    "listen for the 'after_bulk_delete' event"

    # ... (event handling logic) ...

版本0.9已更改 after_bulk_delete事件现在接受参数delete_context接受上面列出的先前参数签名的监听器函数将自动适应新的签名。

这被称为Query.delete()方法的结果。

参数: delete_context -

包含有关更新的详细信息的“删除上下文”对象,包括这些属性:

  • session - 涉及Session
  • query - Query对象是否调用了此更新操作。
  • context对应于调用ORM查询的QueryContext对象。
  • result the ResultProxy returned as a result of the bulk DELETE operation.
after_bulk_update T0> ( T1> update_context T2> ) T3> ¶ T4>

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

示例参数表单:

from sqlalchemy import event

# standard decorator style (arguments as of 0.9)
@event.listens_for(SomeSessionOrFactory, 'after_bulk_update')
def receive_after_bulk_update(update_context):
    "listen for the 'after_bulk_update' event"

    # ... (event handling logic) ...

# legacy calling style (pre-0.9)
@event.listens_for(SomeSessionOrFactory, 'after_bulk_update')
def receive_after_bulk_update(session, query, query_context, result):
    "listen for the 'after_bulk_update' event"

    # ... (event handling logic) ...

更改为0.9版: after_bulk_update现在接受参数update_context接受上面列出的先前参数签名的监听器函数将自动适应新的签名。

这被称为Query.update()方法的结果。

参数: update_context -

包含更新细节的“更新上下文”对象,包括这些属性:

  • session - 涉及Session
  • query - Query对象是否调用了此更新操作。
  • context对应于调用ORM查询的QueryContext对象。
  • result the ResultProxy returned as a result of the bulk UPDATE operation.
after_commit T0> ( T1> 会话 T2> ) T3> ¶ T4>

提交发生后执行。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'after_commit')
def receive_after_commit(session):
    "listen for the 'after_commit' event"

    # ... (event handling logic) ...

注意

The after_commit() hook is not per-flush, that is, the Session can emit SQL to the database many times within the scope of a transaction. 要拦截这些事件,请使用before_flush()after_flush()after_flush_postexec()事件。

注意

当调用after_commit()事件时,Session不处于活动事务中,因此不能发出SQL。要发出对应于每个事务的SQL,请使用before_commit()事件。

参数:session – The target Session.
after_flush sessionflush_context

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

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'after_flush')
def receive_after_flush(session, flush_context):
    "listen for the 'after_flush' event"

    # ... (event handling logic) ...

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

参数:
after_flush_postexec sessionflush_context

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

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'after_flush_postexec')
def receive_after_flush_postexec(session, flush_context):
    "listen for the 'after_flush_postexec' event"

    # ... (event handling logic) ...

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

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

在发生真正的DBAPI回滚之后执行。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'after_rollback')
def receive_after_rollback(session):
    "listen for the 'after_rollback' event"

    # ... (event handling logic) ...

请注意,只有在针对数据库的实际回滚发生时才会触发此事件 - 每次Session.rollback()方法都会触发而不是如果底层的DBAPI事务已经被回滚,就调用它。在许多情况下,由于当前事务无效,Session在此事件期间不会处于“活动”状态。要获取在最后一个回滚进行之后处于活动状态的Session,请使用SessionEvents.after_soft_rollback()事件,检查Session.is_active标志。

参数:session – The target Session.
after_soft_rollback(session, previous_transaction)

在发生任何回滚之后执行,包括实际上在DBAPI级别上不发送的“软”回滚。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'after_soft_rollback')
def receive_after_soft_rollback(session, previous_transaction):
    "listen for the 'after_soft_rollback' event"

    # ... (event handling logic) ...

这对应于嵌套和外部回滚,即调用DBAPI的rollback()方法的最里面的回滚以及只从事务堆栈中弹出的封闭回滚调用。

通过首先检查Session.is_active标志,可以使用给定的Session调用SQL和Session.query()

@event.listens_for(Session, "after_soft_rollback")
def do_something(session, previous_transaction):
    if session.is_active:
        session.execute("select * from some_table")
参数:

New in version 0.7.3.

after_transaction_create(session, transaction)

在创建新的SessionTransaction时执行。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'after_transaction_create')
def receive_after_transaction_create(session, transaction):
    "listen for the 'after_transaction_create' event"

    # ... (event handling logic) ...

这个事件与after_begin()的不同之处在于它发生在每个SessionTransaction整体上,而不是在单个数据库连接上开始事务。它也被嵌套事务和子事务调用,并且总是被相应的after_transaction_end()事件匹配(假设Session正常运行)。

参数:

0.8版本中的新功能

after_transaction_end(session, transaction)

SessionTransaction的跨度结束时执行。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'after_transaction_end')
def receive_after_transaction_end(session, transaction):
    "listen for the 'after_transaction_end' event"

    # ... (event handling logic) ...

这个事件与after_commit()的不同之处在于它对应于所有正在使用的SessionTransaction对象,包括嵌套事务和子事务的对象,并且总是与相应的after_transaction_create()事件。

参数:

0.8版本中的新功能

before_attach sessioninstance

在实例连接到会话之前执行。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'before_attach')
def receive_before_attach(session, instance):
    "listen for the 'before_attach' event"

    # ... (event handling logic) ...

这在添加,删除或合并之前被调用导致对象成为会话的一部分。

版本0.8中的新功能请注意,在项目成为会话的一部分之后,after_attach()现在会被触发。before_attach() is provided for those cases where the item should not yet be part of the session state.

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

在调用commit之前执行。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'before_commit')
def receive_before_commit(session):
    "listen for the 'before_commit' event"

    # ... (event handling logic) ...

注意

The before_commit() hook is not per-flush, that is, the Session can emit SQL to the database many times within the scope of a transaction. 要拦截这些事件,请使用before_flush()after_flush()after_flush_postexec()事件。

参数:session – The target Session.
before_flush(session, flush_context, instances)

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

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'before_flush')
def receive_before_flush(session, flush_context, instances):
    "listen for the 'before_flush' event"

    # ... (event handling logic) ...
参数:
  • session – The target Session.
  • flush_context – Internal UOWTransaction object which handles the details of the flush.
  • instances – Usually None, this is the collection of objects which can be passed to the Session.flush() method (note this usage is deprecated).
deleted_to_detached sessioninstance

拦截特定对象的“已删除到已分离”过渡。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'deleted_to_detached')
def receive_deleted_to_detached(session, instance):
    "listen for the 'deleted_to_detached' event"

    # ... (event handling logic) ...

当从会话中删除已删除的对象时调用此事件。发生这种情况的典型情况是当提交的对​​象被删除的Session的事务被提交时,对象从删除状态移到分离状态。

It is also invoked for objects that were deleted in a flush when the Session.expunge_all() or Session.close() events are called, as well as if the object is individually expunged from its deleted state via Session.expunge().

版本1.1中的新功能

deleted_to_persistent sessioninstance

截取特定对象的“已删除到永久”转换。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'deleted_to_persistent')
def receive_deleted_to_persistent(session, instance):
    "listen for the 'deleted_to_persistent' event"

    # ... (event handling logic) ...

只有当由于调用Session.rollback()而在刷新中成功删除的对象被恢复时才会发生此转换。在任何其他情况下不会调用该事件。

版本1.1中的新功能

detached_to_persistent(session, instance)

截取特定对象的“分离到持续”转换。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'detached_to_persistent')
def receive_detached_to_persistent(session, instance):
    "listen for the 'detached_to_persistent' event"

    # ... (event handling logic) ...

这个事件是SessionEvents.after_attach()事件的一个特殊性,它只为这个特定的转换而被调用。通常在Session.add()调用期间以及在Session.delete()调用期间调用该对象,前提是该对象以前没有与Session(注意标记为“已删除”的对象保持“持续”状态,直到刷新结束)。

注意

如果对象作为对Session.delete()的调用的一部分而持久化,则在调用此事件时,对象不是,但标记为已删除。To detect deleted objects, check the deleted flag sent to the SessionEvents.persistent_to_detached() to event after the flush proceeds, or check the Session.deleted collection within the SessionEvents.before_flush() event if deleted objects need to be intercepted before the flush.

参数:
  • tt> 会话 - 目标Session
  • instance – the ORM-mapped instance being operated upon.

版本1.1中的新功能

loaded_as_persistent(session, instance)

截取特定对象的“已加载”过渡。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'loaded_as_persistent')
def receive_loaded_as_persistent(session, instance):
    "listen for the 'loaded_as_persistent' event"

    # ... (event handling logic) ...

这个事件在ORM加载过程中被调用,并且与InstanceEvents.load()事件的调用非常相似。然而,这里的事件可以链接到一个Session类或实例,而不是映射器或类层次结构,并与其他会话生命周期事件顺利集成。当该事件被调用时,该对象保证出现在会话的身份映射中。

参数:
  • tt> 会话 - 目标Session
  • instance – the ORM-mapped instance being operated upon.

版本1.1中的新功能

pending_to_persistent 会话实例

截取特定对象的“挂起到持续”转换。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'pending_to_persistent')
def receive_pending_to_persistent(session, instance):
    "listen for the 'pending_to_persistent' event"

    # ... (event handling logic) ...

该事件在刷新过程中被调用,类似于在SessionEvents.after_flush()事件中扫描Session.new集合。但是,在这种情况下,当事件被调用时,对象已经被移至持久状态。

参数:
  • tt> 会话 - 目标Session
  • instance – the ORM-mapped instance being operated upon.

版本1.1中的新功能

pending_to_transient sessioninstance

截取特定对象的“等待到瞬态”转换。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'pending_to_transient')
def receive_pending_to_transient(session, instance):
    "listen for the 'pending_to_transient' event"

    # ... (event handling logic) ...

当没有被刷新的待处理对象被从会话中逐出时,发生这种不太常见的转换;当Session.rollback()方法回退事务或使用Session.expunge()方法时,可能发生这种情况。

参数:
  • tt> 会话 - 目标Session
  • instance – the ORM-mapped instance being operated upon.

版本1.1中的新功能

persistent_to_deleted sessioninstance

截取特定对象的“永久删除”转换。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'persistent_to_deleted')
def receive_persistent_to_deleted(session, instance):
    "listen for the 'persistent_to_deleted' event"

    # ... (event handling logic) ...

当一个持久化对象的标识在flush中被从数据库中删除时,这个事件被调用,但是在事务完成之前,该对象仍然与Session关联。

如果事务回滚,则对象再次移至持久状态,并调用SessionEvents.deleted_to_persistent()事件。如果事务被提交,则对象变成分离的,这将发出SessionEvents.deleted_to_detached()事件。

请注意,虽然Session.delete()方法是将对象标记为已删除的主要公共接口,但是由于级联规则而导致许多对象被删除,直到刷新时间才会确定。因此,没有办法捕捉每个将被删除的对象,直到刷新进行。所以SessionEvents.persistent_to_deleted()事件在刷新结束时被调用。

版本1.1中的新功能

persistent_to_detached sessioninstance

截取特定对象的“持久到分离”转换。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'persistent_to_detached')
def receive_persistent_to_detached(session, instance):
    "listen for the 'persistent_to_detached' event"

    # ... (event handling logic) ...

当一个持久对象被从会话中清除时,这个事件被调用。导致这种情况发生的条件很多,包括:

参数:
  • tt> 会话 - 目标Session
  • instance – the ORM-mapped instance being operated upon.
  • 已删除 - 布尔值。如果为True,则表示此对象已移至分离状态,因为它已标记为已删除并已清除。

版本1.1中的新功能

persistent_to_transient sessioninstance

截取特定对象的“持久到瞬态”转换。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'persistent_to_transient')
def receive_persistent_to_transient(session, instance):
    "listen for the 'persistent_to_transient' event"

    # ... (event handling logic) ...

当已经刷新的挂起对象被从会话中逐出时,发生这种不太常见的转换;当Session.rollback()方法回滚事务时,会发生这种情况。

参数:
  • tt> 会话 - 目标Session
  • instance – the ORM-mapped instance being operated upon.

版本1.1中的新功能

transient_to_pending sessioninstance

截取特定对象的“暂态到暂挂”转换。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeSessionOrFactory, 'transient_to_pending')
def receive_transient_to_pending(session, instance):
    "listen for the 'transient_to_pending' event"

    # ... (event handling logic) ...

这个事件是SessionEvents.after_attach()事件的一个特殊性,它只为这个特定的转换而被调用。它通常在Session.add()调用期间被调用。

参数:
  • tt> 会话 - 目标Session
  • instance – the ORM-mapped instance being operated upon.

版本1.1中的新功能

查询事件

class sqlalchemy.orm.events。 QueryEvents

基础:sqlalchemy.event.base.Events

Query对象的结构中表示事件。

此处的事件旨在用于Query的尚未发布的检查系统。现在可以进行一些非常基本的操作,但是检查系统的目的是使复杂的查询操作自动化。

版本1.0.0中的新功能

before_compile T0> ( T1> 查询 T2> ) T3> ¶ T4>

接收Query对象,然后将其组成核心Select对象。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeQuery, 'before_compile')
def receive_before_compile(query):
    "listen for the 'before_compile' event"

    # ... (event handling logic) ...

此事件旨在允许更改给出的查询:

@event.listens_for(Query, "before_compile", retval=True)
def no_deleted(query):
    for desc in query.column_descriptions:
        if desc['type'] is User:
            entity = desc['entity']
            query = query.filter(entity.deleted == False)
    return query

通常应该使用retval=True参数集来监听事件,以便可以返回修改后的查询。

仪器事件

定义SQLAlchemy的类检测系统。

这个模块通常不是用户应用程序直接可见的,但定义了ORM交互性的很大一部分。

instrumentation.py处理状态跟踪的最终用户类的注册。它与分别建立per-instance和per-class-attribute工具的state.py和attributes.py紧密交互。

类工具系统可以使用sqlalchemy.ext.instrumentation模块在每个类或全局基础上定制,该模块提供了构建和指定替代工具形式的方法。

class sqlalchemy.orm.events。 InstrumentationEvents

基础:sqlalchemy.event.base.Events

与类仪器事件相关的事件。

这里的监听器支持针对任何新的风格类建立对象,即任何属于“类型”的子类的对象。然后事件将被解雇对这个类的事件。如果“propagate = True”标志被传递给event.listen(),则该事件也将触发该类的子类。

内建的Python type也被接受为目标,它在使用时具有为所有类发出事件的效果。

请注意,此处的“传播”标志默认为True,与其他默认为False的其他类级别事件不同。这意味着当一个监听器建立在超类上时,新的子类也将成为这些事件的主体。

在0.8版本中改变: - 这里的事件将基于比较传入的类和传递给event.listen()的类的类型来发射。以前,尽管文件中有相反的说明,但事件将无条件地为任何班级开火,无论哪个班级被送去聆听。

attribute_instrument(cls, key, inst)

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeBaseClass, 'attribute_instrument')
def receive_attribute_instrument(cls, key, inst):
    "listen for the 'attribute_instrument' event"

    # ... (event handling logic) ...

调用属性时调用。

class_instrument T0> ( T1> CLS T2> ) T3> ¶ T4>

在给定的课程被装备后调用。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeBaseClass, 'class_instrument')
def receive_class_instrument(cls):
    "listen for the 'class_instrument' event"

    # ... (event handling logic) ...

要得到ClassManager,请使用manager_of_class()

class_uninstrument T0> ( T1> CLS T2> ) T3> ¶ T4>

在给定的类没有被打开之前调用。

示例参数表单:

from sqlalchemy import event

# standard decorator style
@event.listens_for(SomeBaseClass, 'class_uninstrument')
def receive_class_uninstrument(cls):
    "listen for the 'class_uninstrument' event"

    # ... (event handling logic) ...

要得到ClassManager,请使用manager_of_class()