class MapperEvents(event.Events[
Known subclasses: sqlalchemy.orm.events._MapperEventsHold.HoldMapperEvents
Define events specific to mappings. e.g.:: 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.execute( text("select my_special_function(%d)" % target.special_number) ).scalar() # associate the listener function with SomeClass, # to execute during the "before_insert" hook event.listen( SomeClass, 'before_insert', my_before_insert_listener) Available targets include: * mapped classes * unmapped superclasses of mapped or to-be-mapped classes (using the ``propagate=True`` flag) * :class:`_orm.Mapper` objects * the :class:`_orm.Mapper` class itself indicates listening for all mappers. Mapper events provide hooks into critical sections of the mapper, including those related to object instrumentation, object loading, and object persistence. In particular, the persistence methods :meth:`~.MapperEvents.before_insert`, and :meth:`~.MapperEvents.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 :meth:`.SessionEvents.before_flush` and :meth:`.SessionEvents.after_flush` methods as more flexible and user-friendly hooks in which to apply additional database state during a flush. When using :class:`.MapperEvents`, several modifiers are available to the :func:`.event.listen` function. :param 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. :param raw=False: When True, the "target" argument passed to applicable event listener functions will be the instance's :class:`.InstanceState` management object, rather than the mapped instance itself. :param retval=False: when True, the user-defined event function must have a return value, the purpose of which is either to control subsequent event propagation, or to otherwise alter the operation in progress by the mapper. Possible return values are: * ``sqlalchemy.orm.interfaces.EXT_CONTINUE`` - continue event processing normally. * ``sqlalchemy.orm.interfaces.EXT_STOP`` - cancel all subsequent event handlers in the chain. * other values - the return value specified by specific listeners.
| Method | after |
Called after a series of mappers have been configured. |
| Method | after |
Receive an object instance after a DELETE statement has been emitted corresponding to that instance. |
| Method | after |
Receive an object instance after an INSERT statement is emitted corresponding to that instance. |
| Method | after |
Receive a class and mapper when the :class:`_orm.Mapper` has been fully constructed. |
| Method | after |
Receive an object instance after an UPDATE statement is emitted corresponding to that instance. |
| Method | before |
Called before a series of mappers have been configured. |
| Method | before |
Receive an object instance before a DELETE statement is emitted corresponding to that instance. |
| Method | before |
Receive an object instance before an INSERT statement is emitted corresponding to that instance. |
| Method | before |
Called right before a specific mapper is to be configured. |
| Method | before |
Receive an object instance before an UPDATE statement is emitted corresponding to that instance. |
| Method | instrument |
Receive a class when the mapper is first constructed, before instrumentation is applied to the mapped class. |
| Method | mapper |
Called when a specific mapper has completed its own configuration within the scope of the :func:`.configure_mappers` call. |
| Class Method | _accept |
Undocumented |
| Class Method | _clear |
Undocumented |
| Class Method | _listen |
Undocumented |
| Class Method | _new |
Undocumented |
| Class Variable | _target |
Undocumented |
Inherited from Events:
| Class Method | _remove |
Undocumented |
Inherited from _HasEventsDispatch (via Events):
| Method | __getattr__ |
Undocumented |
| Method | __init |
Intercept new Event subclasses and create associated _Dispatch classes. |
| Class Variable | dispatch |
reference back to the _Dispatch class. |
| Class Method | _create |
Create a :class:`._Dispatch` class corresponding to an :class:`.Events` class. |
| Static Method | _set |
Undocumented |
| Class Variable | _dispatch |
class which will receive the .dispatch collection |
Called after a series of mappers have been configured. The :meth:`.MapperEvents.after_configured` event is invoked each time the :func:`_orm.configure_mappers` function is invoked, after the function has completed its work. :func:`_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 :meth:`.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. Also contrast to :meth:`.MapperEvents.before_configured`, which is invoked before the series of mappers has been configured. This event can **only** be applied to the :class:`_orm.Mapper` class, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:: from sqlalchemy.orm import Mapper @event.listens_for(Mapper, "after_configured") def go(): # ... Theoretically this event is called once per application, but is actually called any time new mappers have been affected by a :func:`_orm.configure_mappers` call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the ``once=True`` argument (new in 0.9.4) can be applied:: from sqlalchemy.orm import mapper @event.listens_for(mapper, "after_configured", once=True) def go(): # ... .. seealso:: :meth:`.MapperEvents.before_mapper_configured` :meth:`.MapperEvents.mapper_configured` :meth:`.MapperEvents.before_configured`
Receive an object instance after a DELETE statement has been emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to emit additional SQL statements on the given connection as well as to perform application specific bookkeeping related to a deletion event. The event is often called for a batch of objects of the same class after their DELETE statements have been emitted at once in a previous step. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being deleted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events`
Receive an object instance after an INSERT statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify in-Python-only state on the instance after an INSERT occurs, as well as to emit additional SQL statements on the given connection. The event is often called for a batch of objects of the same class after their INSERT statements have been emitted at once in a previous step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` object can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events`
Receive a class and mapper when the :class:`_orm.Mapper` has been fully constructed. This event is called after the initial constructor for :class:`_orm.Mapper` completes. This occurs after the :meth:`_orm.MapperEvents.instrument_class` event and after the :class:`_orm.Mapper` has done an initial pass of its arguments to generate its collection of :class:`_orm.MapperProperty` objects, which are accessible via the :meth:`_orm.Mapper.get_property` method and the :attr:`_orm.Mapper.iterate_properties` attribute. This event differs from the :meth:`_orm.MapperEvents.before_mapper_configured` event in that it is invoked within the constructor for :class:`_orm.Mapper`, rather than within the :meth:`_orm.registry.configure` process. Currently, this event is the only one which is appropriate for handlers that wish to create additional mapped classes in response to the construction of this :class:`_orm.Mapper`, which will be part of the same configure step when :meth:`_orm.registry.configure` next runs. .. versionadded:: 2.0.2 .. seealso:: :ref:`examples_versioning` - an example which illustrates the use of the :meth:`_orm.MapperEvents.before_mapper_configured` event to create new mappers to record change-audit histories on objects.
Receive an object instance after an UPDATE statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify in-Python-only state on the instance after an UPDATE occurs, as well as to emit additional SQL statements on the given connection. 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. An object is marked as dirty when any of its column-based attributes have a "set attribute" operation called or when any of its collections are modified. If, at update time, no column-based attributes have any net changes, no UPDATE statement will be issued. This means that an instance being sent to :meth:`~.MapperEvents.after_update` is *not* a guarantee that an UPDATE statement has been issued. To detect if the column-based attributes on the object have net changes, and therefore resulted in an UPDATE statement, use ``object_session(instance).is_modified(instance, include_collections=False)``. The event is often called for a batch of objects of the same class after their UPDATE statements have been emitted at once in a previous step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events`
Called before a series of mappers have been configured. The :meth:`.MapperEvents.before_configured` event is invoked each time the :func:`_orm.configure_mappers` function is invoked, before the function has done any of its work. :func:`_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 :class:`_orm.Mapper` class, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:: from sqlalchemy.orm import Mapper @event.listens_for(Mapper, "before_configured") def go(): # ... Contrast this event to :meth:`.MapperEvents.after_configured`, which is invoked after the series of mappers has been configured, as well as :meth:`.MapperEvents.before_mapper_configured` and :meth:`.MapperEvents.mapper_configured`, which are both invoked on a per-mapper basis. Theoretically this event is called once per application, but is actually called any time new mappers are to be affected by a :func:`_orm.configure_mappers` call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the ``once=True`` argument (new in 0.9.4) can be applied:: from sqlalchemy.orm import mapper @event.listens_for(mapper, "before_configured", once=True) def go(): # ... .. versionadded:: 0.9.3 .. seealso:: :meth:`.MapperEvents.before_mapper_configured` :meth:`.MapperEvents.mapper_configured` :meth:`.MapperEvents.after_configured`
Receive an object instance before a DELETE statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to emit additional SQL statements on the given connection as well as to perform application specific bookkeeping related to a deletion event. The event is often called for a batch of objects of the same class before their DELETE statements are emitted at once in a later step. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being deleted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events`
Receive an object instance before an INSERT statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify local, non-object related attributes on the instance before an INSERT occurs, as well as to emit additional SQL statements on the given connection. The event is often called for a batch of objects of the same class before their INSERT statements are emitted at once in a later step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` object can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events`
Called right before a specific mapper is to be configured. This event is intended to allow a specific mapper to be skipped during the configure step, by returning the :attr:`.orm.interfaces.EXT_SKIP` symbol which indicates to the :func:`.configure_mappers` call that this particular mapper (or hierarchy of mappers, if ``propagate=True`` is used) should be skipped in the current configuration run. When one or more mappers are skipped, the he "new mappers" flag will remain set, meaning the :func:`.configure_mappers` function will continue to be called when mappers are used, to continue to try to configure all available mappers. In comparison to the other configure-level events, :meth:`.MapperEvents.before_configured`, :meth:`.MapperEvents.after_configured`, and :meth:`.MapperEvents.mapper_configured`, the :meth;`.MapperEvents.before_mapper_configured` event provides for a meaningful return value when it is registered with the ``retval=True`` parameter. .. versionadded:: 1.3 e.g.:: from sqlalchemy.orm import EXT_SKIP Base = declarative_base() DontConfigureBase = declarative_base() @event.listens_for( DontConfigureBase, "before_mapper_configured", retval=True, propagate=True) def dont_configure(mapper, cls): return EXT_SKIP .. seealso:: :meth:`.MapperEvents.before_configured` :meth:`.MapperEvents.after_configured` :meth:`.MapperEvents.mapper_configured`
Receive an object instance before an UPDATE statement is emitted corresponding to that instance. .. note:: this event **only** applies to the :ref:`session flush operation <session_flushing>` and does **not** apply to the ORM DML operations described at :ref:`orm_expression_update_delete`. To intercept ORM DML events, use :meth:`_orm.SessionEvents.do_orm_execute`. This event is used to modify local, non-object related attributes on the instance before an UPDATE occurs, as well as to emit additional SQL statements on the given connection. This method is called for all instances that are marked as "dirty", *even those which have no net changes to their column-based attributes*. An object is marked as dirty when any of its column-based attributes have a "set attribute" operation called or when any of its collections are modified. If, at update time, no column-based attributes have any net changes, no UPDATE statement will be issued. This means that an instance being sent to :meth:`~.MapperEvents.before_update` is *not* a guarantee that an UPDATE statement will be issued, although you can affect the outcome here by modifying attributes so that a net change in value does exist. To detect if the column-based attributes on the object have net changes, and will therefore generate an UPDATE statement, use ``object_session(instance).is_modified(instance, include_collections=False)``. The event is often called for a batch of objects of the same class before their UPDATE statements are emitted at once in a later step. In the extremely rare case that this is not desirable, the :class:`_orm.Mapper` can be configured with ``batch=False``, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps. .. warning:: Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param connection: the :class:`_engine.Connection` being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. :param target: the mapped instance being persisted. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. .. seealso:: :ref:`session_persistence_events`
Receive a class when the mapper is first constructed, before instrumentation is applied to the mapped class. This event is the earliest phase of mapper construction. Most attributes of the mapper are not yet initialized. To receive an event within initial mapper construction where basic state is available such as the :attr:`_orm.Mapper.attrs` collection, the :meth:`_orm.MapperEvents.after_mapper_constructed` event may be a better choice. This listener can either be applied to the :class:`_orm.Mapper` class overall, or to any un-mapped class which serves as a base for classes that will be mapped (using the ``propagate=True`` flag):: Base = declarative_base() @event.listens_for(Base, "instrument_class", propagate=True) def on_new_class(mapper, cls_): " ... " :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param class\_: the mapped class. .. seealso:: :meth:`_orm.MapperEvents.after_mapper_constructed`
Called when a specific mapper has completed its own configuration within the scope of the :func:`.configure_mappers` call. The :meth:`.MapperEvents.mapper_configured` event is invoked for each mapper that is encountered when the :func:`_orm.configure_mappers` function proceeds through the current list of not-yet-configured mappers. :func:`_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. Bidirectional relationships that are instead configured via the :paramref:`.orm.relationship.back_populates` argument *will* be fully available, since this style of relationship does not rely upon other possibly-not-configured mappers to know that they exist. For an event that is guaranteed to have **all** mappers ready to go including backrefs that are defined only on other mappings, use the :meth:`.MapperEvents.after_configured` event; this event invokes only after all known mappings have been fully configured. The :meth:`.MapperEvents.mapper_configured` event, unlike :meth:`.MapperEvents.before_configured` or :meth:`.MapperEvents.after_configured`, is called for each mapper/class individually, and the mapper is passed to the event itself. It also is called exactly once for a particular mapper. The event is therefore useful for configurational steps that benefit from being invoked just once on a specific mapper basis, which don't require that "backref" configurations are necessarily ready yet. :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param class\_: the mapped class. .. seealso:: :meth:`.MapperEvents.before_configured` :meth:`.MapperEvents.after_configured` :meth:`.MapperEvents.before_mapper_configured`
@util.preload_module(
def _accept_with(cls, target:
Union[, identifier: str) -> Optional[:
(source)
¶
Undocumented
def _listen(cls, event_key:
_EventKey[, raw: bool = False, retval: bool = False, propagate: bool = False, **kw: Any):
(source)
¶
sqlalchemy.event.base.Events._listenUndocumented
def _new_mapper_instance(cls, class_:
Union[, mapper: Mapper[):
(source)
¶
Undocumented