sqlalchemy.orm.events.AttributeEvents

Receive a collection append event.

The append event is invoked for each element as it is appended to the collection. This occurs for single-item appends as well as for a "bulk replace" operation.

Receive a collection append event where the collection was not actually mutated.

This event differs from _orm.AttributeEvents.append in that it is fired off for de-duplicating collections such as sets and dictionaries, when the object already exists in the target collection. The event does not have a return value and the identity of the given object cannot be changed.

The event is used for cascading objects into a _orm.Session when the collection has already been mutated via a backref event.

Receive a collection 'bulk replace' event.

This event is invoked for a sequence of values as they are incoming to a bulk collection set operation, which can be modified in place before the values are treated as ORM objects. This is an "early hook" that runs before the bulk replace routine attempts to reconcile which objects are already present in the collection and which are being removed by the net replace operation.

It is typical that this method be combined with use of the .AttributeEvents.append event. When using both of these events, note that a bulk replace operation will invoke the .AttributeEvents.append event for all new items, even after .AttributeEvents.bulk_replace has been invoked for the collection as a whole. In order to determine if an .AttributeEvents.append event is part of a bulk replace, use the symbol ~.attributes.OP_BULK_REPLACE to test the incoming 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

Receive a 'collection dispose' event.

This event is triggered for a collection-based attribute when a collection is replaced, that is:

u1.addresses.append(a1)

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

The old collection received will contain its previous contents.

Receive a 'collection init' event.

This event is triggered for a collection-based attribute, when the initial "empty collection" is first generated for a blank attribute, as well as for when the collection is replaced with a new one, such as via a set event.

E.g., given that User.addresses is a relationship-based collection, the event is triggered here:

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

and also during replace operations:

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

Receive a scalar "init" event.

This event is invoked when an uninitialized, unpersisted scalar attribute is accessed, e.g. read:

x = my_object.some_attribute

The ORM's default behavior when this occurs for an un-initialized attribute is to return the value None; note this differs from Python's usual behavior of raising AttributeError. The event here can be used to customize what value is actually returned, with the assumption that the event listener would be mirroring a default generator that is configured on the Core _schema.Column object as well.

Since a default generator on a _schema.Column might also produce a changing value such as a timestamp, the .AttributeEvents.init_scalar event handler can also be used to set the newly returned value, so that a Core-level default generation function effectively fires off only once, but at the moment the attribute is accessed on the non-persisted object. Normally, no change to the object's state is made when an uninitialized attribute is accessed (much older SQLAlchemy versions did in fact change the object's state).

If a default generator on a column returned a particular constant, a handler might be used as follows:

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

Above, we initialize the attribute MyClass.some_attribute to the value of SOME_CONSTANT. The above code includes the following features:

• By setting the value SOME_CONSTANT in the given dict_, we indicate that this value is to be persisted to the database. This supersedes the use of SOME_CONSTANT in the default generator for the _schema.Column. The active_column_defaults.py example given at :ref:`examples_instrumentation` illustrates using the same approach for a changing default, e.g. a timestamp generator. In this particular example, it is not strictly necessary to do this since SOME_CONSTANT would be part of the INSERT statement in either case.
• By establishing the retval=True flag, the value we return from the function will be returned by the attribute getter. Without this flag, the event is assumed to be a passive observer and the return value of our function is ignored.
• The propagate=True flag is significant if the mapped class includes inheriting subclasses, which would also make use of this event listener. Without this flag, an inheriting subclass will not use our event handler.

In the above example, the attribute set event .AttributeEvents.set as well as the related validation feature provided by _orm.validates is not invoked when we apply our value to the given dict_. To have these events to invoke in response to our newly generated value, apply the value to the given object as a normal attribute set operation:

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

When multiple listeners are set up, the generation of the value is "chained" from one listener to the next by passing the value returned by the previous listener that specifies retval=True as the value argument of the next listener.

Receive a 'modified' event.

This event is triggered when the .attributes.flag_modified function is used to trigger a modify event on an attribute without any specific value being set.

Receive a collection remove event.

Receive a scalar set event.