1# orm/events.py
2# Copyright (C) 2005-2024 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
7
8"""ORM event interfaces.
9
10"""
11import weakref
12
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
26
27
28class InstrumentationEvents(event.Events):
29 """Events related to class instrumentation events.
30
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.
37
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.
41
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.
47
48 """
49
50 _target_class_doc = "SomeBaseClass"
51 _dispatch_target = instrumentation.InstrumentationFactory
52
53 @classmethod
54 def _accept_with(cls, target):
55 if isinstance(target, type):
56 return _InstrumentationEventsHold(target)
57 else:
58 return None
59
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 )
67
68 def listen(target_cls, *arg):
69 listen_cls = target()
70
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
77
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)
82
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)
93
94 target = weakref.ref(target.class_, remove)
95
96 event_key.with_dispatch_target(
97 instrumentation._instrumentation_factory
98 ).with_wrapper(listen).base_listen(**kw)
99
100 @classmethod
101 def _clear(cls):
102 super(InstrumentationEvents, cls)._clear()
103 instrumentation._instrumentation_factory.dispatch._clear()
104
105 def class_instrument(self, cls):
106 """Called after the given class is instrumented.
107
108 To get at the :class:`.ClassManager`, use
109 :func:`.manager_of_class`.
110
111 """
112
113 def class_uninstrument(self, cls):
114 """Called before the given class is uninstrumented.
115
116 To get at the :class:`.ClassManager`, use
117 :func:`.manager_of_class`.
118
119 """
120
121 def attribute_instrument(self, cls, key, inst):
122 """Called when an attribute is instrumented."""
123
124
125class _InstrumentationEventsHold(object):
126 """temporary marker object used to transfer from _accept_with() to
127 _listen() on the InstrumentationEvents class.
128
129 """
130
131 def __init__(self, class_):
132 self.class_ = class_
133
134 dispatch = event.dispatcher(InstrumentationEvents)
135
136
137class InstanceEvents(event.Events):
138 """Define events specific to object lifecycle.
139
140 e.g.::
141
142 from sqlalchemy import event
143
144 def my_load_listener(target, context):
145 print("on load!")
146
147 event.listen(SomeClass, 'load', my_load_listener)
148
149 Available targets include:
150
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.
157
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.
161
162 When using :class:`.InstanceEvents`, several modifiers are
163 available to the :func:`.event.listen` function.
164
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.
179
180 .. versionadded:: 1.3.14
181
182
183 """
184
185 _target_class_doc = "SomeClass"
186
187 _dispatch_target = instrumentation.ClassManager
188
189 @classmethod
190 def _new_classmanager_instance(cls, class_, classmanager):
191 _InstanceEventsHold.populate(class_, classmanager)
192
193 @classmethod
194 @util.preload_module("sqlalchemy.orm")
195 def _accept_with(cls, target):
196 orm = util.preloaded.orm
197
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
214
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)
225
226 if not raw or restore_load_context:
227
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
240
241 event_key = event_key.with_wrapper(wrap)
242
243 event_key.base_listen(propagate=propagate, **kw)
244
245 if propagate:
246 for mgr in target.subclass_managers(True):
247 event_key.with_dispatch_target(mgr).base_listen(propagate=True)
248
249 @classmethod
250 def _clear(cls):
251 super(InstanceEvents, cls)._clear()
252 _InstanceEventsHold._clear()
253
254 def first_init(self, manager, cls):
255 """Called when the first instance of a particular mapping is called.
256
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.
261
262 """
263
264 def init(self, target, args, kwargs):
265 """Receive an instance when its constructor is called.
266
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.
272
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__``.
277
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.
286
287 .. seealso::
288
289 :meth:`.InstanceEvents.init_failure`
290
291 :meth:`.InstanceEvents.load`
292
293 """
294
295 def init_failure(self, target, args, kwargs):
296 """Receive an instance when its constructor has been called,
297 and raised an exception.
298
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.
303
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()``.
310
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.
319
320 .. seealso::
321
322 :meth:`.InstanceEvents.init`
323
324 :meth:`.InstanceEvents.load`
325
326 """
327
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.
331
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.
338
339 This functionality is acceptable to be made public in a later release.
340
341 .. versionadded:: 1.4.41
342
343 """
344
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.
349
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.
353
354 .. warning::
355
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.
366
367 Examples of what can cause the "loading context" to change within
368 the event handler include, but are not necessarily limited to:
369
370 * accessing deferred attributes that weren't part of the row,
371 will trigger an "undefer" operation and refresh the object
372
373 * accessing attributes on a joined-inheritance subclass that
374 weren't part of the row, will trigger a refresh operation.
375
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::
381
382 @event.listens_for(
383 SomeClass, "load", restore_load_context=True)
384 def on_load(instance, context):
385 instance.some_unloaded_attribute
386
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.
394
395
396 The :meth:`.InstanceEvents.load` event is also available in a
397 class-method decorator format called :func:`_orm.reconstructor`.
398
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`.
407
408 .. seealso::
409
410 :meth:`.InstanceEvents.init`
411
412 :meth:`.InstanceEvents.refresh`
413
414 :meth:`.SessionEvents.loaded_as_persistent`
415
416 :ref:`mapping_constructors`
417
418 """
419
420 def refresh(self, target, context, attrs):
421 """Receive an object instance after one or more attributes have
422 been refreshed from a query.
423
424 Contrast this to the :meth:`.InstanceEvents.load` method, which
425 is invoked when the object is first loaded from a query.
426
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.
435
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.
445
446 .. seealso::
447
448 :meth:`.InstanceEvents.load`
449
450 """
451
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.
456
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.
462
463 .. note::
464
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.
474
475 .. versionadded:: 1.0.5
476
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.
485
486 .. seealso::
487
488 :ref:`orm_server_defaults`
489
490 :ref:`metadata_defaults_toplevel`
491
492 """
493
494 def expire(self, target, attrs):
495 """Receive an object instance after its attributes or some subset
496 have been expired.
497
498 'keys' is a list of attribute names. If None, the entire
499 state was expired.
500
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.
508
509 """
510
511 def pickle(self, target, state_dict):
512 """Receive an object instance when its associated state is
513 being pickled.
514
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.
522
523 """
524
525 def unpickle(self, target, state_dict):
526 """Receive an object instance after its associated state has
527 been unpickled.
528
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.
536
537 """
538
539
540class _EventsHold(event.RefCollection):
541 """Hold onto listeners against unmapped, uninstrumented classes.
542
543 Establish _listen() for that class' mapper/instrumentation when
544 those objects are created for that class.
545
546 """
547
548 def __init__(self, class_):
549 self.class_ = class_
550
551 @classmethod
552 def _clear(cls):
553 cls.all_holds.clear()
554
555 class HoldEvents(object):
556 _dispatch_target = None
557
558 @classmethod
559 def _listen(
560 cls, event_key, raw=False, propagate=False, retval=False, **kw
561 ):
562 target = event_key.dispatch_target
563
564 if target.class_ in target.all_holds:
565 collection = target.all_holds[target.class_]
566 else:
567 collection = target.all_holds[target.class_] = {}
568
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 )
577
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 )
590
591 def remove(self, event_key):
592 target = event_key.dispatch_target
593
594 if isinstance(target, _EventsHold):
595 collection = target.all_holds[target.class_]
596 del collection[event_key._key]
597
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 )
619
620
621class _InstanceEventsHold(_EventsHold):
622 all_holds = weakref.WeakKeyDictionary()
623
624 def resolve(self, class_):
625 return instrumentation.manager_of_class(class_)
626
627 class HoldInstanceEvents(_EventsHold.HoldEvents, InstanceEvents):
628 pass
629
630 dispatch = event.dispatcher(HoldInstanceEvents)
631
632
633class MapperEvents(event.Events):
634 """Define events specific to mappings.
635
636 e.g.::
637
638 from sqlalchemy import event
639
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()
646
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)
651
652 Available targets include:
653
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.
660
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.
673
674 When using :class:`.MapperEvents`, several modifiers are
675 available to the :func:`.event.listen` function.
676
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:
690
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.
696
697 """
698
699 _target_class_doc = "SomeClass"
700 _dispatch_target = mapperlib.Mapper
701
702 @classmethod
703 def _new_mapper_instance(cls, class_, mapper):
704 _MapperEventsHold.populate(class_, mapper)
705
706 @classmethod
707 @util.preload_module("sqlalchemy.orm")
708 def _accept_with(cls, target):
709 orm = util.preloaded.orm
710
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
724
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 )
734
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 )
744
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
754
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)
764
765 event_key = event_key.with_wrapper(wrap)
766
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)
774
775 @classmethod
776 def _clear(cls):
777 super(MapperEvents, cls)._clear()
778 _MapperEventsHold._clear()
779
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.
783
784 This event is the earliest phase of mapper construction.
785 Most attributes of the mapper are not yet initialized.
786
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)::
790
791 Base = declarative_base()
792
793 @event.listens_for(Base, "instrument_class", propagate=True)
794 def on_new_class(mapper, cls_):
795 " ... "
796
797 :param mapper: the :class:`_orm.Mapper` which is the target
798 of this event.
799 :param class\_: the mapped class.
800
801 """
802
803 def before_mapper_configured(self, mapper, class_):
804 """Called right before a specific mapper is to be configured.
805
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.
815
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.
823
824 .. versionadded:: 1.3
825
826 e.g.::
827
828 from sqlalchemy.orm import EXT_SKIP
829
830 Base = declarative_base()
831
832 DontConfigureBase = declarative_base()
833
834 @event.listens_for(
835 DontConfigureBase,
836 "before_mapper_configured", retval=True, propagate=True)
837 def dont_configure(mapper, cls):
838 return EXT_SKIP
839
840
841 .. seealso::
842
843 :meth:`.MapperEvents.before_configured`
844
845 :meth:`.MapperEvents.after_configured`
846
847 :meth:`.MapperEvents.mapper_configured`
848
849 """
850
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.
854
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.
863
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.
873
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.
879
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.
889
890 :param mapper: the :class:`_orm.Mapper` which is the target
891 of this event.
892 :param class\_: the mapped class.
893
894 .. seealso::
895
896 :meth:`.MapperEvents.before_configured`
897
898 :meth:`.MapperEvents.after_configured`
899
900 :meth:`.MapperEvents.before_mapper_configured`
901
902 """
903 # TODO: need coverage for this event
904
905 def before_configured(self):
906 """Called before a series of mappers have been configured.
907
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.
915
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::
919
920 from sqlalchemy.orm import mapper
921
922 @event.listens_for(mapper, "before_configured")
923 def go():
924 # ...
925
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.
931
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::
939
940 from sqlalchemy.orm import mapper
941
942 @event.listens_for(mapper, "before_configured", once=True)
943 def go():
944 # ...
945
946
947 .. versionadded:: 0.9.3
948
949
950 .. seealso::
951
952 :meth:`.MapperEvents.before_mapper_configured`
953
954 :meth:`.MapperEvents.mapper_configured`
955
956 :meth:`.MapperEvents.after_configured`
957
958 """
959
960 def after_configured(self):
961 """Called after a series of mappers have been configured.
962
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.
970
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.
978
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::
982
983 from sqlalchemy.orm import mapper
984
985 @event.listens_for(mapper, "after_configured")
986 def go():
987 # ...
988
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::
996
997 from sqlalchemy.orm import mapper
998
999 @event.listens_for(mapper, "after_configured", once=True)
1000 def go():
1001 # ...
1002
1003 .. seealso::
1004
1005 :meth:`.MapperEvents.before_mapper_configured`
1006
1007 :meth:`.MapperEvents.mapper_configured`
1008
1009 :meth:`.MapperEvents.before_configured`
1010
1011 """
1012
1013 def before_insert(self, mapper, connection, target):
1014 """Receive an object instance before an INSERT statement
1015 is emitted corresponding to that instance.
1016
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.
1021
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.
1030
1031 .. warning::
1032
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.
1040
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.
1052
1053 .. seealso::
1054
1055 :ref:`session_persistence_events`
1056
1057 """
1058
1059 def after_insert(self, mapper, connection, target):
1060 """Receive an object instance after an INSERT statement
1061 is emitted corresponding to that instance.
1062
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.
1067
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.
1076
1077 .. warning::
1078
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.
1086
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.
1098
1099 .. seealso::
1100
1101 :ref:`session_persistence_events`
1102
1103 """
1104
1105 def before_update(self, mapper, connection, target):
1106 """Receive an object instance before an UPDATE statement
1107 is emitted corresponding to that instance.
1108
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.
1113
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.
1127
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)``.
1132
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.
1141
1142 .. warning::
1143
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.
1151
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.
1163
1164 .. seealso::
1165
1166 :ref:`session_persistence_events`
1167
1168 """
1169
1170 def after_update(self, mapper, connection, target):
1171 """Receive an object instance after an UPDATE statement
1172 is emitted corresponding to that instance.
1173
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.
1178
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.
1191
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)``.
1196
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.
1205
1206 .. warning::
1207
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.
1215
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.
1227
1228 .. seealso::
1229
1230 :ref:`session_persistence_events`
1231
1232 """
1233
1234 def before_delete(self, mapper, connection, target):
1235 """Receive an object instance before a DELETE statement
1236 is emitted corresponding to that instance.
1237
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.
1241
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.
1245
1246 .. warning::
1247
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.
1255
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.
1267
1268 .. seealso::
1269
1270 :ref:`session_persistence_events`
1271
1272 """
1273
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.
1277
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.
1281
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.
1285
1286 .. warning::
1287
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.
1295
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.
1307
1308 .. seealso::
1309
1310 :ref:`session_persistence_events`
1311
1312 """
1313
1314
1315class _MapperEventsHold(_EventsHold):
1316 all_holds = weakref.WeakKeyDictionary()
1317
1318 def resolve(self, class_):
1319 return _mapper_or_none(class_)
1320
1321 class HoldMapperEvents(_EventsHold.HoldEvents, MapperEvents):
1322 pass
1323
1324 dispatch = event.dispatcher(HoldMapperEvents)
1325
1326
1327_sessionevents_lifecycle_event_names = set()
1328
1329
1330class SessionEvents(event.Events):
1331 """Define events specific to :class:`.Session` lifecycle.
1332
1333 e.g.::
1334
1335 from sqlalchemy import event
1336 from sqlalchemy.orm import sessionmaker
1337
1338 def my_before_commit(session):
1339 print("before commit!")
1340
1341 Session = sessionmaker()
1342
1343 event.listen(Session, "before_commit", my_before_commit)
1344
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()`.
1348
1349 Additionally, it accepts the :class:`.Session` class which
1350 will apply listeners to all :class:`.Session` instances
1351 globally.
1352
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.
1357
1358 .. versionadded:: 1.3.14
1359
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.
1366
1367 .. versionadded:: 1.3.14
1368
1369 """
1370
1371 _target_class_doc = "SomeSessionClassOrObject"
1372
1373 _dispatch_target = Session
1374
1375 def _lifecycle_event(fn):
1376 _sessionevents_lifecycle_event_names.add(fn.__name__)
1377 return fn
1378
1379 @classmethod
1380 def _accept_with(cls, target):
1381 if isinstance(target, scoped_session):
1382
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 )
1392
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)
1405
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 )
1411
1412 if is_instance_event:
1413 if not raw or restore_load_context:
1414
1415 fn = event_key._listen_fn
1416
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
1433
1434 event_key = event_key.with_wrapper(wrap)
1435
1436 event_key.base_listen(**kw)
1437
1438 def do_orm_execute(self, orm_execute_state):
1439 """Intercept statement executions that occur on behalf of an
1440 ORM :class:`.Session` object.
1441
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.
1450
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`.
1464
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.
1472
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.
1476
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.
1481
1482 .. seealso::
1483
1484 :ref:`session_execute_events` - top level documentation on how
1485 to use :meth:`_orm.SessionEvents.do_orm_execute`
1486
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.
1493
1494 :ref:`examples_session_orm_events` - includes examples of using
1495 :meth:`_orm.SessionEvents.do_orm_execute`
1496
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.
1500
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.
1505
1506
1507 .. versionadded:: 1.4
1508
1509 """
1510
1511 def after_transaction_create(self, session, transaction):
1512 """Execute when a new :class:`.SessionTransaction` is created.
1513
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`).
1522
1523 :param session: the target :class:`.Session`.
1524 :param transaction: the target :class:`.SessionTransaction`.
1525
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``::
1530
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
1535
1536 To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the
1537 :attr:`.SessionTransaction.nested` attribute::
1538
1539 @event.listens_for(session, "after_transaction_create")
1540 def after_transaction_create(session, transaction):
1541 if transaction.nested:
1542 # work with SAVEPOINT transaction
1543
1544
1545 .. seealso::
1546
1547 :class:`.SessionTransaction`
1548
1549 :meth:`~.SessionEvents.after_transaction_end`
1550
1551 """
1552
1553 def after_transaction_end(self, session, transaction):
1554 """Execute when the span of a :class:`.SessionTransaction` ends.
1555
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.
1561
1562 :param session: the target :class:`.Session`.
1563 :param transaction: the target :class:`.SessionTransaction`.
1564
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``::
1569
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
1574
1575 To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the
1576 :attr:`.SessionTransaction.nested` attribute::
1577
1578 @event.listens_for(session, "after_transaction_create")
1579 def after_transaction_end(session, transaction):
1580 if transaction.nested:
1581 # work with SAVEPOINT transaction
1582
1583
1584 .. seealso::
1585
1586 :class:`.SessionTransaction`
1587
1588 :meth:`~.SessionEvents.after_transaction_create`
1589
1590 """
1591
1592 def before_commit(self, session):
1593 """Execute before commit is called.
1594
1595 .. note::
1596
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.
1605
1606 :param session: The target :class:`.Session`.
1607
1608 .. seealso::
1609
1610 :meth:`~.SessionEvents.after_commit`
1611
1612 :meth:`~.SessionEvents.after_begin`
1613
1614 :meth:`~.SessionEvents.after_transaction_create`
1615
1616 :meth:`~.SessionEvents.after_transaction_end`
1617
1618 """
1619
1620 def after_commit(self, session):
1621 """Execute after a commit has occurred.
1622
1623 .. note::
1624
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.
1633
1634 .. note::
1635
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.
1641
1642 :param session: The target :class:`.Session`.
1643
1644 .. seealso::
1645
1646 :meth:`~.SessionEvents.before_commit`
1647
1648 :meth:`~.SessionEvents.after_begin`
1649
1650 :meth:`~.SessionEvents.after_transaction_create`
1651
1652 :meth:`~.SessionEvents.after_transaction_end`
1653
1654 """
1655
1656 def after_rollback(self, session):
1657 """Execute after a real DBAPI rollback has occurred.
1658
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.
1669
1670 :param session: The target :class:`.Session`.
1671
1672 """
1673
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.
1677
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.
1682
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::
1686
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")
1691
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.
1697
1698 """
1699
1700 def before_flush(self, session, flush_context, instances):
1701 """Execute before flush process has started.
1702
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).
1709
1710 .. seealso::
1711
1712 :meth:`~.SessionEvents.after_flush`
1713
1714 :meth:`~.SessionEvents.after_flush_postexec`
1715
1716 :ref:`session_persistence_events`
1717
1718 """
1719
1720 def after_flush(self, session, flush_context):
1721 """Execute after flush has completed, but before commit has been
1722 called.
1723
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.
1727
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.
1736
1737 :param session: The target :class:`.Session`.
1738 :param flush_context: Internal :class:`.UOWTransaction` object
1739 which handles the details of the flush.
1740
1741 .. seealso::
1742
1743 :meth:`~.SessionEvents.before_flush`
1744
1745 :meth:`~.SessionEvents.after_flush_postexec`
1746
1747 :ref:`session_persistence_events`
1748
1749 """
1750
1751 def after_flush_postexec(self, session, flush_context):
1752 """Execute after flush has completed, and after the post-exec
1753 state occurs.
1754
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.
1759
1760 :param session: The target :class:`.Session`.
1761 :param flush_context: Internal :class:`.UOWTransaction` object
1762 which handles the details of the flush.
1763
1764
1765 .. seealso::
1766
1767 :meth:`~.SessionEvents.before_flush`
1768
1769 :meth:`~.SessionEvents.after_flush`
1770
1771 :ref:`session_persistence_events`
1772
1773 """
1774
1775 def after_begin(self, session, transaction, connection):
1776 """Execute after a transaction is begun on a connection
1777
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.
1782
1783 .. seealso::
1784
1785 :meth:`~.SessionEvents.before_commit`
1786
1787 :meth:`~.SessionEvents.after_commit`
1788
1789 :meth:`~.SessionEvents.after_transaction_create`
1790
1791 :meth:`~.SessionEvents.after_transaction_end`
1792
1793 """
1794
1795 @_lifecycle_event
1796 def before_attach(self, session, instance):
1797 """Execute before an instance is attached to a session.
1798
1799 This is called before an add, delete or merge causes
1800 the object to be part of the session.
1801
1802 .. seealso::
1803
1804 :meth:`~.SessionEvents.after_attach`
1805
1806 :ref:`session_lifecycle_events`
1807
1808 """
1809
1810 @_lifecycle_event
1811 def after_attach(self, session, instance):
1812 """Execute after an instance is attached to a session.
1813
1814 This is called after an add, delete or merge.
1815
1816 .. note::
1817
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.
1826
1827 .. seealso::
1828
1829 :meth:`~.SessionEvents.before_attach`
1830
1831 :ref:`session_lifecycle_events`
1832
1833 """
1834
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.
1848
1849 This is called as a result of the :meth:`_query.Query.update` method.
1850
1851 :param update_context: an "update context" object which contains
1852 details about the update, including these attributes:
1853
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.
1863
1864 .. versionchanged:: 1.4 the update_context no longer has a
1865 ``QueryContext`` object associated with it.
1866
1867 .. seealso::
1868
1869 :meth:`.QueryEvents.before_compile_update`
1870
1871 :meth:`.SessionEvents.after_bulk_delete`
1872
1873 """
1874
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.
1888
1889 This is called as a result of the :meth:`_query.Query.delete` method.
1890
1891 :param delete_context: a "delete context" object which contains
1892 details about the update, including these attributes:
1893
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.
1901
1902 .. versionchanged:: 1.4 the update_context no longer has a
1903 ``QueryContext`` object associated with it.
1904
1905 .. seealso::
1906
1907 :meth:`.QueryEvents.before_compile_delete`
1908
1909 :meth:`.SessionEvents.after_bulk_update`
1910
1911 """
1912
1913 @_lifecycle_event
1914 def transient_to_pending(self, session, instance):
1915 """Intercept the "transient to pending" transition for a specific
1916 object.
1917
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.
1922
1923 :param session: target :class:`.Session`
1924
1925 :param instance: the ORM-mapped instance being operated upon.
1926
1927 .. versionadded:: 1.1
1928
1929 .. seealso::
1930
1931 :ref:`session_lifecycle_events`
1932
1933 """
1934
1935 @_lifecycle_event
1936 def pending_to_transient(self, session, instance):
1937 """Intercept the "pending to transient" transition for a specific
1938 object.
1939
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.
1944
1945 :param session: target :class:`.Session`
1946
1947 :param instance: the ORM-mapped instance being operated upon.
1948
1949 .. versionadded:: 1.1
1950
1951 .. seealso::
1952
1953 :ref:`session_lifecycle_events`
1954
1955 """
1956
1957 @_lifecycle_event
1958 def persistent_to_transient(self, session, instance):
1959 """Intercept the "persistent to transient" transition for a specific
1960 object.
1961
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.
1965
1966 :param session: target :class:`.Session`
1967
1968 :param instance: the ORM-mapped instance being operated upon.
1969
1970 .. versionadded:: 1.1
1971
1972 .. seealso::
1973
1974 :ref:`session_lifecycle_events`
1975
1976 """
1977
1978 @_lifecycle_event
1979 def pending_to_persistent(self, session, instance):
1980 """Intercept the "pending to persistent"" transition for a specific
1981 object.
1982
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.
1988
1989 :param session: target :class:`.Session`
1990
1991 :param instance: the ORM-mapped instance being operated upon.
1992
1993 .. versionadded:: 1.1
1994
1995 .. seealso::
1996
1997 :ref:`session_lifecycle_events`
1998
1999 """
2000
2001 @_lifecycle_event
2002 def detached_to_persistent(self, session, instance):
2003 """Intercept the "detached to persistent" transition for a specific
2004 object.
2005
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).
2014
2015 .. note::
2016
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.
2025
2026 :param session: target :class:`.Session`
2027
2028 :param instance: the ORM-mapped instance being operated upon.
2029
2030 .. versionadded:: 1.1
2031
2032 .. seealso::
2033
2034 :ref:`session_lifecycle_events`
2035
2036 """
2037
2038 @_lifecycle_event
2039 def loaded_as_persistent(self, session, instance):
2040 """Intercept the "loaded as persistent" transition for a specific
2041 object.
2042
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.
2050
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.
2061
2062 :param session: target :class:`.Session`
2063
2064 :param instance: the ORM-mapped instance being operated upon.
2065
2066 .. versionadded:: 1.1
2067
2068 .. seealso::
2069
2070 :ref:`session_lifecycle_events`
2071
2072 """
2073
2074 @_lifecycle_event
2075 def persistent_to_deleted(self, session, instance):
2076 """Intercept the "persistent to deleted" transition for a specific
2077 object.
2078
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.
2083
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.
2090
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.
2098
2099 .. versionadded:: 1.1
2100
2101 .. seealso::
2102
2103 :ref:`session_lifecycle_events`
2104
2105 """
2106
2107 @_lifecycle_event
2108 def deleted_to_persistent(self, session, instance):
2109 """Intercept the "deleted to persistent" transition for a specific
2110 object.
2111
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.
2116
2117 .. versionadded:: 1.1
2118
2119 .. seealso::
2120
2121 :ref:`session_lifecycle_events`
2122
2123 """
2124
2125 @_lifecycle_event
2126 def deleted_to_detached(self, session, instance):
2127 """Intercept the "deleted to detached" transition for a specific
2128 object.
2129
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.
2135
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`.
2140
2141 .. versionadded:: 1.1
2142
2143 .. seealso::
2144
2145 :ref:`session_lifecycle_events`
2146
2147 """
2148
2149 @_lifecycle_event
2150 def persistent_to_detached(self, session, instance):
2151 """Intercept the "persistent to detached" transition for a specific
2152 object.
2153
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:
2157
2158 * using a method such as :meth:`.Session.expunge`
2159 or :meth:`.Session.close`
2160
2161 * Calling the :meth:`.Session.rollback` method, when the object
2162 was part of an INSERT statement for that session's transaction
2163
2164
2165 :param session: target :class:`.Session`
2166
2167 :param instance: the ORM-mapped instance being operated upon.
2168
2169 :param deleted: boolean. If True, indicates this object moved
2170 to the detached state because it was marked as deleted and flushed.
2171
2172
2173 .. versionadded:: 1.1
2174
2175 .. seealso::
2176
2177 :ref:`session_lifecycle_events`
2178
2179 """
2180
2181
2182class AttributeEvents(event.Events):
2183 r"""Define events for object attributes.
2184
2185 These are typically defined on the class-bound descriptor for the
2186 target class.
2187
2188 For example, to register a listener that will receive the
2189 :meth:`_orm.AttributeEvents.append` event::
2190
2191 from sqlalchemy import event
2192
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)
2196
2197
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::
2202
2203 def validate_phone(target, value, oldvalue, initiator):
2204 "Strip non-numeric characters from a phone number"
2205
2206 return re.sub(r'\D', '', value)
2207
2208 # setup listener on UserContact.phone attribute, instructing
2209 # it to use the return value
2210 listen(UserContact.phone, 'set', validate_phone, retval=True)
2211
2212 A validation function like the above can also raise an exception
2213 such as :exc:`ValueError` to halt the operation.
2214
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::
2218
2219
2220 @event.listens_for(MySuperClass.attr, 'set', propagate=True)
2221 def receive_set(target, value, initiator):
2222 print("value set: %s" % target)
2223
2224 The full list of modifiers available to the :func:`.event.listen`
2225 and :func:`.event.listens_for` functions are below.
2226
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`.
2233
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.
2248
2249 """
2250
2251 _target_class_doc = "SomeClass.some_attribute"
2252 _dispatch_target = QueryableAttribute
2253
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
2259
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
2267
2268 @classmethod
2269 def _listen(
2270 cls,
2271 event_key,
2272 active_history=False,
2273 raw=False,
2274 retval=False,
2275 propagate=False,
2276 ):
2277
2278 target, fn = event_key.dispatch_target, event_key._listen_fn
2279
2280 if active_history:
2281 target.dispatch._active_history = True
2282
2283 if not raw or not retval:
2284
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)
2297
2298 event_key = event_key.with_wrapper(wrap)
2299
2300 event_key.base_listen(propagate=propagate)
2301
2302 if propagate:
2303 manager = instrumentation.manager_of_class(target.class_)
2304
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
2311
2312 def append(self, target, value, initiator):
2313 """Receive a collection append event.
2314
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.
2318
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.
2333
2334 .. seealso::
2335
2336 :class:`.AttributeEvents` - background on listener options such
2337 as propagation to subclasses.
2338
2339 :meth:`.AttributeEvents.bulk_replace`
2340
2341 """
2342
2343 def append_wo_mutation(self, target, value, initiator):
2344 """Receive a collection append event where the collection was not
2345 actually mutated.
2346
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.
2352
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.
2355
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.
2366
2367 :return: No return value is defined for this event.
2368
2369 .. versionadded:: 1.4.15
2370
2371 """
2372
2373 def bulk_replace(self, target, values, initiator):
2374 """Receive a collection 'bulk replace' event.
2375
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.
2382
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::
2392
2393 from sqlalchemy.orm.attributes import OP_BULK_REPLACE
2394
2395 @event.listens_for(SomeObject.collection, "bulk_replace")
2396 def process_collection(target, values, initiator):
2397 values[:] = [_make_value(value) for value in values]
2398
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
2406
2407 .. versionadded:: 1.2
2408
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.
2416
2417 .. seealso::
2418
2419 :class:`.AttributeEvents` - background on listener options such
2420 as propagation to subclasses.
2421
2422
2423 """
2424
2425 def remove(self, target, value, initiator):
2426 """Receive a collection remove event.
2427
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.
2436
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.
2441
2442 :return: No return value is defined for this event.
2443
2444
2445 .. seealso::
2446
2447 :class:`.AttributeEvents` - background on listener options such
2448 as propagation to subclasses.
2449
2450 """
2451
2452 def set(self, target, value, oldvalue, initiator):
2453 """Receive a scalar set event.
2454
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.
2472
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.
2477
2478 :return: if the event was registered with ``retval=True``,
2479 the given value, or a new effective value, should be returned.
2480
2481 .. seealso::
2482
2483 :class:`.AttributeEvents` - background on listener options such
2484 as propagation to subclasses.
2485
2486 """
2487
2488 def init_scalar(self, target, value, dict_):
2489 r"""Receive a scalar "init" event.
2490
2491 This event is invoked when an uninitialized, unpersisted scalar
2492 attribute is accessed, e.g. read::
2493
2494
2495 x = my_object.some_attribute
2496
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.
2505
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).
2516
2517 If a default generator on a column returned a particular constant,
2518 a handler might be used as follows::
2519
2520 SOME_CONSTANT = 3.1415926
2521
2522 class MyClass(Base):
2523 # ...
2524
2525 some_attribute = Column(Numeric, default=SOME_CONSTANT)
2526
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
2533
2534 Above, we initialize the attribute ``MyClass.some_attribute`` to the
2535 value of ``SOME_CONSTANT``. The above code includes the following
2536 features:
2537
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.
2547
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.
2552
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.
2557
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::
2564
2565 SOME_CONSTANT = 3.1415926
2566
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
2574
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.
2579
2580 .. versionadded:: 1.1
2581
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.
2595
2596
2597 .. seealso::
2598
2599 :meth:`.AttributeEvents.init_collection` - collection version
2600 of this event
2601
2602 :class:`.AttributeEvents` - background on listener options such
2603 as propagation to subclasses.
2604
2605 :ref:`examples_instrumentation` - see the
2606 ``active_column_defaults.py`` example.
2607
2608 """
2609
2610 def init_collection(self, target, collection, collection_adapter):
2611 """Receive a 'collection init' event.
2612
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.
2617
2618 E.g., given that ``User.addresses`` is a relationship-based
2619 collection, the event is triggered here::
2620
2621 u1 = User()
2622 u1.addresses.append(a1) # <- new collection
2623
2624 and also during replace operations::
2625
2626 u1.addresses = [a2, a3] # <- new collection
2627
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.
2637
2638 .. versionadded:: 1.0.0 :meth:`.AttributeEvents.init_collection`
2639 and :meth:`.AttributeEvents.dispose_collection` events.
2640
2641 .. seealso::
2642
2643 :class:`.AttributeEvents` - background on listener options such
2644 as propagation to subclasses.
2645
2646 :meth:`.AttributeEvents.init_scalar` - "scalar" version of this
2647 event.
2648
2649 """
2650
2651 def dispose_collection(self, target, collection, collection_adapter):
2652 """Receive a 'collection dispose' event.
2653
2654 This event is triggered for a collection-based attribute when
2655 a collection is replaced, that is::
2656
2657 u1.addresses.append(a1)
2658
2659 u1.addresses = [a2, a3] # <- old collection is disposed
2660
2661 The old collection received will contain its previous contents.
2662
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.
2667
2668 .. versionadded:: 1.0.0 the :meth:`.AttributeEvents.init_collection`
2669 and :meth:`.AttributeEvents.dispose_collection` events.
2670
2671 .. seealso::
2672
2673 :class:`.AttributeEvents` - background on listener options such
2674 as propagation to subclasses.
2675
2676 """
2677
2678 def modified(self, target, initiator):
2679 """Receive a 'modified' event.
2680
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.
2684
2685 .. versionadded:: 1.2
2686
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.
2690
2691 :param initiator: An instance of :class:`.attributes.Event`
2692 representing the initiation of the event.
2693
2694 .. seealso::
2695
2696 :class:`.AttributeEvents` - background on listener options such
2697 as propagation to subclasses.
2698
2699 """
2700
2701
2702class QueryEvents(event.Events):
2703 """Represent events within the construction of a :class:`_query.Query`
2704 object.
2705
2706 The :class:`_orm.QueryEvents` hooks are now superseded by the
2707 :meth:`_orm.SessionEvents.do_orm_execute` event hook.
2708
2709 """
2710
2711 _target_class_doc = "SomeQuery"
2712 _dispatch_target = Query
2713
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.
2718
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.
2728
2729
2730 This event is intended to allow changes to the query given::
2731
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
2739
2740 The event should normally be listened with the ``retval=True``
2741 parameter set, so that the modified query may be returned.
2742
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::
2751
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
2760
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.
2764
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.
2769
2770 .. seealso::
2771
2772 :meth:`.QueryEvents.before_compile_update`
2773
2774 :meth:`.QueryEvents.before_compile_delete`
2775
2776 :ref:`baked_with_before_compile`
2777
2778 """
2779
2780 def before_compile_update(self, query, update_context):
2781 """Allow modifications to the :class:`_query.Query` object within
2782 :meth:`_query.Query.update`.
2783
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.
2787
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 ::
2792
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)
2799
2800 update_context.values['timestamp'] = datetime.utcnow()
2801 return query
2802
2803 The ``.values`` dictionary of the "update context" object can also
2804 be modified in place as illustrated above.
2805
2806 :param query: a :class:`_query.Query` instance; this is also
2807 the ``.query`` attribute of the given "update context"
2808 object.
2809
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.
2818
2819 .. versionadded:: 1.2.17
2820
2821 .. seealso::
2822
2823 :meth:`.QueryEvents.before_compile`
2824
2825 :meth:`.QueryEvents.before_compile_delete`
2826
2827
2828 """
2829
2830 def before_compile_delete(self, query, delete_context):
2831 """Allow modifications to the :class:`_query.Query` object within
2832 :meth:`_query.Query.delete`.
2833
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.
2837
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 ::
2841
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
2849
2850 :param query: a :class:`_query.Query` instance; this is also
2851 the ``.query`` attribute of the given "delete context"
2852 object.
2853
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`.
2857
2858 .. versionadded:: 1.2.17
2859
2860 .. seealso::
2861
2862 :meth:`.QueryEvents.before_compile`
2863
2864 :meth:`.QueryEvents.before_compile_update`
2865
2866
2867 """
2868
2869 @classmethod
2870 def _listen(cls, event_key, retval=False, bake_ok=False, **kw):
2871 fn = event_key._listen_fn
2872
2873 if not retval:
2874
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)
2882
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)
2888
2889 event_key = event_key.with_wrapper(wrap)
2890
2891 wrap._bake_ok = bake_ok
2892
2893 event_key.base_listen(**kw)