Classe « InstanceEvents »

Méthode sqlalchemy.orm.InstanceEvents.load

Signature de la méthode load

def load(self, target, context) 

Description

load.__doc__

Receive an object instance after it has been created via
``__new__``, and after initial attribute population has
occurred.

.. container:: event_signatures

     Example argument forms::

        from sqlalchemy import event


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

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


This typically occurs when the instance is created based on
incoming result rows, and is only called once for that
instance's lifetime.

.. warning::

    During a result-row load, this event is invoked when the
    first row received for this instance is processed.  When using
    eager loading with collection-oriented attributes, the additional
    rows that are to be loaded / processed in order to load subsequent
    collection items have not occurred yet.   This has the effect
    both that collections will not be fully loaded, as well as that
    if an operation occurs within this event handler that emits
    another database load operation for the object, the "loading
    context" for the object can change and interfere with the
    existing eager loaders still in progress.

    Examples of what can cause the "loading context" to change within
    the event handler include, but are not necessarily limited to:

    * accessing deferred attributes that weren't part of the row,
      will trigger an "undefer" operation and refresh the object

    * accessing attributes on a joined-inheritance subclass that
      weren't part of the row, will trigger a refresh operation.

    As of SQLAlchemy 1.3.14, a warning is emitted when this occurs. The
    :paramref:`.InstanceEvents.restore_load_context` option may  be
    used on the event to prevent this warning; this will ensure that
    the existing loading context is maintained for the object after the
    event is called::

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

    .. versionchanged:: 1.3.14 Added
       :paramref:`.InstanceEvents.restore_load_context`
       and :paramref:`.SessionEvents.restore_load_context` flags which
       apply to "on load" events, which will ensure that the loading
       context for an object is restored when the event hook is
       complete; a warning is emitted if the load context of the object
       changes without this flag being set.


The :meth:`.InstanceEvents.load` event is also available in a
class-method decorator format called :func:`_orm.reconstructor`.

:param target: the mapped instance.  If
 the event is configured with ``raw=True``, this will
 instead be the :class:`.InstanceState` state-management
 object associated with the instance.
:param context: the :class:`.QueryContext` corresponding to the
 current :class:`_query.Query` in progress.  This argument may be
 ``None`` if the load does not correspond to a :class:`_query.Query`,
 such as during :meth:`.Session.merge`.

.. seealso::

    :meth:`.InstanceEvents.init`

    :meth:`.InstanceEvents.refresh`

    :meth:`.SessionEvents.loaded_as_persistent`

    :ref:`mapping_constructors`