Classe « AttributeEvents »

Méthode sqlalchemy.orm.AttributeEvents.bulk_replace

Signature de la méthode bulk_replace

def bulk_replace(self, target, values, initiator) 

Description

bulk_replace.__doc__

Receive a collection 'bulk replace' event.

.. container:: event_signatures

     Example argument forms::

        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) ...


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
:meth:`.AttributeEvents.append` event.    When using both of these
events, note that a bulk replace operation will invoke
the :meth:`.AttributeEvents.append` event for all new items,
even after :meth:`.AttributeEvents.bulk_replace` has been invoked
for the collection as a whole.  In order to determine if an
:meth:`.AttributeEvents.append` event is part of a bulk replace,
use the symbol :attr:`~.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

.. versionadded:: 1.2

:param target: the object instance receiving the event.
  If the listener is registered with ``raw=True``, this will
  be the :class:`.InstanceState` object.
:param value: a sequence (e.g. a list) of the values being set.  The
  handler can modify this list in place.
:param initiator: An instance of :class:`.attributes.Event`
  representing the initiation of the event.

.. seealso::

    :class:`.AttributeEvents` - background on listener options such
    as propagation to subclasses.