Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/sqlalchemy/orm/events.py: 56%
368 statements
« prev ^ index » next coverage.py v7.0.1, created at 2022-12-25 06:11 +0000
1# orm/events.py
2# Copyright (C) 2005-2022 the SQLAlchemy authors and contributors
3# <see AUTHORS file>
4#
5# This module is part of SQLAlchemy and is released under
6# the MIT License: https://www.opensource.org/licenses/mit-license.php
8"""ORM event interfaces.
10"""
11import weakref
13from . import instrumentation
14from . import interfaces
15from . import mapperlib
16from .attributes import QueryableAttribute
17from .base import _mapper_or_none
18from .query import Query
19from .scoping import scoped_session
20from .session import Session
21from .session import sessionmaker
22from .. import event
23from .. import exc
24from .. import util
25from ..util.compat import inspect_getfullargspec
28class InstrumentationEvents(event.Events):
29 """Events related to class instrumentation events.
31 The listeners here support being established against
32 any new style class, that is any object that is a subclass
33 of 'type'. Events will then be fired off for events
34 against that class. If the "propagate=True" flag is passed
35 to event.listen(), the event will fire off for subclasses
36 of that class as well.
38 The Python ``type`` builtin is also accepted as a target,
39 which when used has the effect of events being emitted
40 for all classes.
42 Note the "propagate" flag here is defaulted to ``True``,
43 unlike the other class level events where it defaults
44 to ``False``. This means that new subclasses will also
45 be the subject of these events, when a listener
46 is established on a superclass.
48 """
50 _target_class_doc = "SomeBaseClass"
51 _dispatch_target = instrumentation.InstrumentationFactory
53 @classmethod
54 def _accept_with(cls, target):
55 if isinstance(target, type):
56 return _InstrumentationEventsHold(target)
57 else:
58 return None
60 @classmethod
61 def _listen(cls, event_key, propagate=True, **kw):
62 target, identifier, fn = (
63 event_key.dispatch_target,
64 event_key.identifier,
65 event_key._listen_fn,
66 )
68 def listen(target_cls, *arg):
69 listen_cls = target()
71 # if weakref were collected, however this is not something
72 # that normally happens. it was occurring during test teardown
73 # between mapper/registry/instrumentation_manager, however this
74 # interaction was changed to not rely upon the event system.
75 if listen_cls is None:
76 return None
78 if propagate and issubclass(target_cls, listen_cls):
79 return fn(target_cls, *arg)
80 elif not propagate and target_cls is listen_cls:
81 return fn(target_cls, *arg)
83 def remove(ref):
84 key = event.registry._EventKey(
85 None,
86 identifier,
87 listen,
88 instrumentation._instrumentation_factory,
89 )
90 getattr(
91 instrumentation._instrumentation_factory.dispatch, identifier
92 ).remove(key)
94 target = weakref.ref(target.class_, remove)
96 event_key.with_dispatch_target(
97 instrumentation._instrumentation_factory
98 ).with_wrapper(listen).base_listen(**kw)
100 @classmethod
101 def _clear(cls):
102 super(InstrumentationEvents, cls)._clear()
103 instrumentation._instrumentation_factory.dispatch._clear()
105 def class_instrument(self, cls):
106 """Called after the given class is instrumented.
108 To get at the :class:`.ClassManager`, use
109 :func:`.manager_of_class`.
111 """
113 def class_uninstrument(self, cls):
114 """Called before the given class is uninstrumented.
116 To get at the :class:`.ClassManager`, use
117 :func:`.manager_of_class`.
119 """
121 def attribute_instrument(self, cls, key, inst):
122 """Called when an attribute is instrumented."""
125class _InstrumentationEventsHold(object):
126 """temporary marker object used to transfer from _accept_with() to
127 _listen() on the InstrumentationEvents class.
129 """
131 def __init__(self, class_):
132 self.class_ = class_
134 dispatch = event.dispatcher(InstrumentationEvents)
137class InstanceEvents(event.Events):
138 """Define events specific to object lifecycle.
140 e.g.::
142 from sqlalchemy import event
144 def my_load_listener(target, context):
145 print("on load!")
147 event.listen(SomeClass, 'load', my_load_listener)
149 Available targets include:
151 * mapped classes
152 * unmapped superclasses of mapped or to-be-mapped classes
153 (using the ``propagate=True`` flag)
154 * :class:`_orm.Mapper` objects
155 * the :class:`_orm.Mapper` class itself and the :func:`.mapper`
156 function indicate listening for all mappers.
158 Instance events are closely related to mapper events, but
159 are more specific to the instance and its instrumentation,
160 rather than its system of persistence.
162 When using :class:`.InstanceEvents`, several modifiers are
163 available to the :func:`.event.listen` function.
165 :param propagate=False: When True, the event listener should
166 be applied to all inheriting classes as well as the
167 class which is the target of this listener.
168 :param raw=False: When True, the "target" argument passed
169 to applicable event listener functions will be the
170 instance's :class:`.InstanceState` management
171 object, rather than the mapped instance itself.
172 :param restore_load_context=False: Applies to the
173 :meth:`.InstanceEvents.load` and :meth:`.InstanceEvents.refresh`
174 events. Restores the loader context of the object when the event
175 hook is complete, so that ongoing eager load operations continue
176 to target the object appropriately. A warning is emitted if the
177 object is moved to a new loader context from within one of these
178 events if this flag is not set.
180 .. versionadded:: 1.3.14
183 """
185 _target_class_doc = "SomeClass"
187 _dispatch_target = instrumentation.ClassManager
189 @classmethod
190 def _new_classmanager_instance(cls, class_, classmanager):
191 _InstanceEventsHold.populate(class_, classmanager)
193 @classmethod
194 @util.preload_module("sqlalchemy.orm")
195 def _accept_with(cls, target):
196 orm = util.preloaded.orm
198 if isinstance(target, instrumentation.ClassManager):
199 return target
200 elif isinstance(target, mapperlib.Mapper):
201 return target.class_manager
202 elif target is orm.mapper:
203 return instrumentation.ClassManager
204 elif isinstance(target, type):
205 if issubclass(target, mapperlib.Mapper):
206 return instrumentation.ClassManager
207 else:
208 manager = instrumentation.manager_of_class(target)
209 if manager:
210 return manager
211 else:
212 return _InstanceEventsHold(target)
213 return None
215 @classmethod
216 def _listen(
217 cls,
218 event_key,
219 raw=False,
220 propagate=False,
221 restore_load_context=False,
222 **kw
223 ):
224 target, fn = (event_key.dispatch_target, event_key._listen_fn)
226 if not raw or restore_load_context:
228 def wrap(state, *arg, **kw):
229 if not raw:
230 target = state.obj()
231 else:
232 target = state
233 if restore_load_context:
234 runid = state.runid
235 try:
236 return fn(target, *arg, **kw)
237 finally:
238 if restore_load_context:
239 state.runid = runid
241 event_key = event_key.with_wrapper(wrap)
243 event_key.base_listen(propagate=propagate, **kw)
245 if propagate:
246 for mgr in target.subclass_managers(True):
247 event_key.with_dispatch_target(mgr).base_listen(propagate=True)
249 @classmethod
250 def _clear(cls):
251 super(InstanceEvents, cls)._clear()
252 _InstanceEventsHold._clear()
254 def first_init(self, manager, cls):
255 """Called when the first instance of a particular mapping is called.
257 This event is called when the ``__init__`` method of a class
258 is called the first time for that particular class. The event
259 invokes before ``__init__`` actually proceeds as well as before
260 the :meth:`.InstanceEvents.init` event is invoked.
262 """
264 def init(self, target, args, kwargs):
265 """Receive an instance when its constructor is called.
267 This method is only called during a userland construction of
268 an object, in conjunction with the object's constructor, e.g.
269 its ``__init__`` method. It is not called when an object is
270 loaded from the database; see the :meth:`.InstanceEvents.load`
271 event in order to intercept a database load.
273 The event is called before the actual ``__init__`` constructor
274 of the object is called. The ``kwargs`` dictionary may be
275 modified in-place in order to affect what is passed to
276 ``__init__``.
278 :param target: the mapped instance. If
279 the event is configured with ``raw=True``, this will
280 instead be the :class:`.InstanceState` state-management
281 object associated with the instance.
282 :param args: positional arguments passed to the ``__init__`` method.
283 This is passed as a tuple and is currently immutable.
284 :param kwargs: keyword arguments passed to the ``__init__`` method.
285 This structure *can* be altered in place.
287 .. seealso::
289 :meth:`.InstanceEvents.init_failure`
291 :meth:`.InstanceEvents.load`
293 """
295 def init_failure(self, target, args, kwargs):
296 """Receive an instance when its constructor has been called,
297 and raised an exception.
299 This method is only called during a userland construction of
300 an object, in conjunction with the object's constructor, e.g.
301 its ``__init__`` method. It is not called when an object is loaded
302 from the database.
304 The event is invoked after an exception raised by the ``__init__``
305 method is caught. After the event
306 is invoked, the original exception is re-raised outwards, so that
307 the construction of the object still raises an exception. The
308 actual exception and stack trace raised should be present in
309 ``sys.exc_info()``.
311 :param target: the mapped instance. If
312 the event is configured with ``raw=True``, this will
313 instead be the :class:`.InstanceState` state-management
314 object associated with the instance.
315 :param args: positional arguments that were passed to the ``__init__``
316 method.
317 :param kwargs: keyword arguments that were passed to the ``__init__``
318 method.
320 .. seealso::
322 :meth:`.InstanceEvents.init`
324 :meth:`.InstanceEvents.load`
326 """
328 def _sa_event_merge_wo_load(self, target, context):
329 """receive an object instance after it was the subject of a merge()
330 call, when load=False was passed.
332 The target would be the already-loaded object in the Session which
333 would have had its attributes overwritten by the incoming object. This
334 overwrite operation does not use attribute events, instead just
335 populating dict directly. Therefore the purpose of this event is so
336 that extensions like sqlalchemy.ext.mutable know that object state has
337 changed and incoming state needs to be set up for "parents" etc.
339 This functionality is acceptable to be made public in a later release.
341 .. versionadded:: 1.4.41
343 """
345 def load(self, target, context):
346 """Receive an object instance after it has been created via
347 ``__new__``, and after initial attribute population has
348 occurred.
350 This typically occurs when the instance is created based on
351 incoming result rows, and is only called once for that
352 instance's lifetime.
354 .. warning::
356 During a result-row load, this event is invoked when the
357 first row received for this instance is processed. When using
358 eager loading with collection-oriented attributes, the additional
359 rows that are to be loaded / processed in order to load subsequent
360 collection items have not occurred yet. This has the effect
361 both that collections will not be fully loaded, as well as that
362 if an operation occurs within this event handler that emits
363 another database load operation for the object, the "loading
364 context" for the object can change and interfere with the
365 existing eager loaders still in progress.
367 Examples of what can cause the "loading context" to change within
368 the event handler include, but are not necessarily limited to:
370 * accessing deferred attributes that weren't part of the row,
371 will trigger an "undefer" operation and refresh the object
373 * accessing attributes on a joined-inheritance subclass that
374 weren't part of the row, will trigger a refresh operation.
376 As of SQLAlchemy 1.3.14, a warning is emitted when this occurs. The
377 :paramref:`.InstanceEvents.restore_load_context` option may be
378 used on the event to prevent this warning; this will ensure that
379 the existing loading context is maintained for the object after the
380 event is called::
382 @event.listens_for(
383 SomeClass, "load", restore_load_context=True)
384 def on_load(instance, context):
385 instance.some_unloaded_attribute
387 .. versionchanged:: 1.3.14 Added
388 :paramref:`.InstanceEvents.restore_load_context`
389 and :paramref:`.SessionEvents.restore_load_context` flags which
390 apply to "on load" events, which will ensure that the loading
391 context for an object is restored when the event hook is
392 complete; a warning is emitted if the load context of the object
393 changes without this flag being set.
396 The :meth:`.InstanceEvents.load` event is also available in a
397 class-method decorator format called :func:`_orm.reconstructor`.
399 :param target: the mapped instance. If
400 the event is configured with ``raw=True``, this will
401 instead be the :class:`.InstanceState` state-management
402 object associated with the instance.
403 :param context: the :class:`.QueryContext` corresponding to the
404 current :class:`_query.Query` in progress. This argument may be
405 ``None`` if the load does not correspond to a :class:`_query.Query`,
406 such as during :meth:`.Session.merge`.
408 .. seealso::
410 :meth:`.InstanceEvents.init`
412 :meth:`.InstanceEvents.refresh`
414 :meth:`.SessionEvents.loaded_as_persistent`
416 :ref:`mapping_constructors`
418 """
420 def refresh(self, target, context, attrs):
421 """Receive an object instance after one or more attributes have
422 been refreshed from a query.
424 Contrast this to the :meth:`.InstanceEvents.load` method, which
425 is invoked when the object is first loaded from a query.
427 .. note:: This event is invoked within the loader process before
428 eager loaders may have been completed, and the object's state may
429 not be complete. Additionally, invoking row-level refresh
430 operations on the object will place the object into a new loader
431 context, interfering with the existing load context. See the note
432 on :meth:`.InstanceEvents.load` for background on making use of the
433 :paramref:`.InstanceEvents.restore_load_context` parameter, in
434 order to resolve this scenario.
436 :param target: the mapped instance. If
437 the event is configured with ``raw=True``, this will
438 instead be the :class:`.InstanceState` state-management
439 object associated with the instance.
440 :param context: the :class:`.QueryContext` corresponding to the
441 current :class:`_query.Query` in progress.
442 :param attrs: sequence of attribute names which
443 were populated, or None if all column-mapped, non-deferred
444 attributes were populated.
446 .. seealso::
448 :meth:`.InstanceEvents.load`
450 """
452 def refresh_flush(self, target, flush_context, attrs):
453 """Receive an object instance after one or more attributes that
454 contain a column-level default or onupdate handler have been refreshed
455 during persistence of the object's state.
457 This event is the same as :meth:`.InstanceEvents.refresh` except
458 it is invoked within the unit of work flush process, and includes
459 only non-primary-key columns that have column level default or
460 onupdate handlers, including Python callables as well as server side
461 defaults and triggers which may be fetched via the RETURNING clause.
463 .. note::
465 While the :meth:`.InstanceEvents.refresh_flush` event is triggered
466 for an object that was INSERTed as well as for an object that was
467 UPDATEd, the event is geared primarily towards the UPDATE process;
468 it is mostly an internal artifact that INSERT actions can also
469 trigger this event, and note that **primary key columns for an
470 INSERTed row are explicitly omitted** from this event. In order to
471 intercept the newly INSERTed state of an object, the
472 :meth:`.SessionEvents.pending_to_persistent` and
473 :meth:`.MapperEvents.after_insert` are better choices.
475 .. versionadded:: 1.0.5
477 :param target: the mapped instance. If
478 the event is configured with ``raw=True``, this will
479 instead be the :class:`.InstanceState` state-management
480 object associated with the instance.
481 :param flush_context: Internal :class:`.UOWTransaction` object
482 which handles the details of the flush.
483 :param attrs: sequence of attribute names which
484 were populated.
486 .. seealso::
488 :ref:`orm_server_defaults`
490 :ref:`metadata_defaults_toplevel`
492 """
494 def expire(self, target, attrs):
495 """Receive an object instance after its attributes or some subset
496 have been expired.
498 'keys' is a list of attribute names. If None, the entire
499 state was expired.
501 :param target: the mapped instance. If
502 the event is configured with ``raw=True``, this will
503 instead be the :class:`.InstanceState` state-management
504 object associated with the instance.
505 :param attrs: sequence of attribute
506 names which were expired, or None if all attributes were
507 expired.
509 """
511 def pickle(self, target, state_dict):
512 """Receive an object instance when its associated state is
513 being pickled.
515 :param target: the mapped instance. If
516 the event is configured with ``raw=True``, this will
517 instead be the :class:`.InstanceState` state-management
518 object associated with the instance.
519 :param state_dict: the dictionary returned by
520 :class:`.InstanceState.__getstate__`, containing the state
521 to be pickled.
523 """
525 def unpickle(self, target, state_dict):
526 """Receive an object instance after its associated state has
527 been unpickled.
529 :param target: the mapped instance. If
530 the event is configured with ``raw=True``, this will
531 instead be the :class:`.InstanceState` state-management
532 object associated with the instance.
533 :param state_dict: the dictionary sent to
534 :class:`.InstanceState.__setstate__`, containing the state
535 dictionary which was pickled.
537 """
540class _EventsHold(event.RefCollection):
541 """Hold onto listeners against unmapped, uninstrumented classes.
543 Establish _listen() for that class' mapper/instrumentation when
544 those objects are created for that class.
546 """
548 def __init__(self, class_):
549 self.class_ = class_
551 @classmethod
552 def _clear(cls):
553 cls.all_holds.clear()
555 class HoldEvents(object):
556 _dispatch_target = None
558 @classmethod
559 def _listen(
560 cls, event_key, raw=False, propagate=False, retval=False, **kw
561 ):
562 target = event_key.dispatch_target
564 if target.class_ in target.all_holds:
565 collection = target.all_holds[target.class_]
566 else:
567 collection = target.all_holds[target.class_] = {}
569 event.registry._stored_in_collection(event_key, target)
570 collection[event_key._key] = (
571 event_key,
572 raw,
573 propagate,
574 retval,
575 kw,
576 )
578 if propagate:
579 stack = list(target.class_.__subclasses__())
580 while stack:
581 subclass = stack.pop(0)
582 stack.extend(subclass.__subclasses__())
583 subject = target.resolve(subclass)
584 if subject is not None:
585 # we are already going through __subclasses__()
586 # so leave generic propagate flag False
587 event_key.with_dispatch_target(subject).listen(
588 raw=raw, propagate=False, retval=retval, **kw
589 )
591 def remove(self, event_key):
592 target = event_key.dispatch_target
594 if isinstance(target, _EventsHold):
595 collection = target.all_holds[target.class_]
596 del collection[event_key._key]
598 @classmethod
599 def populate(cls, class_, subject):
600 for subclass in class_.__mro__:
601 if subclass in cls.all_holds:
602 collection = cls.all_holds[subclass]
603 for (
604 event_key,
605 raw,
606 propagate,
607 retval,
608 kw,
609 ) in collection.values():
610 if propagate or subclass is class_:
611 # since we can't be sure in what order different
612 # classes in a hierarchy are triggered with
613 # populate(), we rely upon _EventsHold for all event
614 # assignment, instead of using the generic propagate
615 # flag.
616 event_key.with_dispatch_target(subject).listen(
617 raw=raw, propagate=False, retval=retval, **kw
618 )
621class _InstanceEventsHold(_EventsHold):
622 all_holds = weakref.WeakKeyDictionary()
624 def resolve(self, class_):
625 return instrumentation.manager_of_class(class_)
627 class HoldInstanceEvents(_EventsHold.HoldEvents, InstanceEvents):
628 pass
630 dispatch = event.dispatcher(HoldInstanceEvents)
633class MapperEvents(event.Events):
634 """Define events specific to mappings.
636 e.g.::
638 from sqlalchemy import event
640 def my_before_insert_listener(mapper, connection, target):
641 # execute a stored procedure upon INSERT,
642 # apply the value to the row to be inserted
643 target.calculated_value = connection.execute(
644 text("select my_special_function(%d)" % target.special_number)
645 ).scalar()
647 # associate the listener function with SomeClass,
648 # to execute during the "before_insert" hook
649 event.listen(
650 SomeClass, 'before_insert', my_before_insert_listener)
652 Available targets include:
654 * mapped classes
655 * unmapped superclasses of mapped or to-be-mapped classes
656 (using the ``propagate=True`` flag)
657 * :class:`_orm.Mapper` objects
658 * the :class:`_orm.Mapper` class itself and the :func:`.mapper`
659 function indicate listening for all mappers.
661 Mapper events provide hooks into critical sections of the
662 mapper, including those related to object instrumentation,
663 object loading, and object persistence. In particular, the
664 persistence methods :meth:`~.MapperEvents.before_insert`,
665 and :meth:`~.MapperEvents.before_update` are popular
666 places to augment the state being persisted - however, these
667 methods operate with several significant restrictions. The
668 user is encouraged to evaluate the
669 :meth:`.SessionEvents.before_flush` and
670 :meth:`.SessionEvents.after_flush` methods as more
671 flexible and user-friendly hooks in which to apply
672 additional database state during a flush.
674 When using :class:`.MapperEvents`, several modifiers are
675 available to the :func:`.event.listen` function.
677 :param propagate=False: When True, the event listener should
678 be applied to all inheriting mappers and/or the mappers of
679 inheriting classes, as well as any
680 mapper which is the target of this listener.
681 :param raw=False: When True, the "target" argument passed
682 to applicable event listener functions will be the
683 instance's :class:`.InstanceState` management
684 object, rather than the mapped instance itself.
685 :param retval=False: when True, the user-defined event function
686 must have a return value, the purpose of which is either to
687 control subsequent event propagation, or to otherwise alter
688 the operation in progress by the mapper. Possible return
689 values are:
691 * ``sqlalchemy.orm.interfaces.EXT_CONTINUE`` - continue event
692 processing normally.
693 * ``sqlalchemy.orm.interfaces.EXT_STOP`` - cancel all subsequent
694 event handlers in the chain.
695 * other values - the return value specified by specific listeners.
697 """
699 _target_class_doc = "SomeClass"
700 _dispatch_target = mapperlib.Mapper
702 @classmethod
703 def _new_mapper_instance(cls, class_, mapper):
704 _MapperEventsHold.populate(class_, mapper)
706 @classmethod
707 @util.preload_module("sqlalchemy.orm")
708 def _accept_with(cls, target):
709 orm = util.preloaded.orm
711 if target is orm.mapper:
712 return mapperlib.Mapper
713 elif isinstance(target, type):
714 if issubclass(target, mapperlib.Mapper):
715 return target
716 else:
717 mapper = _mapper_or_none(target)
718 if mapper is not None:
719 return mapper
720 else:
721 return _MapperEventsHold(target)
722 else:
723 return target
725 @classmethod
726 def _listen(
727 cls, event_key, raw=False, retval=False, propagate=False, **kw
728 ):
729 target, identifier, fn = (
730 event_key.dispatch_target,
731 event_key.identifier,
732 event_key._listen_fn,
733 )
735 if (
736 identifier in ("before_configured", "after_configured")
737 and target is not mapperlib.Mapper
738 ):
739 util.warn(
740 "'before_configured' and 'after_configured' ORM events "
741 "only invoke with the mapper() function or Mapper class "
742 "as the target."
743 )
745 if not raw or not retval:
746 if not raw:
747 meth = getattr(cls, identifier)
748 try:
749 target_index = (
750 inspect_getfullargspec(meth)[0].index("target") - 1
751 )
752 except ValueError:
753 target_index = None
755 def wrap(*arg, **kw):
756 if not raw and target_index is not None:
757 arg = list(arg)
758 arg[target_index] = arg[target_index].obj()
759 if not retval:
760 fn(*arg, **kw)
761 return interfaces.EXT_CONTINUE
762 else:
763 return fn(*arg, **kw)
765 event_key = event_key.with_wrapper(wrap)
767 if propagate:
768 for mapper in target.self_and_descendants:
769 event_key.with_dispatch_target(mapper).base_listen(
770 propagate=True, **kw
771 )
772 else:
773 event_key.base_listen(**kw)
775 @classmethod
776 def _clear(cls):
777 super(MapperEvents, cls)._clear()
778 _MapperEventsHold._clear()
780 def instrument_class(self, mapper, class_):
781 r"""Receive a class when the mapper is first constructed,
782 before instrumentation is applied to the mapped class.
784 This event is the earliest phase of mapper construction.
785 Most attributes of the mapper are not yet initialized.
787 This listener can either be applied to the :class:`_orm.Mapper`
788 class overall, or to any un-mapped class which serves as a base
789 for classes that will be mapped (using the ``propagate=True`` flag)::
791 Base = declarative_base()
793 @event.listens_for(Base, "instrument_class", propagate=True)
794 def on_new_class(mapper, cls_):
795 " ... "
797 :param mapper: the :class:`_orm.Mapper` which is the target
798 of this event.
799 :param class\_: the mapped class.
801 """
803 def before_mapper_configured(self, mapper, class_):
804 """Called right before a specific mapper is to be configured.
806 This event is intended to allow a specific mapper to be skipped during
807 the configure step, by returning the :attr:`.orm.interfaces.EXT_SKIP`
808 symbol which indicates to the :func:`.configure_mappers` call that this
809 particular mapper (or hierarchy of mappers, if ``propagate=True`` is
810 used) should be skipped in the current configuration run. When one or
811 more mappers are skipped, the he "new mappers" flag will remain set,
812 meaning the :func:`.configure_mappers` function will continue to be
813 called when mappers are used, to continue to try to configure all
814 available mappers.
816 In comparison to the other configure-level events,
817 :meth:`.MapperEvents.before_configured`,
818 :meth:`.MapperEvents.after_configured`, and
819 :meth:`.MapperEvents.mapper_configured`, the
820 :meth;`.MapperEvents.before_mapper_configured` event provides for a
821 meaningful return value when it is registered with the ``retval=True``
822 parameter.
824 .. versionadded:: 1.3
826 e.g.::
828 from sqlalchemy.orm import EXT_SKIP
830 Base = declarative_base()
832 DontConfigureBase = declarative_base()
834 @event.listens_for(
835 DontConfigureBase,
836 "before_mapper_configured", retval=True, propagate=True)
837 def dont_configure(mapper, cls):
838 return EXT_SKIP
841 .. seealso::
843 :meth:`.MapperEvents.before_configured`
845 :meth:`.MapperEvents.after_configured`
847 :meth:`.MapperEvents.mapper_configured`
849 """
851 def mapper_configured(self, mapper, class_):
852 r"""Called when a specific mapper has completed its own configuration
853 within the scope of the :func:`.configure_mappers` call.
855 The :meth:`.MapperEvents.mapper_configured` event is invoked
856 for each mapper that is encountered when the
857 :func:`_orm.configure_mappers` function proceeds through the current
858 list of not-yet-configured mappers.
859 :func:`_orm.configure_mappers` is typically invoked
860 automatically as mappings are first used, as well as each time
861 new mappers have been made available and new mapper use is
862 detected.
864 When the event is called, the mapper should be in its final
865 state, but **not including backrefs** that may be invoked from
866 other mappers; they might still be pending within the
867 configuration operation. Bidirectional relationships that
868 are instead configured via the
869 :paramref:`.orm.relationship.back_populates` argument
870 *will* be fully available, since this style of relationship does not
871 rely upon other possibly-not-configured mappers to know that they
872 exist.
874 For an event that is guaranteed to have **all** mappers ready
875 to go including backrefs that are defined only on other
876 mappings, use the :meth:`.MapperEvents.after_configured`
877 event; this event invokes only after all known mappings have been
878 fully configured.
880 The :meth:`.MapperEvents.mapper_configured` event, unlike
881 :meth:`.MapperEvents.before_configured` or
882 :meth:`.MapperEvents.after_configured`,
883 is called for each mapper/class individually, and the mapper is
884 passed to the event itself. It also is called exactly once for
885 a particular mapper. The event is therefore useful for
886 configurational steps that benefit from being invoked just once
887 on a specific mapper basis, which don't require that "backref"
888 configurations are necessarily ready yet.
890 :param mapper: the :class:`_orm.Mapper` which is the target
891 of this event.
892 :param class\_: the mapped class.
894 .. seealso::
896 :meth:`.MapperEvents.before_configured`
898 :meth:`.MapperEvents.after_configured`
900 :meth:`.MapperEvents.before_mapper_configured`
902 """
903 # TODO: need coverage for this event
905 def before_configured(self):
906 """Called before a series of mappers have been configured.
908 The :meth:`.MapperEvents.before_configured` event is invoked
909 each time the :func:`_orm.configure_mappers` function is
910 invoked, before the function has done any of its work.
911 :func:`_orm.configure_mappers` is typically invoked
912 automatically as mappings are first used, as well as each time
913 new mappers have been made available and new mapper use is
914 detected.
916 This event can **only** be applied to the :class:`_orm.Mapper` class
917 or :func:`.mapper` function, and not to individual mappings or
918 mapped classes. It is only invoked for all mappings as a whole::
920 from sqlalchemy.orm import mapper
922 @event.listens_for(mapper, "before_configured")
923 def go():
924 # ...
926 Contrast this event to :meth:`.MapperEvents.after_configured`,
927 which is invoked after the series of mappers has been configured,
928 as well as :meth:`.MapperEvents.before_mapper_configured`
929 and :meth:`.MapperEvents.mapper_configured`, which are both invoked
930 on a per-mapper basis.
932 Theoretically this event is called once per
933 application, but is actually called any time new mappers
934 are to be affected by a :func:`_orm.configure_mappers`
935 call. If new mappings are constructed after existing ones have
936 already been used, this event will likely be called again. To ensure
937 that a particular event is only called once and no further, the
938 ``once=True`` argument (new in 0.9.4) can be applied::
940 from sqlalchemy.orm import mapper
942 @event.listens_for(mapper, "before_configured", once=True)
943 def go():
944 # ...
947 .. versionadded:: 0.9.3
950 .. seealso::
952 :meth:`.MapperEvents.before_mapper_configured`
954 :meth:`.MapperEvents.mapper_configured`
956 :meth:`.MapperEvents.after_configured`
958 """
960 def after_configured(self):
961 """Called after a series of mappers have been configured.
963 The :meth:`.MapperEvents.after_configured` event is invoked
964 each time the :func:`_orm.configure_mappers` function is
965 invoked, after the function has completed its work.
966 :func:`_orm.configure_mappers` is typically invoked
967 automatically as mappings are first used, as well as each time
968 new mappers have been made available and new mapper use is
969 detected.
971 Contrast this event to the :meth:`.MapperEvents.mapper_configured`
972 event, which is called on a per-mapper basis while the configuration
973 operation proceeds; unlike that event, when this event is invoked,
974 all cross-configurations (e.g. backrefs) will also have been made
975 available for any mappers that were pending.
976 Also contrast to :meth:`.MapperEvents.before_configured`,
977 which is invoked before the series of mappers has been configured.
979 This event can **only** be applied to the :class:`_orm.Mapper` class
980 or :func:`.mapper` function, and not to individual mappings or
981 mapped classes. It is only invoked for all mappings as a whole::
983 from sqlalchemy.orm import mapper
985 @event.listens_for(mapper, "after_configured")
986 def go():
987 # ...
989 Theoretically this event is called once per
990 application, but is actually called any time new mappers
991 have been affected by a :func:`_orm.configure_mappers`
992 call. If new mappings are constructed after existing ones have
993 already been used, this event will likely be called again. To ensure
994 that a particular event is only called once and no further, the
995 ``once=True`` argument (new in 0.9.4) can be applied::
997 from sqlalchemy.orm import mapper
999 @event.listens_for(mapper, "after_configured", once=True)
1000 def go():
1001 # ...
1003 .. seealso::
1005 :meth:`.MapperEvents.before_mapper_configured`
1007 :meth:`.MapperEvents.mapper_configured`
1009 :meth:`.MapperEvents.before_configured`
1011 """
1013 def before_insert(self, mapper, connection, target):
1014 """Receive an object instance before an INSERT statement
1015 is emitted corresponding to that instance.
1017 This event is used to modify local, non-object related
1018 attributes on the instance before an INSERT occurs, as well
1019 as to emit additional SQL statements on the given
1020 connection.
1022 The event is often called for a batch of objects of the
1023 same class before their INSERT statements are emitted at
1024 once in a later step. In the extremely rare case that
1025 this is not desirable, the :func:`.mapper` can be
1026 configured with ``batch=False``, which will cause
1027 batches of instances to be broken up into individual
1028 (and more poorly performing) event->persist->event
1029 steps.
1031 .. warning::
1033 Mapper-level flush events only allow **very limited operations**,
1034 on attributes local to the row being operated upon only,
1035 as well as allowing any SQL to be emitted on the given
1036 :class:`_engine.Connection`. **Please read fully** the notes
1037 at :ref:`session_persistence_mapper` for guidelines on using
1038 these methods; generally, the :meth:`.SessionEvents.before_flush`
1039 method should be preferred for general on-flush changes.
1041 :param mapper: the :class:`_orm.Mapper` which is the target
1042 of this event.
1043 :param connection: the :class:`_engine.Connection` being used to
1044 emit INSERT statements for this instance. This
1045 provides a handle into the current transaction on the
1046 target database specific to this instance.
1047 :param target: the mapped instance being persisted. If
1048 the event is configured with ``raw=True``, this will
1049 instead be the :class:`.InstanceState` state-management
1050 object associated with the instance.
1051 :return: No return value is supported by this event.
1053 .. seealso::
1055 :ref:`session_persistence_events`
1057 """
1059 def after_insert(self, mapper, connection, target):
1060 """Receive an object instance after an INSERT statement
1061 is emitted corresponding to that instance.
1063 This event is used to modify in-Python-only
1064 state on the instance after an INSERT occurs, as well
1065 as to emit additional SQL statements on the given
1066 connection.
1068 The event is often called for a batch of objects of the
1069 same class after their INSERT statements have been
1070 emitted at once in a previous step. In the extremely
1071 rare case that this is not desirable, the
1072 :func:`.mapper` can be configured with ``batch=False``,
1073 which will cause batches of instances to be broken up
1074 into individual (and more poorly performing)
1075 event->persist->event steps.
1077 .. warning::
1079 Mapper-level flush events only allow **very limited operations**,
1080 on attributes local to the row being operated upon only,
1081 as well as allowing any SQL to be emitted on the given
1082 :class:`_engine.Connection`. **Please read fully** the notes
1083 at :ref:`session_persistence_mapper` for guidelines on using
1084 these methods; generally, the :meth:`.SessionEvents.before_flush`
1085 method should be preferred for general on-flush changes.
1087 :param mapper: the :class:`_orm.Mapper` which is the target
1088 of this event.
1089 :param connection: the :class:`_engine.Connection` being used to
1090 emit INSERT statements for this instance. This
1091 provides a handle into the current transaction on the
1092 target database specific to this instance.
1093 :param target: the mapped instance being persisted. If
1094 the event is configured with ``raw=True``, this will
1095 instead be the :class:`.InstanceState` state-management
1096 object associated with the instance.
1097 :return: No return value is supported by this event.
1099 .. seealso::
1101 :ref:`session_persistence_events`
1103 """
1105 def before_update(self, mapper, connection, target):
1106 """Receive an object instance before an UPDATE statement
1107 is emitted corresponding to that instance.
1109 This event is used to modify local, non-object related
1110 attributes on the instance before an UPDATE occurs, as well
1111 as to emit additional SQL statements on the given
1112 connection.
1114 This method is called for all instances that are
1115 marked as "dirty", *even those which have no net changes
1116 to their column-based attributes*. An object is marked
1117 as dirty when any of its column-based attributes have a
1118 "set attribute" operation called or when any of its
1119 collections are modified. If, at update time, no
1120 column-based attributes have any net changes, no UPDATE
1121 statement will be issued. This means that an instance
1122 being sent to :meth:`~.MapperEvents.before_update` is
1123 *not* a guarantee that an UPDATE statement will be
1124 issued, although you can affect the outcome here by
1125 modifying attributes so that a net change in value does
1126 exist.
1128 To detect if the column-based attributes on the object have net
1129 changes, and will therefore generate an UPDATE statement, use
1130 ``object_session(instance).is_modified(instance,
1131 include_collections=False)``.
1133 The event is often called for a batch of objects of the
1134 same class before their UPDATE statements are emitted at
1135 once in a later step. In the extremely rare case that
1136 this is not desirable, the :func:`.mapper` can be
1137 configured with ``batch=False``, which will cause
1138 batches of instances to be broken up into individual
1139 (and more poorly performing) event->persist->event
1140 steps.
1142 .. warning::
1144 Mapper-level flush events only allow **very limited operations**,
1145 on attributes local to the row being operated upon only,
1146 as well as allowing any SQL to be emitted on the given
1147 :class:`_engine.Connection`. **Please read fully** the notes
1148 at :ref:`session_persistence_mapper` for guidelines on using
1149 these methods; generally, the :meth:`.SessionEvents.before_flush`
1150 method should be preferred for general on-flush changes.
1152 :param mapper: the :class:`_orm.Mapper` which is the target
1153 of this event.
1154 :param connection: the :class:`_engine.Connection` being used to
1155 emit UPDATE statements for this instance. This
1156 provides a handle into the current transaction on the
1157 target database specific to this instance.
1158 :param target: the mapped instance being persisted. If
1159 the event is configured with ``raw=True``, this will
1160 instead be the :class:`.InstanceState` state-management
1161 object associated with the instance.
1162 :return: No return value is supported by this event.
1164 .. seealso::
1166 :ref:`session_persistence_events`
1168 """
1170 def after_update(self, mapper, connection, target):
1171 """Receive an object instance after an UPDATE statement
1172 is emitted corresponding to that instance.
1174 This event is used to modify in-Python-only
1175 state on the instance after an UPDATE occurs, as well
1176 as to emit additional SQL statements on the given
1177 connection.
1179 This method is called for all instances that are
1180 marked as "dirty", *even those which have no net changes
1181 to their column-based attributes*, and for which
1182 no UPDATE statement has proceeded. An object is marked
1183 as dirty when any of its column-based attributes have a
1184 "set attribute" operation called or when any of its
1185 collections are modified. If, at update time, no
1186 column-based attributes have any net changes, no UPDATE
1187 statement will be issued. This means that an instance
1188 being sent to :meth:`~.MapperEvents.after_update` is
1189 *not* a guarantee that an UPDATE statement has been
1190 issued.
1192 To detect if the column-based attributes on the object have net
1193 changes, and therefore resulted in an UPDATE statement, use
1194 ``object_session(instance).is_modified(instance,
1195 include_collections=False)``.
1197 The event is often called for a batch of objects of the
1198 same class after their UPDATE statements have been emitted at
1199 once in a previous step. In the extremely rare case that
1200 this is not desirable, the :func:`.mapper` can be
1201 configured with ``batch=False``, which will cause
1202 batches of instances to be broken up into individual
1203 (and more poorly performing) event->persist->event
1204 steps.
1206 .. warning::
1208 Mapper-level flush events only allow **very limited operations**,
1209 on attributes local to the row being operated upon only,
1210 as well as allowing any SQL to be emitted on the given
1211 :class:`_engine.Connection`. **Please read fully** the notes
1212 at :ref:`session_persistence_mapper` for guidelines on using
1213 these methods; generally, the :meth:`.SessionEvents.before_flush`
1214 method should be preferred for general on-flush changes.
1216 :param mapper: the :class:`_orm.Mapper` which is the target
1217 of this event.
1218 :param connection: the :class:`_engine.Connection` being used to
1219 emit UPDATE statements for this instance. This
1220 provides a handle into the current transaction on the
1221 target database specific to this instance.
1222 :param target: the mapped instance being persisted. If
1223 the event is configured with ``raw=True``, this will
1224 instead be the :class:`.InstanceState` state-management
1225 object associated with the instance.
1226 :return: No return value is supported by this event.
1228 .. seealso::
1230 :ref:`session_persistence_events`
1232 """
1234 def before_delete(self, mapper, connection, target):
1235 """Receive an object instance before a DELETE statement
1236 is emitted corresponding to that instance.
1238 This event is used to emit additional SQL statements on
1239 the given connection as well as to perform application
1240 specific bookkeeping related to a deletion event.
1242 The event is often called for a batch of objects of the
1243 same class before their DELETE statements are emitted at
1244 once in a later step.
1246 .. warning::
1248 Mapper-level flush events only allow **very limited operations**,
1249 on attributes local to the row being operated upon only,
1250 as well as allowing any SQL to be emitted on the given
1251 :class:`_engine.Connection`. **Please read fully** the notes
1252 at :ref:`session_persistence_mapper` for guidelines on using
1253 these methods; generally, the :meth:`.SessionEvents.before_flush`
1254 method should be preferred for general on-flush changes.
1256 :param mapper: the :class:`_orm.Mapper` which is the target
1257 of this event.
1258 :param connection: the :class:`_engine.Connection` being used to
1259 emit DELETE statements for this instance. This
1260 provides a handle into the current transaction on the
1261 target database specific to this instance.
1262 :param target: the mapped instance being deleted. If
1263 the event is configured with ``raw=True``, this will
1264 instead be the :class:`.InstanceState` state-management
1265 object associated with the instance.
1266 :return: No return value is supported by this event.
1268 .. seealso::
1270 :ref:`session_persistence_events`
1272 """
1274 def after_delete(self, mapper, connection, target):
1275 """Receive an object instance after a DELETE statement
1276 has been emitted corresponding to that instance.
1278 This event is used to emit additional SQL statements on
1279 the given connection as well as to perform application
1280 specific bookkeeping related to a deletion event.
1282 The event is often called for a batch of objects of the
1283 same class after their DELETE statements have been emitted at
1284 once in a previous step.
1286 .. warning::
1288 Mapper-level flush events only allow **very limited operations**,
1289 on attributes local to the row being operated upon only,
1290 as well as allowing any SQL to be emitted on the given
1291 :class:`_engine.Connection`. **Please read fully** the notes
1292 at :ref:`session_persistence_mapper` for guidelines on using
1293 these methods; generally, the :meth:`.SessionEvents.before_flush`
1294 method should be preferred for general on-flush changes.
1296 :param mapper: the :class:`_orm.Mapper` which is the target
1297 of this event.
1298 :param connection: the :class:`_engine.Connection` being used to
1299 emit DELETE statements for this instance. This
1300 provides a handle into the current transaction on the
1301 target database specific to this instance.
1302 :param target: the mapped instance being deleted. If
1303 the event is configured with ``raw=True``, this will
1304 instead be the :class:`.InstanceState` state-management
1305 object associated with the instance.
1306 :return: No return value is supported by this event.
1308 .. seealso::
1310 :ref:`session_persistence_events`
1312 """
1315class _MapperEventsHold(_EventsHold):
1316 all_holds = weakref.WeakKeyDictionary()
1318 def resolve(self, class_):
1319 return _mapper_or_none(class_)
1321 class HoldMapperEvents(_EventsHold.HoldEvents, MapperEvents):
1322 pass
1324 dispatch = event.dispatcher(HoldMapperEvents)
1327_sessionevents_lifecycle_event_names = set()
1330class SessionEvents(event.Events):
1331 """Define events specific to :class:`.Session` lifecycle.
1333 e.g.::
1335 from sqlalchemy import event
1336 from sqlalchemy.orm import sessionmaker
1338 def my_before_commit(session):
1339 print("before commit!")
1341 Session = sessionmaker()
1343 event.listen(Session, "before_commit", my_before_commit)
1345 The :func:`~.event.listen` function will accept
1346 :class:`.Session` objects as well as the return result
1347 of :class:`~.sessionmaker()` and :class:`~.scoped_session()`.
1349 Additionally, it accepts the :class:`.Session` class which
1350 will apply listeners to all :class:`.Session` instances
1351 globally.
1353 :param raw=False: When True, the "target" argument passed
1354 to applicable event listener functions that work on individual
1355 objects will be the instance's :class:`.InstanceState` management
1356 object, rather than the mapped instance itself.
1358 .. versionadded:: 1.3.14
1360 :param restore_load_context=False: Applies to the
1361 :meth:`.SessionEvents.loaded_as_persistent` event. Restores the loader
1362 context of the object when the event hook is complete, so that ongoing
1363 eager load operations continue to target the object appropriately. A
1364 warning is emitted if the object is moved to a new loader context from
1365 within this event if this flag is not set.
1367 .. versionadded:: 1.3.14
1369 """
1371 _target_class_doc = "SomeSessionClassOrObject"
1373 _dispatch_target = Session
1375 def _lifecycle_event(fn):
1376 _sessionevents_lifecycle_event_names.add(fn.__name__)
1377 return fn
1379 @classmethod
1380 def _accept_with(cls, target):
1381 if isinstance(target, scoped_session):
1383 target = target.session_factory
1384 if not isinstance(target, sessionmaker) and (
1385 not isinstance(target, type) or not issubclass(target, Session)
1386 ):
1387 raise exc.ArgumentError(
1388 "Session event listen on a scoped_session "
1389 "requires that its creation callable "
1390 "is associated with the Session class."
1391 )
1393 if isinstance(target, sessionmaker):
1394 return target.class_
1395 elif isinstance(target, type):
1396 if issubclass(target, scoped_session):
1397 return Session
1398 elif issubclass(target, Session):
1399 return target
1400 elif isinstance(target, Session):
1401 return target
1402 else:
1403 # allows alternate SessionEvents-like-classes to be consulted
1404 return event.Events._accept_with(target)
1406 @classmethod
1407 def _listen(cls, event_key, raw=False, restore_load_context=False, **kw):
1408 is_instance_event = (
1409 event_key.identifier in _sessionevents_lifecycle_event_names
1410 )
1412 if is_instance_event:
1413 if not raw or restore_load_context:
1415 fn = event_key._listen_fn
1417 def wrap(session, state, *arg, **kw):
1418 if not raw:
1419 target = state.obj()
1420 if target is None:
1421 # existing behavior is that if the object is
1422 # garbage collected, no event is emitted
1423 return
1424 else:
1425 target = state
1426 if restore_load_context:
1427 runid = state.runid
1428 try:
1429 return fn(session, target, *arg, **kw)
1430 finally:
1431 if restore_load_context:
1432 state.runid = runid
1434 event_key = event_key.with_wrapper(wrap)
1436 event_key.base_listen(**kw)
1438 def do_orm_execute(self, orm_execute_state):
1439 """Intercept statement executions that occur on behalf of an
1440 ORM :class:`.Session` object.
1442 This event is invoked for all top-level SQL statements invoked from the
1443 :meth:`_orm.Session.execute` method, as well as related methods such as
1444 :meth:`_orm.Session.scalars` and :meth:`_orm.Session.scalar`. As of
1445 SQLAlchemy 1.4, all ORM queries emitted on behalf of a
1446 :class:`_orm.Session` will flow through this method, so this event hook
1447 provides the single point at which ORM queries of all types may be
1448 intercepted before they are invoked, and additionally to replace their
1449 execution with a different process.
1451 .. note:: The :meth:`_orm.SessionEvents.do_orm_execute` event hook
1452 is triggered **for ORM statement executions only**, meaning those
1453 invoked via the :meth:`_orm.Session.execute` and similar methods on
1454 the :class:`_orm.Session` object. It does **not** trigger for
1455 statements that are invoked by SQLAlchemy Core only, i.e. statements
1456 invoked directly using :meth:`_engine.Connection.execute` or
1457 otherwise originating from an :class:`_engine.Engine` object without
1458 any :class:`_orm.Session` involved. To intercept **all** SQL
1459 executions regardless of whether the Core or ORM APIs are in use,
1460 see the event hooks at
1461 :class:`.ConnectionEvents`, such as
1462 :meth:`.ConnectionEvents.before_execute` and
1463 :meth:`.ConnectionEvents.before_cursor_execute`.
1465 This event is a ``do_`` event, meaning it has the capability to replace
1466 the operation that the :meth:`_orm.Session.execute` method normally
1467 performs. The intended use for this includes sharding and
1468 result-caching schemes which may seek to invoke the same statement
1469 across multiple database connections, returning a result that is
1470 merged from each of them, or which don't invoke the statement at all,
1471 instead returning data from a cache.
1473 The hook intends to replace the use of the
1474 ``Query._execute_and_instances`` method that could be subclassed prior
1475 to SQLAlchemy 1.4.
1477 :param orm_execute_state: an instance of :class:`.ORMExecuteState`
1478 which contains all information about the current execution, as well
1479 as helper functions used to derive other commonly required
1480 information. See that object for details.
1482 .. seealso::
1484 :ref:`session_execute_events` - top level documentation on how
1485 to use :meth:`_orm.SessionEvents.do_orm_execute`
1487 :class:`.ORMExecuteState` - the object passed to the
1488 :meth:`_orm.SessionEvents.do_orm_execute` event which contains
1489 all information about the statement to be invoked. It also
1490 provides an interface to extend the current statement, options,
1491 and parameters as well as an option that allows programmatic
1492 invocation of the statement at any point.
1494 :ref:`examples_session_orm_events` - includes examples of using
1495 :meth:`_orm.SessionEvents.do_orm_execute`
1497 :ref:`examples_caching` - an example of how to integrate
1498 Dogpile caching with the ORM :class:`_orm.Session` making use
1499 of the :meth:`_orm.SessionEvents.do_orm_execute` event hook.
1501 :ref:`examples_sharding` - the Horizontal Sharding example /
1502 extension relies upon the
1503 :meth:`_orm.SessionEvents.do_orm_execute` event hook to invoke a
1504 SQL statement on multiple backends and return a merged result.
1507 .. versionadded:: 1.4
1509 """
1511 def after_transaction_create(self, session, transaction):
1512 """Execute when a new :class:`.SessionTransaction` is created.
1514 This event differs from :meth:`~.SessionEvents.after_begin`
1515 in that it occurs for each :class:`.SessionTransaction`
1516 overall, as opposed to when transactions are begun
1517 on individual database connections. It is also invoked
1518 for nested transactions and subtransactions, and is always
1519 matched by a corresponding
1520 :meth:`~.SessionEvents.after_transaction_end` event
1521 (assuming normal operation of the :class:`.Session`).
1523 :param session: the target :class:`.Session`.
1524 :param transaction: the target :class:`.SessionTransaction`.
1526 To detect if this is the outermost
1527 :class:`.SessionTransaction`, as opposed to a "subtransaction" or a
1528 SAVEPOINT, test that the :attr:`.SessionTransaction.parent` attribute
1529 is ``None``::
1531 @event.listens_for(session, "after_transaction_create")
1532 def after_transaction_create(session, transaction):
1533 if transaction.parent is None:
1534 # work with top-level transaction
1536 To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the
1537 :attr:`.SessionTransaction.nested` attribute::
1539 @event.listens_for(session, "after_transaction_create")
1540 def after_transaction_create(session, transaction):
1541 if transaction.nested:
1542 # work with SAVEPOINT transaction
1545 .. seealso::
1547 :class:`.SessionTransaction`
1549 :meth:`~.SessionEvents.after_transaction_end`
1551 """
1553 def after_transaction_end(self, session, transaction):
1554 """Execute when the span of a :class:`.SessionTransaction` ends.
1556 This event differs from :meth:`~.SessionEvents.after_commit`
1557 in that it corresponds to all :class:`.SessionTransaction`
1558 objects in use, including those for nested transactions
1559 and subtransactions, and is always matched by a corresponding
1560 :meth:`~.SessionEvents.after_transaction_create` event.
1562 :param session: the target :class:`.Session`.
1563 :param transaction: the target :class:`.SessionTransaction`.
1565 To detect if this is the outermost
1566 :class:`.SessionTransaction`, as opposed to a "subtransaction" or a
1567 SAVEPOINT, test that the :attr:`.SessionTransaction.parent` attribute
1568 is ``None``::
1570 @event.listens_for(session, "after_transaction_create")
1571 def after_transaction_end(session, transaction):
1572 if transaction.parent is None:
1573 # work with top-level transaction
1575 To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the
1576 :attr:`.SessionTransaction.nested` attribute::
1578 @event.listens_for(session, "after_transaction_create")
1579 def after_transaction_end(session, transaction):
1580 if transaction.nested:
1581 # work with SAVEPOINT transaction
1584 .. seealso::
1586 :class:`.SessionTransaction`
1588 :meth:`~.SessionEvents.after_transaction_create`
1590 """
1592 def before_commit(self, session):
1593 """Execute before commit is called.
1595 .. note::
1597 The :meth:`~.SessionEvents.before_commit` hook is *not* per-flush,
1598 that is, the :class:`.Session` can emit SQL to the database
1599 many times within the scope of a transaction.
1600 For interception of these events, use the
1601 :meth:`~.SessionEvents.before_flush`,
1602 :meth:`~.SessionEvents.after_flush`, or
1603 :meth:`~.SessionEvents.after_flush_postexec`
1604 events.
1606 :param session: The target :class:`.Session`.
1608 .. seealso::
1610 :meth:`~.SessionEvents.after_commit`
1612 :meth:`~.SessionEvents.after_begin`
1614 :meth:`~.SessionEvents.after_transaction_create`
1616 :meth:`~.SessionEvents.after_transaction_end`
1618 """
1620 def after_commit(self, session):
1621 """Execute after a commit has occurred.
1623 .. note::
1625 The :meth:`~.SessionEvents.after_commit` hook is *not* per-flush,
1626 that is, the :class:`.Session` can emit SQL to the database
1627 many times within the scope of a transaction.
1628 For interception of these events, use the
1629 :meth:`~.SessionEvents.before_flush`,
1630 :meth:`~.SessionEvents.after_flush`, or
1631 :meth:`~.SessionEvents.after_flush_postexec`
1632 events.
1634 .. note::
1636 The :class:`.Session` is not in an active transaction
1637 when the :meth:`~.SessionEvents.after_commit` event is invoked,
1638 and therefore can not emit SQL. To emit SQL corresponding to
1639 every transaction, use the :meth:`~.SessionEvents.before_commit`
1640 event.
1642 :param session: The target :class:`.Session`.
1644 .. seealso::
1646 :meth:`~.SessionEvents.before_commit`
1648 :meth:`~.SessionEvents.after_begin`
1650 :meth:`~.SessionEvents.after_transaction_create`
1652 :meth:`~.SessionEvents.after_transaction_end`
1654 """
1656 def after_rollback(self, session):
1657 """Execute after a real DBAPI rollback has occurred.
1659 Note that this event only fires when the *actual* rollback against
1660 the database occurs - it does *not* fire each time the
1661 :meth:`.Session.rollback` method is called, if the underlying
1662 DBAPI transaction has already been rolled back. In many
1663 cases, the :class:`.Session` will not be in
1664 an "active" state during this event, as the current
1665 transaction is not valid. To acquire a :class:`.Session`
1666 which is active after the outermost rollback has proceeded,
1667 use the :meth:`.SessionEvents.after_soft_rollback` event, checking the
1668 :attr:`.Session.is_active` flag.
1670 :param session: The target :class:`.Session`.
1672 """
1674 def after_soft_rollback(self, session, previous_transaction):
1675 """Execute after any rollback has occurred, including "soft"
1676 rollbacks that don't actually emit at the DBAPI level.
1678 This corresponds to both nested and outer rollbacks, i.e.
1679 the innermost rollback that calls the DBAPI's
1680 rollback() method, as well as the enclosing rollback
1681 calls that only pop themselves from the transaction stack.
1683 The given :class:`.Session` can be used to invoke SQL and
1684 :meth:`.Session.query` operations after an outermost rollback
1685 by first checking the :attr:`.Session.is_active` flag::
1687 @event.listens_for(Session, "after_soft_rollback")
1688 def do_something(session, previous_transaction):
1689 if session.is_active:
1690 session.execute("select * from some_table")
1692 :param session: The target :class:`.Session`.
1693 :param previous_transaction: The :class:`.SessionTransaction`
1694 transactional marker object which was just closed. The current
1695 :class:`.SessionTransaction` for the given :class:`.Session` is
1696 available via the :attr:`.Session.transaction` attribute.
1698 """
1700 def before_flush(self, session, flush_context, instances):
1701 """Execute before flush process has started.
1703 :param session: The target :class:`.Session`.
1704 :param flush_context: Internal :class:`.UOWTransaction` object
1705 which handles the details of the flush.
1706 :param instances: Usually ``None``, this is the collection of
1707 objects which can be passed to the :meth:`.Session.flush` method
1708 (note this usage is deprecated).
1710 .. seealso::
1712 :meth:`~.SessionEvents.after_flush`
1714 :meth:`~.SessionEvents.after_flush_postexec`
1716 :ref:`session_persistence_events`
1718 """
1720 def after_flush(self, session, flush_context):
1721 """Execute after flush has completed, but before commit has been
1722 called.
1724 Note that the session's state is still in pre-flush, i.e. 'new',
1725 'dirty', and 'deleted' lists still show pre-flush state as well
1726 as the history settings on instance attributes.
1728 .. warning:: This event runs after the :class:`.Session` has emitted
1729 SQL to modify the database, but **before** it has altered its
1730 internal state to reflect those changes, including that newly
1731 inserted objects are placed into the identity map. ORM operations
1732 emitted within this event such as loads of related items
1733 may produce new identity map entries that will immediately
1734 be replaced, sometimes causing confusing results. SQLAlchemy will
1735 emit a warning for this condition as of version 1.3.9.
1737 :param session: The target :class:`.Session`.
1738 :param flush_context: Internal :class:`.UOWTransaction` object
1739 which handles the details of the flush.
1741 .. seealso::
1743 :meth:`~.SessionEvents.before_flush`
1745 :meth:`~.SessionEvents.after_flush_postexec`
1747 :ref:`session_persistence_events`
1749 """
1751 def after_flush_postexec(self, session, flush_context):
1752 """Execute after flush has completed, and after the post-exec
1753 state occurs.
1755 This will be when the 'new', 'dirty', and 'deleted' lists are in
1756 their final state. An actual commit() may or may not have
1757 occurred, depending on whether or not the flush started its own
1758 transaction or participated in a larger transaction.
1760 :param session: The target :class:`.Session`.
1761 :param flush_context: Internal :class:`.UOWTransaction` object
1762 which handles the details of the flush.
1765 .. seealso::
1767 :meth:`~.SessionEvents.before_flush`
1769 :meth:`~.SessionEvents.after_flush`
1771 :ref:`session_persistence_events`
1773 """
1775 def after_begin(self, session, transaction, connection):
1776 """Execute after a transaction is begun on a connection
1778 :param session: The target :class:`.Session`.
1779 :param transaction: The :class:`.SessionTransaction`.
1780 :param connection: The :class:`_engine.Connection` object
1781 which will be used for SQL statements.
1783 .. seealso::
1785 :meth:`~.SessionEvents.before_commit`
1787 :meth:`~.SessionEvents.after_commit`
1789 :meth:`~.SessionEvents.after_transaction_create`
1791 :meth:`~.SessionEvents.after_transaction_end`
1793 """
1795 @_lifecycle_event
1796 def before_attach(self, session, instance):
1797 """Execute before an instance is attached to a session.
1799 This is called before an add, delete or merge causes
1800 the object to be part of the session.
1802 .. seealso::
1804 :meth:`~.SessionEvents.after_attach`
1806 :ref:`session_lifecycle_events`
1808 """
1810 @_lifecycle_event
1811 def after_attach(self, session, instance):
1812 """Execute after an instance is attached to a session.
1814 This is called after an add, delete or merge.
1816 .. note::
1818 As of 0.8, this event fires off *after* the item
1819 has been fully associated with the session, which is
1820 different than previous releases. For event
1821 handlers that require the object not yet
1822 be part of session state (such as handlers which
1823 may autoflush while the target object is not
1824 yet complete) consider the
1825 new :meth:`.before_attach` event.
1827 .. seealso::
1829 :meth:`~.SessionEvents.before_attach`
1831 :ref:`session_lifecycle_events`
1833 """
1835 @event._legacy_signature(
1836 "0.9",
1837 ["session", "query", "query_context", "result"],
1838 lambda update_context: (
1839 update_context.session,
1840 update_context.query,
1841 None,
1842 update_context.result,
1843 ),
1844 )
1845 def after_bulk_update(self, update_context):
1846 """Execute after an ORM UPDATE against a WHERE expression has been
1847 invoked.
1849 This is called as a result of the :meth:`_query.Query.update` method.
1851 :param update_context: an "update context" object which contains
1852 details about the update, including these attributes:
1854 * ``session`` - the :class:`.Session` involved
1855 * ``query`` -the :class:`_query.Query`
1856 object that this update operation
1857 was called upon.
1858 * ``values`` The "values" dictionary that was passed to
1859 :meth:`_query.Query.update`.
1860 * ``result`` the :class:`_engine.CursorResult`
1861 returned as a result of the
1862 bulk UPDATE operation.
1864 .. versionchanged:: 1.4 the update_context no longer has a
1865 ``QueryContext`` object associated with it.
1867 .. seealso::
1869 :meth:`.QueryEvents.before_compile_update`
1871 :meth:`.SessionEvents.after_bulk_delete`
1873 """
1875 @event._legacy_signature(
1876 "0.9",
1877 ["session", "query", "query_context", "result"],
1878 lambda delete_context: (
1879 delete_context.session,
1880 delete_context.query,
1881 None,
1882 delete_context.result,
1883 ),
1884 )
1885 def after_bulk_delete(self, delete_context):
1886 """Execute after ORM DELETE against a WHERE expression has been
1887 invoked.
1889 This is called as a result of the :meth:`_query.Query.delete` method.
1891 :param delete_context: a "delete context" object which contains
1892 details about the update, including these attributes:
1894 * ``session`` - the :class:`.Session` involved
1895 * ``query`` -the :class:`_query.Query`
1896 object that this update operation
1897 was called upon.
1898 * ``result`` the :class:`_engine.CursorResult`
1899 returned as a result of the
1900 bulk DELETE operation.
1902 .. versionchanged:: 1.4 the update_context no longer has a
1903 ``QueryContext`` object associated with it.
1905 .. seealso::
1907 :meth:`.QueryEvents.before_compile_delete`
1909 :meth:`.SessionEvents.after_bulk_update`
1911 """
1913 @_lifecycle_event
1914 def transient_to_pending(self, session, instance):
1915 """Intercept the "transient to pending" transition for a specific
1916 object.
1918 This event is a specialization of the
1919 :meth:`.SessionEvents.after_attach` event which is only invoked
1920 for this specific transition. It is invoked typically during the
1921 :meth:`.Session.add` call.
1923 :param session: target :class:`.Session`
1925 :param instance: the ORM-mapped instance being operated upon.
1927 .. versionadded:: 1.1
1929 .. seealso::
1931 :ref:`session_lifecycle_events`
1933 """
1935 @_lifecycle_event
1936 def pending_to_transient(self, session, instance):
1937 """Intercept the "pending to transient" transition for a specific
1938 object.
1940 This less common transition occurs when an pending object that has
1941 not been flushed is evicted from the session; this can occur
1942 when the :meth:`.Session.rollback` method rolls back the transaction,
1943 or when the :meth:`.Session.expunge` method is used.
1945 :param session: target :class:`.Session`
1947 :param instance: the ORM-mapped instance being operated upon.
1949 .. versionadded:: 1.1
1951 .. seealso::
1953 :ref:`session_lifecycle_events`
1955 """
1957 @_lifecycle_event
1958 def persistent_to_transient(self, session, instance):
1959 """Intercept the "persistent to transient" transition for a specific
1960 object.
1962 This less common transition occurs when an pending object that has
1963 has been flushed is evicted from the session; this can occur
1964 when the :meth:`.Session.rollback` method rolls back the transaction.
1966 :param session: target :class:`.Session`
1968 :param instance: the ORM-mapped instance being operated upon.
1970 .. versionadded:: 1.1
1972 .. seealso::
1974 :ref:`session_lifecycle_events`
1976 """
1978 @_lifecycle_event
1979 def pending_to_persistent(self, session, instance):
1980 """Intercept the "pending to persistent"" transition for a specific
1981 object.
1983 This event is invoked within the flush process, and is
1984 similar to scanning the :attr:`.Session.new` collection within
1985 the :meth:`.SessionEvents.after_flush` event. However, in this
1986 case the object has already been moved to the persistent state
1987 when the event is called.
1989 :param session: target :class:`.Session`
1991 :param instance: the ORM-mapped instance being operated upon.
1993 .. versionadded:: 1.1
1995 .. seealso::
1997 :ref:`session_lifecycle_events`
1999 """
2001 @_lifecycle_event
2002 def detached_to_persistent(self, session, instance):
2003 """Intercept the "detached to persistent" transition for a specific
2004 object.
2006 This event is a specialization of the
2007 :meth:`.SessionEvents.after_attach` event which is only invoked
2008 for this specific transition. It is invoked typically during the
2009 :meth:`.Session.add` call, as well as during the
2010 :meth:`.Session.delete` call if the object was not previously
2011 associated with the
2012 :class:`.Session` (note that an object marked as "deleted" remains
2013 in the "persistent" state until the flush proceeds).
2015 .. note::
2017 If the object becomes persistent as part of a call to
2018 :meth:`.Session.delete`, the object is **not** yet marked as
2019 deleted when this event is called. To detect deleted objects,
2020 check the ``deleted`` flag sent to the
2021 :meth:`.SessionEvents.persistent_to_detached` to event after the
2022 flush proceeds, or check the :attr:`.Session.deleted` collection
2023 within the :meth:`.SessionEvents.before_flush` event if deleted
2024 objects need to be intercepted before the flush.
2026 :param session: target :class:`.Session`
2028 :param instance: the ORM-mapped instance being operated upon.
2030 .. versionadded:: 1.1
2032 .. seealso::
2034 :ref:`session_lifecycle_events`
2036 """
2038 @_lifecycle_event
2039 def loaded_as_persistent(self, session, instance):
2040 """Intercept the "loaded as persistent" transition for a specific
2041 object.
2043 This event is invoked within the ORM loading process, and is invoked
2044 very similarly to the :meth:`.InstanceEvents.load` event. However,
2045 the event here is linkable to a :class:`.Session` class or instance,
2046 rather than to a mapper or class hierarchy, and integrates
2047 with the other session lifecycle events smoothly. The object
2048 is guaranteed to be present in the session's identity map when
2049 this event is called.
2051 .. note:: This event is invoked within the loader process before
2052 eager loaders may have been completed, and the object's state may
2053 not be complete. Additionally, invoking row-level refresh
2054 operations on the object will place the object into a new loader
2055 context, interfering with the existing load context. See the note
2056 on :meth:`.InstanceEvents.load` for background on making use of the
2057 :paramref:`.SessionEvents.restore_load_context` parameter, which
2058 works in the same manner as that of
2059 :paramref:`.InstanceEvents.restore_load_context`, in order to
2060 resolve this scenario.
2062 :param session: target :class:`.Session`
2064 :param instance: the ORM-mapped instance being operated upon.
2066 .. versionadded:: 1.1
2068 .. seealso::
2070 :ref:`session_lifecycle_events`
2072 """
2074 @_lifecycle_event
2075 def persistent_to_deleted(self, session, instance):
2076 """Intercept the "persistent to deleted" transition for a specific
2077 object.
2079 This event is invoked when a persistent object's identity
2080 is deleted from the database within a flush, however the object
2081 still remains associated with the :class:`.Session` until the
2082 transaction completes.
2084 If the transaction is rolled back, the object moves again
2085 to the persistent state, and the
2086 :meth:`.SessionEvents.deleted_to_persistent` event is called.
2087 If the transaction is committed, the object becomes detached,
2088 which will emit the :meth:`.SessionEvents.deleted_to_detached`
2089 event.
2091 Note that while the :meth:`.Session.delete` method is the primary
2092 public interface to mark an object as deleted, many objects
2093 get deleted due to cascade rules, which are not always determined
2094 until flush time. Therefore, there's no way to catch
2095 every object that will be deleted until the flush has proceeded.
2096 the :meth:`.SessionEvents.persistent_to_deleted` event is therefore
2097 invoked at the end of a flush.
2099 .. versionadded:: 1.1
2101 .. seealso::
2103 :ref:`session_lifecycle_events`
2105 """
2107 @_lifecycle_event
2108 def deleted_to_persistent(self, session, instance):
2109 """Intercept the "deleted to persistent" transition for a specific
2110 object.
2112 This transition occurs only when an object that's been deleted
2113 successfully in a flush is restored due to a call to
2114 :meth:`.Session.rollback`. The event is not called under
2115 any other circumstances.
2117 .. versionadded:: 1.1
2119 .. seealso::
2121 :ref:`session_lifecycle_events`
2123 """
2125 @_lifecycle_event
2126 def deleted_to_detached(self, session, instance):
2127 """Intercept the "deleted to detached" transition for a specific
2128 object.
2130 This event is invoked when a deleted object is evicted
2131 from the session. The typical case when this occurs is when
2132 the transaction for a :class:`.Session` in which the object
2133 was deleted is committed; the object moves from the deleted
2134 state to the detached state.
2136 It is also invoked for objects that were deleted in a flush
2137 when the :meth:`.Session.expunge_all` or :meth:`.Session.close`
2138 events are called, as well as if the object is individually
2139 expunged from its deleted state via :meth:`.Session.expunge`.
2141 .. versionadded:: 1.1
2143 .. seealso::
2145 :ref:`session_lifecycle_events`
2147 """
2149 @_lifecycle_event
2150 def persistent_to_detached(self, session, instance):
2151 """Intercept the "persistent to detached" transition for a specific
2152 object.
2154 This event is invoked when a persistent object is evicted
2155 from the session. There are many conditions that cause this
2156 to happen, including:
2158 * using a method such as :meth:`.Session.expunge`
2159 or :meth:`.Session.close`
2161 * Calling the :meth:`.Session.rollback` method, when the object
2162 was part of an INSERT statement for that session's transaction
2165 :param session: target :class:`.Session`
2167 :param instance: the ORM-mapped instance being operated upon.
2169 :param deleted: boolean. If True, indicates this object moved
2170 to the detached state because it was marked as deleted and flushed.
2173 .. versionadded:: 1.1
2175 .. seealso::
2177 :ref:`session_lifecycle_events`
2179 """
2182class AttributeEvents(event.Events):
2183 r"""Define events for object attributes.
2185 These are typically defined on the class-bound descriptor for the
2186 target class.
2188 For example, to register a listener that will receive the
2189 :meth:`_orm.AttributeEvents.append` event::
2191 from sqlalchemy import event
2193 @event.listens_for(MyClass.collection, 'append', propagate=True)
2194 def my_append_listener(target, value, initiator):
2195 print("received append event for target: %s" % target)
2198 Listeners have the option to return a possibly modified version of the
2199 value, when the :paramref:`.AttributeEvents.retval` flag is passed to
2200 :func:`.event.listen` or :func:`.event.listens_for`, such as below,
2201 illustrated using the :meth:`_orm.AttributeEvents.set` event::
2203 def validate_phone(target, value, oldvalue, initiator):
2204 "Strip non-numeric characters from a phone number"
2206 return re.sub(r'\D', '', value)
2208 # setup listener on UserContact.phone attribute, instructing
2209 # it to use the return value
2210 listen(UserContact.phone, 'set', validate_phone, retval=True)
2212 A validation function like the above can also raise an exception
2213 such as :exc:`ValueError` to halt the operation.
2215 The :paramref:`.AttributeEvents.propagate` flag is also important when
2216 applying listeners to mapped classes that also have mapped subclasses,
2217 as when using mapper inheritance patterns::
2220 @event.listens_for(MySuperClass.attr, 'set', propagate=True)
2221 def receive_set(target, value, initiator):
2222 print("value set: %s" % target)
2224 The full list of modifiers available to the :func:`.event.listen`
2225 and :func:`.event.listens_for` functions are below.
2227 :param active_history=False: When True, indicates that the
2228 "set" event would like to receive the "old" value being
2229 replaced unconditionally, even if this requires firing off
2230 database loads. Note that ``active_history`` can also be
2231 set directly via :func:`.column_property` and
2232 :func:`_orm.relationship`.
2234 :param propagate=False: When True, the listener function will
2235 be established not just for the class attribute given, but
2236 for attributes of the same name on all current subclasses
2237 of that class, as well as all future subclasses of that
2238 class, using an additional listener that listens for
2239 instrumentation events.
2240 :param raw=False: When True, the "target" argument to the
2241 event will be the :class:`.InstanceState` management
2242 object, rather than the mapped instance itself.
2243 :param retval=False: when True, the user-defined event
2244 listening must return the "value" argument from the
2245 function. This gives the listening function the opportunity
2246 to change the value that is ultimately used for a "set"
2247 or "append" event.
2249 """
2251 _target_class_doc = "SomeClass.some_attribute"
2252 _dispatch_target = QueryableAttribute
2254 @staticmethod
2255 def _set_dispatch(cls, dispatch_cls):
2256 dispatch = event.Events._set_dispatch(cls, dispatch_cls)
2257 dispatch_cls._active_history = False
2258 return dispatch
2260 @classmethod
2261 def _accept_with(cls, target):
2262 # TODO: coverage
2263 if isinstance(target, interfaces.MapperProperty):
2264 return getattr(target.parent.class_, target.key)
2265 else:
2266 return target
2268 @classmethod
2269 def _listen(
2270 cls,
2271 event_key,
2272 active_history=False,
2273 raw=False,
2274 retval=False,
2275 propagate=False,
2276 ):
2278 target, fn = event_key.dispatch_target, event_key._listen_fn
2280 if active_history:
2281 target.dispatch._active_history = True
2283 if not raw or not retval:
2285 def wrap(target, *arg):
2286 if not raw:
2287 target = target.obj()
2288 if not retval:
2289 if arg:
2290 value = arg[0]
2291 else:
2292 value = None
2293 fn(target, *arg)
2294 return value
2295 else:
2296 return fn(target, *arg)
2298 event_key = event_key.with_wrapper(wrap)
2300 event_key.base_listen(propagate=propagate)
2302 if propagate:
2303 manager = instrumentation.manager_of_class(target.class_)
2305 for mgr in manager.subclass_managers(True):
2306 event_key.with_dispatch_target(mgr[target.key]).base_listen(
2307 propagate=True
2308 )
2309 if active_history:
2310 mgr[target.key].dispatch._active_history = True
2312 def append(self, target, value, initiator):
2313 """Receive a collection append event.
2315 The append event is invoked for each element as it is appended
2316 to the collection. This occurs for single-item appends as well
2317 as for a "bulk replace" operation.
2319 :param target: the object instance receiving the event.
2320 If the listener is registered with ``raw=True``, this will
2321 be the :class:`.InstanceState` object.
2322 :param value: the value being appended. If this listener
2323 is registered with ``retval=True``, the listener
2324 function must return this value, or a new value which
2325 replaces it.
2326 :param initiator: An instance of :class:`.attributes.Event`
2327 representing the initiation of the event. May be modified
2328 from its original value by backref handlers in order to control
2329 chained event propagation, as well as be inspected for information
2330 about the source of the event.
2331 :return: if the event was registered with ``retval=True``,
2332 the given value, or a new effective value, should be returned.
2334 .. seealso::
2336 :class:`.AttributeEvents` - background on listener options such
2337 as propagation to subclasses.
2339 :meth:`.AttributeEvents.bulk_replace`
2341 """
2343 def append_wo_mutation(self, target, value, initiator):
2344 """Receive a collection append event where the collection was not
2345 actually mutated.
2347 This event differs from :meth:`_orm.AttributeEvents.append` in that
2348 it is fired off for de-duplicating collections such as sets and
2349 dictionaries, when the object already exists in the target collection.
2350 The event does not have a return value and the identity of the
2351 given object cannot be changed.
2353 The event is used for cascading objects into a :class:`_orm.Session`
2354 when the collection has already been mutated via a backref event.
2356 :param target: the object instance receiving the event.
2357 If the listener is registered with ``raw=True``, this will
2358 be the :class:`.InstanceState` object.
2359 :param value: the value that would be appended if the object did not
2360 already exist in the collection.
2361 :param initiator: An instance of :class:`.attributes.Event`
2362 representing the initiation of the event. May be modified
2363 from its original value by backref handlers in order to control
2364 chained event propagation, as well as be inspected for information
2365 about the source of the event.
2367 :return: No return value is defined for this event.
2369 .. versionadded:: 1.4.15
2371 """
2373 def bulk_replace(self, target, values, initiator):
2374 """Receive a collection 'bulk replace' event.
2376 This event is invoked for a sequence of values as they are incoming
2377 to a bulk collection set operation, which can be
2378 modified in place before the values are treated as ORM objects.
2379 This is an "early hook" that runs before the bulk replace routine
2380 attempts to reconcile which objects are already present in the
2381 collection and which are being removed by the net replace operation.
2383 It is typical that this method be combined with use of the
2384 :meth:`.AttributeEvents.append` event. When using both of these
2385 events, note that a bulk replace operation will invoke
2386 the :meth:`.AttributeEvents.append` event for all new items,
2387 even after :meth:`.AttributeEvents.bulk_replace` has been invoked
2388 for the collection as a whole. In order to determine if an
2389 :meth:`.AttributeEvents.append` event is part of a bulk replace,
2390 use the symbol :attr:`~.attributes.OP_BULK_REPLACE` to test the
2391 incoming initiator::
2393 from sqlalchemy.orm.attributes import OP_BULK_REPLACE
2395 @event.listens_for(SomeObject.collection, "bulk_replace")
2396 def process_collection(target, values, initiator):
2397 values[:] = [_make_value(value) for value in values]
2399 @event.listens_for(SomeObject.collection, "append", retval=True)
2400 def process_collection(target, value, initiator):
2401 # make sure bulk_replace didn't already do it
2402 if initiator is None or initiator.op is not OP_BULK_REPLACE:
2403 return _make_value(value)
2404 else:
2405 return value
2407 .. versionadded:: 1.2
2409 :param target: the object instance receiving the event.
2410 If the listener is registered with ``raw=True``, this will
2411 be the :class:`.InstanceState` object.
2412 :param value: a sequence (e.g. a list) of the values being set. The
2413 handler can modify this list in place.
2414 :param initiator: An instance of :class:`.attributes.Event`
2415 representing the initiation of the event.
2417 .. seealso::
2419 :class:`.AttributeEvents` - background on listener options such
2420 as propagation to subclasses.
2423 """
2425 def remove(self, target, value, initiator):
2426 """Receive a collection remove event.
2428 :param target: the object instance receiving the event.
2429 If the listener is registered with ``raw=True``, this will
2430 be the :class:`.InstanceState` object.
2431 :param value: the value being removed.
2432 :param initiator: An instance of :class:`.attributes.Event`
2433 representing the initiation of the event. May be modified
2434 from its original value by backref handlers in order to control
2435 chained event propagation.
2437 .. versionchanged:: 0.9.0 the ``initiator`` argument is now
2438 passed as a :class:`.attributes.Event` object, and may be
2439 modified by backref handlers within a chain of backref-linked
2440 events.
2442 :return: No return value is defined for this event.
2445 .. seealso::
2447 :class:`.AttributeEvents` - background on listener options such
2448 as propagation to subclasses.
2450 """
2452 def set(self, target, value, oldvalue, initiator):
2453 """Receive a scalar set event.
2455 :param target: the object instance receiving the event.
2456 If the listener is registered with ``raw=True``, this will
2457 be the :class:`.InstanceState` object.
2458 :param value: the value being set. If this listener
2459 is registered with ``retval=True``, the listener
2460 function must return this value, or a new value which
2461 replaces it.
2462 :param oldvalue: the previous value being replaced. This
2463 may also be the symbol ``NEVER_SET`` or ``NO_VALUE``.
2464 If the listener is registered with ``active_history=True``,
2465 the previous value of the attribute will be loaded from
2466 the database if the existing value is currently unloaded
2467 or expired.
2468 :param initiator: An instance of :class:`.attributes.Event`
2469 representing the initiation of the event. May be modified
2470 from its original value by backref handlers in order to control
2471 chained event propagation.
2473 .. versionchanged:: 0.9.0 the ``initiator`` argument is now
2474 passed as a :class:`.attributes.Event` object, and may be
2475 modified by backref handlers within a chain of backref-linked
2476 events.
2478 :return: if the event was registered with ``retval=True``,
2479 the given value, or a new effective value, should be returned.
2481 .. seealso::
2483 :class:`.AttributeEvents` - background on listener options such
2484 as propagation to subclasses.
2486 """
2488 def init_scalar(self, target, value, dict_):
2489 r"""Receive a scalar "init" event.
2491 This event is invoked when an uninitialized, unpersisted scalar
2492 attribute is accessed, e.g. read::
2495 x = my_object.some_attribute
2497 The ORM's default behavior when this occurs for an un-initialized
2498 attribute is to return the value ``None``; note this differs from
2499 Python's usual behavior of raising ``AttributeError``. The
2500 event here can be used to customize what value is actually returned,
2501 with the assumption that the event listener would be mirroring
2502 a default generator that is configured on the Core
2503 :class:`_schema.Column`
2504 object as well.
2506 Since a default generator on a :class:`_schema.Column`
2507 might also produce
2508 a changing value such as a timestamp, the
2509 :meth:`.AttributeEvents.init_scalar`
2510 event handler can also be used to **set** the newly returned value, so
2511 that a Core-level default generation function effectively fires off
2512 only once, but at the moment the attribute is accessed on the
2513 non-persisted object. Normally, no change to the object's state
2514 is made when an uninitialized attribute is accessed (much older
2515 SQLAlchemy versions did in fact change the object's state).
2517 If a default generator on a column returned a particular constant,
2518 a handler might be used as follows::
2520 SOME_CONSTANT = 3.1415926
2522 class MyClass(Base):
2523 # ...
2525 some_attribute = Column(Numeric, default=SOME_CONSTANT)
2527 @event.listens_for(
2528 MyClass.some_attribute, "init_scalar",
2529 retval=True, propagate=True)
2530 def _init_some_attribute(target, dict_, value):
2531 dict_['some_attribute'] = SOME_CONSTANT
2532 return SOME_CONSTANT
2534 Above, we initialize the attribute ``MyClass.some_attribute`` to the
2535 value of ``SOME_CONSTANT``. The above code includes the following
2536 features:
2538 * By setting the value ``SOME_CONSTANT`` in the given ``dict_``,
2539 we indicate that this value is to be persisted to the database.
2540 This supersedes the use of ``SOME_CONSTANT`` in the default generator
2541 for the :class:`_schema.Column`. The ``active_column_defaults.py``
2542 example given at :ref:`examples_instrumentation` illustrates using
2543 the same approach for a changing default, e.g. a timestamp
2544 generator. In this particular example, it is not strictly
2545 necessary to do this since ``SOME_CONSTANT`` would be part of the
2546 INSERT statement in either case.
2548 * By establishing the ``retval=True`` flag, the value we return
2549 from the function will be returned by the attribute getter.
2550 Without this flag, the event is assumed to be a passive observer
2551 and the return value of our function is ignored.
2553 * The ``propagate=True`` flag is significant if the mapped class
2554 includes inheriting subclasses, which would also make use of this
2555 event listener. Without this flag, an inheriting subclass will
2556 not use our event handler.
2558 In the above example, the attribute set event
2559 :meth:`.AttributeEvents.set` as well as the related validation feature
2560 provided by :obj:`_orm.validates` is **not** invoked when we apply our
2561 value to the given ``dict_``. To have these events to invoke in
2562 response to our newly generated value, apply the value to the given
2563 object as a normal attribute set operation::
2565 SOME_CONSTANT = 3.1415926
2567 @event.listens_for(
2568 MyClass.some_attribute, "init_scalar",
2569 retval=True, propagate=True)
2570 def _init_some_attribute(target, dict_, value):
2571 # will also fire off attribute set events
2572 target.some_attribute = SOME_CONSTANT
2573 return SOME_CONSTANT
2575 When multiple listeners are set up, the generation of the value
2576 is "chained" from one listener to the next by passing the value
2577 returned by the previous listener that specifies ``retval=True``
2578 as the ``value`` argument of the next listener.
2580 .. versionadded:: 1.1
2582 :param target: the object instance receiving the event.
2583 If the listener is registered with ``raw=True``, this will
2584 be the :class:`.InstanceState` object.
2585 :param value: the value that is to be returned before this event
2586 listener were invoked. This value begins as the value ``None``,
2587 however will be the return value of the previous event handler
2588 function if multiple listeners are present.
2589 :param dict\_: the attribute dictionary of this mapped object.
2590 This is normally the ``__dict__`` of the object, but in all cases
2591 represents the destination that the attribute system uses to get
2592 at the actual value of this attribute. Placing the value in this
2593 dictionary has the effect that the value will be used in the
2594 INSERT statement generated by the unit of work.
2597 .. seealso::
2599 :meth:`.AttributeEvents.init_collection` - collection version
2600 of this event
2602 :class:`.AttributeEvents` - background on listener options such
2603 as propagation to subclasses.
2605 :ref:`examples_instrumentation` - see the
2606 ``active_column_defaults.py`` example.
2608 """
2610 def init_collection(self, target, collection, collection_adapter):
2611 """Receive a 'collection init' event.
2613 This event is triggered for a collection-based attribute, when
2614 the initial "empty collection" is first generated for a blank
2615 attribute, as well as for when the collection is replaced with
2616 a new one, such as via a set event.
2618 E.g., given that ``User.addresses`` is a relationship-based
2619 collection, the event is triggered here::
2621 u1 = User()
2622 u1.addresses.append(a1) # <- new collection
2624 and also during replace operations::
2626 u1.addresses = [a2, a3] # <- new collection
2628 :param target: the object instance receiving the event.
2629 If the listener is registered with ``raw=True``, this will
2630 be the :class:`.InstanceState` object.
2631 :param collection: the new collection. This will always be generated
2632 from what was specified as
2633 :paramref:`_orm.relationship.collection_class`, and will always
2634 be empty.
2635 :param collection_adapter: the :class:`.CollectionAdapter` that will
2636 mediate internal access to the collection.
2638 .. versionadded:: 1.0.0 :meth:`.AttributeEvents.init_collection`
2639 and :meth:`.AttributeEvents.dispose_collection` events.
2641 .. seealso::
2643 :class:`.AttributeEvents` - background on listener options such
2644 as propagation to subclasses.
2646 :meth:`.AttributeEvents.init_scalar` - "scalar" version of this
2647 event.
2649 """
2651 def dispose_collection(self, target, collection, collection_adapter):
2652 """Receive a 'collection dispose' event.
2654 This event is triggered for a collection-based attribute when
2655 a collection is replaced, that is::
2657 u1.addresses.append(a1)
2659 u1.addresses = [a2, a3] # <- old collection is disposed
2661 The old collection received will contain its previous contents.
2663 .. versionchanged:: 1.2 The collection passed to
2664 :meth:`.AttributeEvents.dispose_collection` will now have its
2665 contents before the dispose intact; previously, the collection
2666 would be empty.
2668 .. versionadded:: 1.0.0 the :meth:`.AttributeEvents.init_collection`
2669 and :meth:`.AttributeEvents.dispose_collection` events.
2671 .. seealso::
2673 :class:`.AttributeEvents` - background on listener options such
2674 as propagation to subclasses.
2676 """
2678 def modified(self, target, initiator):
2679 """Receive a 'modified' event.
2681 This event is triggered when the :func:`.attributes.flag_modified`
2682 function is used to trigger a modify event on an attribute without
2683 any specific value being set.
2685 .. versionadded:: 1.2
2687 :param target: the object instance receiving the event.
2688 If the listener is registered with ``raw=True``, this will
2689 be the :class:`.InstanceState` object.
2691 :param initiator: An instance of :class:`.attributes.Event`
2692 representing the initiation of the event.
2694 .. seealso::
2696 :class:`.AttributeEvents` - background on listener options such
2697 as propagation to subclasses.
2699 """
2702class QueryEvents(event.Events):
2703 """Represent events within the construction of a :class:`_query.Query`
2704 object.
2706 The :class:`_orm.QueryEvents` hooks are now superseded by the
2707 :meth:`_orm.SessionEvents.do_orm_execute` event hook.
2709 """
2711 _target_class_doc = "SomeQuery"
2712 _dispatch_target = Query
2714 def before_compile(self, query):
2715 """Receive the :class:`_query.Query`
2716 object before it is composed into a
2717 core :class:`_expression.Select` object.
2719 .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile` event
2720 is superseded by the much more capable
2721 :meth:`_orm.SessionEvents.do_orm_execute` hook. In version 1.4,
2722 the :meth:`_orm.QueryEvents.before_compile` event is **no longer
2723 used** for ORM-level attribute loads, such as loads of deferred
2724 or expired attributes as well as relationship loaders. See the
2725 new examples in :ref:`examples_session_orm_events` which
2726 illustrate new ways of intercepting and modifying ORM queries
2727 for the most common purpose of adding arbitrary filter criteria.
2730 This event is intended to allow changes to the query given::
2732 @event.listens_for(Query, "before_compile", retval=True)
2733 def no_deleted(query):
2734 for desc in query.column_descriptions:
2735 if desc['type'] is User:
2736 entity = desc['entity']
2737 query = query.filter(entity.deleted == False)
2738 return query
2740 The event should normally be listened with the ``retval=True``
2741 parameter set, so that the modified query may be returned.
2743 The :meth:`.QueryEvents.before_compile` event by default
2744 will disallow "baked" queries from caching a query, if the event
2745 hook returns a new :class:`_query.Query` object.
2746 This affects both direct
2747 use of the baked query extension as well as its operation within
2748 lazy loaders and eager loaders for relationships. In order to
2749 re-establish the query being cached, apply the event adding the
2750 ``bake_ok`` flag::
2752 @event.listens_for(
2753 Query, "before_compile", retval=True, bake_ok=True)
2754 def my_event(query):
2755 for desc in query.column_descriptions:
2756 if desc['type'] is User:
2757 entity = desc['entity']
2758 query = query.filter(entity.deleted == False)
2759 return query
2761 When ``bake_ok`` is set to True, the event hook will only be invoked
2762 once, and not called for subsequent invocations of a particular query
2763 that is being cached.
2765 .. versionadded:: 1.3.11 - added the "bake_ok" flag to the
2766 :meth:`.QueryEvents.before_compile` event and disallowed caching via
2767 the "baked" extension from occurring for event handlers that
2768 return a new :class:`_query.Query` object if this flag is not set.
2770 .. seealso::
2772 :meth:`.QueryEvents.before_compile_update`
2774 :meth:`.QueryEvents.before_compile_delete`
2776 :ref:`baked_with_before_compile`
2778 """
2780 def before_compile_update(self, query, update_context):
2781 """Allow modifications to the :class:`_query.Query` object within
2782 :meth:`_query.Query.update`.
2784 .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_update`
2785 event is superseded by the much more capable
2786 :meth:`_orm.SessionEvents.do_orm_execute` hook.
2788 Like the :meth:`.QueryEvents.before_compile` event, if the event
2789 is to be used to alter the :class:`_query.Query` object, it should
2790 be configured with ``retval=True``, and the modified
2791 :class:`_query.Query` object returned, as in ::
2793 @event.listens_for(Query, "before_compile_update", retval=True)
2794 def no_deleted(query, update_context):
2795 for desc in query.column_descriptions:
2796 if desc['type'] is User:
2797 entity = desc['entity']
2798 query = query.filter(entity.deleted == False)
2800 update_context.values['timestamp'] = datetime.utcnow()
2801 return query
2803 The ``.values`` dictionary of the "update context" object can also
2804 be modified in place as illustrated above.
2806 :param query: a :class:`_query.Query` instance; this is also
2807 the ``.query`` attribute of the given "update context"
2808 object.
2810 :param update_context: an "update context" object which is
2811 the same kind of object as described in
2812 :paramref:`.QueryEvents.after_bulk_update.update_context`.
2813 The object has a ``.values`` attribute in an UPDATE context which is
2814 the dictionary of parameters passed to :meth:`_query.Query.update`.
2815 This
2816 dictionary can be modified to alter the VALUES clause of the
2817 resulting UPDATE statement.
2819 .. versionadded:: 1.2.17
2821 .. seealso::
2823 :meth:`.QueryEvents.before_compile`
2825 :meth:`.QueryEvents.before_compile_delete`
2828 """
2830 def before_compile_delete(self, query, delete_context):
2831 """Allow modifications to the :class:`_query.Query` object within
2832 :meth:`_query.Query.delete`.
2834 .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_delete`
2835 event is superseded by the much more capable
2836 :meth:`_orm.SessionEvents.do_orm_execute` hook.
2838 Like the :meth:`.QueryEvents.before_compile` event, this event
2839 should be configured with ``retval=True``, and the modified
2840 :class:`_query.Query` object returned, as in ::
2842 @event.listens_for(Query, "before_compile_delete", retval=True)
2843 def no_deleted(query, delete_context):
2844 for desc in query.column_descriptions:
2845 if desc['type'] is User:
2846 entity = desc['entity']
2847 query = query.filter(entity.deleted == False)
2848 return query
2850 :param query: a :class:`_query.Query` instance; this is also
2851 the ``.query`` attribute of the given "delete context"
2852 object.
2854 :param delete_context: a "delete context" object which is
2855 the same kind of object as described in
2856 :paramref:`.QueryEvents.after_bulk_delete.delete_context`.
2858 .. versionadded:: 1.2.17
2860 .. seealso::
2862 :meth:`.QueryEvents.before_compile`
2864 :meth:`.QueryEvents.before_compile_update`
2867 """
2869 @classmethod
2870 def _listen(cls, event_key, retval=False, bake_ok=False, **kw):
2871 fn = event_key._listen_fn
2873 if not retval:
2875 def wrap(*arg, **kw):
2876 if not retval:
2877 query = arg[0]
2878 fn(*arg, **kw)
2879 return query
2880 else:
2881 return fn(*arg, **kw)
2883 event_key = event_key.with_wrapper(wrap)
2884 else:
2885 # don't assume we can apply an attribute to the callable
2886 def wrap(*arg, **kw):
2887 return fn(*arg, **kw)
2889 event_key = event_key.with_wrapper(wrap)
2891 wrap._bake_ok = bake_ok
2893 event_key.base_listen(**kw)