Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# orm/events.py
2# Copyright (C) 2005-2025 the SQLAlchemy authors and contributors
3# <see AUTHORS file>
4#
5# This module is part of SQLAlchemy and is released under
6# the MIT License: https://www.opensource.org/licenses/mit-license.php
8"""ORM event interfaces."""
9from __future__ import annotations
11from typing import Any
12from typing import Callable
13from typing import Collection
14from typing import Dict
15from typing import Generic
16from typing import Iterable
17from typing import Optional
18from typing import Sequence
19from typing import Set
20from typing import Type
21from typing import TYPE_CHECKING
22from typing import TypeVar
23from typing import Union
24import weakref
26from . import instrumentation
27from . import interfaces
28from . import mapperlib
29from .attributes import QueryableAttribute
30from .base import _mapper_or_none
31from .base import NO_KEY
32from .instrumentation import ClassManager
33from .instrumentation import InstrumentationFactory
34from .query import BulkDelete
35from .query import BulkUpdate
36from .query import Query
37from .scoping import scoped_session
38from .session import Session
39from .session import sessionmaker
40from .. import event
41from .. import exc
42from .. import util
43from ..event import EventTarget
44from ..event.registry import _ET
45from ..util.compat import inspect_getfullargspec
47if TYPE_CHECKING:
48 from weakref import ReferenceType
50 from ._typing import _InstanceDict
51 from ._typing import _InternalEntityType
52 from ._typing import _O
53 from ._typing import _T
54 from .attributes import Event
55 from .base import EventConstants
56 from .session import ORMExecuteState
57 from .session import SessionTransaction
58 from .unitofwork import UOWTransaction
59 from ..engine import Connection
60 from ..event.base import _Dispatch
61 from ..event.base import _HasEventsDispatch
62 from ..event.registry import _EventKey
63 from ..orm.collections import CollectionAdapter
64 from ..orm.context import QueryContext
65 from ..orm.decl_api import DeclarativeAttributeIntercept
66 from ..orm.decl_api import DeclarativeMeta
67 from ..orm.mapper import Mapper
68 from ..orm.state import InstanceState
70_KT = TypeVar("_KT", bound=Any)
71_ET2 = TypeVar("_ET2", bound=EventTarget)
74class InstrumentationEvents(event.Events[InstrumentationFactory]):
75 """Events related to class instrumentation events.
77 The listeners here support being established against
78 any new style class, that is any object that is a subclass
79 of 'type'. Events will then be fired off for events
80 against that class. If the "propagate=True" flag is passed
81 to event.listen(), the event will fire off for subclasses
82 of that class as well.
84 The Python ``type`` builtin is also accepted as a target,
85 which when used has the effect of events being emitted
86 for all classes.
88 Note the "propagate" flag here is defaulted to ``True``,
89 unlike the other class level events where it defaults
90 to ``False``. This means that new subclasses will also
91 be the subject of these events, when a listener
92 is established on a superclass.
94 """
96 _target_class_doc = "SomeBaseClass"
97 _dispatch_target = InstrumentationFactory
99 @classmethod
100 def _accept_with(
101 cls,
102 target: Union[
103 InstrumentationFactory,
104 Type[InstrumentationFactory],
105 ],
106 identifier: str,
107 ) -> Optional[
108 Union[
109 InstrumentationFactory,
110 Type[InstrumentationFactory],
111 ]
112 ]:
113 if isinstance(target, type):
114 return _InstrumentationEventsHold(target) # type: ignore [return-value] # noqa: E501
115 else:
116 return None
118 @classmethod
119 def _listen(
120 cls, event_key: _EventKey[_T], propagate: bool = True, **kw: Any
121 ) -> None:
122 target, identifier, fn = (
123 event_key.dispatch_target,
124 event_key.identifier,
125 event_key._listen_fn,
126 )
128 def listen(target_cls: type, *arg: Any) -> Optional[Any]:
129 listen_cls = target()
131 # if weakref were collected, however this is not something
132 # that normally happens. it was occurring during test teardown
133 # between mapper/registry/instrumentation_manager, however this
134 # interaction was changed to not rely upon the event system.
135 if listen_cls is None:
136 return None
138 if propagate and issubclass(target_cls, listen_cls):
139 return fn(target_cls, *arg)
140 elif not propagate and target_cls is listen_cls:
141 return fn(target_cls, *arg)
142 else:
143 return None
145 def remove(ref: ReferenceType[_T]) -> None:
146 key = event.registry._EventKey( # type: ignore [type-var]
147 None,
148 identifier,
149 listen,
150 instrumentation._instrumentation_factory,
151 )
152 getattr(
153 instrumentation._instrumentation_factory.dispatch, identifier
154 ).remove(key)
156 target = weakref.ref(target.class_, remove)
158 event_key.with_dispatch_target(
159 instrumentation._instrumentation_factory
160 ).with_wrapper(listen).base_listen(**kw)
162 @classmethod
163 def _clear(cls) -> None:
164 super()._clear()
165 instrumentation._instrumentation_factory.dispatch._clear()
167 def class_instrument(self, cls: ClassManager[_O]) -> None:
168 """Called after the given class is instrumented.
170 To get at the :class:`.ClassManager`, use
171 :func:`.manager_of_class`.
173 """
175 def class_uninstrument(self, cls: ClassManager[_O]) -> None:
176 """Called before the given class is uninstrumented.
178 To get at the :class:`.ClassManager`, use
179 :func:`.manager_of_class`.
181 """
183 def attribute_instrument(
184 self, cls: ClassManager[_O], key: _KT, inst: _O
185 ) -> None:
186 """Called when an attribute is instrumented."""
189class _InstrumentationEventsHold:
190 """temporary marker object used to transfer from _accept_with() to
191 _listen() on the InstrumentationEvents class.
193 """
195 def __init__(self, class_: type) -> None:
196 self.class_ = class_
198 dispatch = event.dispatcher(InstrumentationEvents)
201class InstanceEvents(event.Events[ClassManager[Any]]):
202 """Define events specific to object lifecycle.
204 e.g.::
206 from sqlalchemy import event
209 def my_load_listener(target, context):
210 print("on load!")
213 event.listen(SomeClass, "load", my_load_listener)
215 Available targets include:
217 * mapped classes
218 * unmapped superclasses of mapped or to-be-mapped classes
219 (using the ``propagate=True`` flag)
220 * :class:`_orm.Mapper` objects
221 * the :class:`_orm.Mapper` class itself indicates listening for all
222 mappers.
224 Instance events are closely related to mapper events, but
225 are more specific to the instance and its instrumentation,
226 rather than its system of persistence.
228 When using :class:`.InstanceEvents`, several modifiers are
229 available to the :func:`.event.listen` function.
231 :param propagate=False: When True, the event listener should
232 be applied to all inheriting classes as well as the
233 class which is the target of this listener.
234 :param raw=False: When True, the "target" argument passed
235 to applicable event listener functions will be the
236 instance's :class:`.InstanceState` management
237 object, rather than the mapped instance itself.
238 :param restore_load_context=False: Applies to the
239 :meth:`.InstanceEvents.load` and :meth:`.InstanceEvents.refresh`
240 events. Restores the loader context of the object when the event
241 hook is complete, so that ongoing eager load operations continue
242 to target the object appropriately. A warning is emitted if the
243 object is moved to a new loader context from within one of these
244 events if this flag is not set.
246 """
248 _target_class_doc = "SomeClass"
250 _dispatch_target = ClassManager
252 @classmethod
253 def _new_classmanager_instance(
254 cls,
255 class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type],
256 classmanager: ClassManager[_O],
257 ) -> None:
258 _InstanceEventsHold.populate(class_, classmanager)
260 @classmethod
261 @util.preload_module("sqlalchemy.orm")
262 def _accept_with(
263 cls,
264 target: Union[
265 ClassManager[Any],
266 Type[ClassManager[Any]],
267 ],
268 identifier: str,
269 ) -> Optional[Union[ClassManager[Any], Type[ClassManager[Any]]]]:
270 orm = util.preloaded.orm
272 if isinstance(target, ClassManager):
273 return target
274 elif isinstance(target, mapperlib.Mapper):
275 return target.class_manager
276 elif target is orm.mapper: # type: ignore [attr-defined]
277 util.warn_deprecated(
278 "The `sqlalchemy.orm.mapper()` symbol is deprecated and "
279 "will be removed in a future release. For the mapper-wide "
280 "event target, use the 'sqlalchemy.orm.Mapper' class.",
281 "2.0",
282 )
283 return ClassManager
284 elif isinstance(target, type):
285 if issubclass(target, mapperlib.Mapper):
286 return ClassManager
287 else:
288 manager = instrumentation.opt_manager_of_class(target)
289 if manager:
290 return manager
291 else:
292 return _InstanceEventsHold(target) # type: ignore [return-value] # noqa: E501
293 return None
295 @classmethod
296 def _listen(
297 cls,
298 event_key: _EventKey[ClassManager[Any]],
299 raw: bool = False,
300 propagate: bool = False,
301 restore_load_context: bool = False,
302 **kw: Any,
303 ) -> None:
304 target, fn = (event_key.dispatch_target, event_key._listen_fn)
306 if not raw or restore_load_context:
308 def wrap(
309 state: InstanceState[_O], *arg: Any, **kw: Any
310 ) -> Optional[Any]:
311 if not raw:
312 target: Any = state.obj()
313 else:
314 target = state
315 if restore_load_context:
316 runid = state.runid
317 try:
318 return fn(target, *arg, **kw)
319 finally:
320 if restore_load_context:
321 state.runid = runid
323 event_key = event_key.with_wrapper(wrap)
325 event_key.base_listen(propagate=propagate, **kw)
327 if propagate:
328 for mgr in target.subclass_managers(True):
329 event_key.with_dispatch_target(mgr).base_listen(propagate=True)
331 @classmethod
332 def _clear(cls) -> None:
333 super()._clear()
334 _InstanceEventsHold._clear()
336 def init(self, target: _O, args: Any, kwargs: Any) -> None:
337 """Receive an instance when its constructor is called.
339 This method is only called during a userland construction of
340 an object, in conjunction with the object's constructor, e.g.
341 its ``__init__`` method. It is not called when an object is
342 loaded from the database; see the :meth:`.InstanceEvents.load`
343 event in order to intercept a database load.
345 The event is called before the actual ``__init__`` constructor
346 of the object is called. The ``kwargs`` dictionary may be
347 modified in-place in order to affect what is passed to
348 ``__init__``.
350 :param target: the mapped instance. If
351 the event is configured with ``raw=True``, this will
352 instead be the :class:`.InstanceState` state-management
353 object associated with the instance.
354 :param args: positional arguments passed to the ``__init__`` method.
355 This is passed as a tuple and is currently immutable.
356 :param kwargs: keyword arguments passed to the ``__init__`` method.
357 This structure *can* be altered in place.
359 .. seealso::
361 :meth:`.InstanceEvents.init_failure`
363 :meth:`.InstanceEvents.load`
365 """
367 def init_failure(self, target: _O, args: Any, kwargs: Any) -> None:
368 """Receive an instance when its constructor has been called,
369 and raised an exception.
371 This method is only called during a userland construction of
372 an object, in conjunction with the object's constructor, e.g.
373 its ``__init__`` method. It is not called when an object is loaded
374 from the database.
376 The event is invoked after an exception raised by the ``__init__``
377 method is caught. After the event
378 is invoked, the original exception is re-raised outwards, so that
379 the construction of the object still raises an exception. The
380 actual exception and stack trace raised should be present in
381 ``sys.exc_info()``.
383 :param target: the mapped instance. If
384 the event is configured with ``raw=True``, this will
385 instead be the :class:`.InstanceState` state-management
386 object associated with the instance.
387 :param args: positional arguments that were passed to the ``__init__``
388 method.
389 :param kwargs: keyword arguments that were passed to the ``__init__``
390 method.
392 .. seealso::
394 :meth:`.InstanceEvents.init`
396 :meth:`.InstanceEvents.load`
398 """
400 def _sa_event_merge_wo_load(
401 self, target: _O, context: QueryContext
402 ) -> None:
403 """receive an object instance after it was the subject of a merge()
404 call, when load=False was passed.
406 The target would be the already-loaded object in the Session which
407 would have had its attributes overwritten by the incoming object. This
408 overwrite operation does not use attribute events, instead just
409 populating dict directly. Therefore the purpose of this event is so
410 that extensions like sqlalchemy.ext.mutable know that object state has
411 changed and incoming state needs to be set up for "parents" etc.
413 This functionality is acceptable to be made public in a later release.
415 .. versionadded:: 1.4.41
417 """
419 def load(self, target: _O, context: QueryContext) -> None:
420 """Receive an object instance after it has been created via
421 ``__new__``, and after initial attribute population has
422 occurred.
424 This typically occurs when the instance is created based on
425 incoming result rows, and is only called once for that
426 instance's lifetime.
428 .. warning::
430 During a result-row load, this event is invoked when the
431 first row received for this instance is processed. When using
432 eager loading with collection-oriented attributes, the additional
433 rows that are to be loaded / processed in order to load subsequent
434 collection items have not occurred yet. This has the effect
435 both that collections will not be fully loaded, as well as that
436 if an operation occurs within this event handler that emits
437 another database load operation for the object, the "loading
438 context" for the object can change and interfere with the
439 existing eager loaders still in progress.
441 Examples of what can cause the "loading context" to change within
442 the event handler include, but are not necessarily limited to:
444 * accessing deferred attributes that weren't part of the row,
445 will trigger an "undefer" operation and refresh the object
447 * accessing attributes on a joined-inheritance subclass that
448 weren't part of the row, will trigger a refresh operation.
450 As of SQLAlchemy 1.3.14, a warning is emitted when this occurs. The
451 :paramref:`.InstanceEvents.restore_load_context` option may be
452 used on the event to prevent this warning; this will ensure that
453 the existing loading context is maintained for the object after the
454 event is called::
456 @event.listens_for(SomeClass, "load", restore_load_context=True)
457 def on_load(instance, context):
458 instance.some_unloaded_attribute
460 The :meth:`.InstanceEvents.load` event is also available in a
461 class-method decorator format called :func:`_orm.reconstructor`.
463 :param target: the mapped instance. If
464 the event is configured with ``raw=True``, this will
465 instead be the :class:`.InstanceState` state-management
466 object associated with the instance.
467 :param context: the :class:`.QueryContext` corresponding to the
468 current :class:`_query.Query` in progress. This argument may be
469 ``None`` if the load does not correspond to a :class:`_query.Query`,
470 such as during :meth:`.Session.merge`.
472 .. seealso::
474 :ref:`mapped_class_load_events`
476 :meth:`.InstanceEvents.init`
478 :meth:`.InstanceEvents.refresh`
480 :meth:`.SessionEvents.loaded_as_persistent`
482 """ # noqa: E501
484 def refresh(
485 self, target: _O, context: QueryContext, attrs: Optional[Iterable[str]]
486 ) -> None:
487 """Receive an object instance after one or more attributes have
488 been refreshed from a query.
490 Contrast this to the :meth:`.InstanceEvents.load` method, which
491 is invoked when the object is first loaded from a query.
493 .. note:: This event is invoked within the loader process before
494 eager loaders may have been completed, and the object's state may
495 not be complete. Additionally, invoking row-level refresh
496 operations on the object will place the object into a new loader
497 context, interfering with the existing load context. See the note
498 on :meth:`.InstanceEvents.load` for background on making use of the
499 :paramref:`.InstanceEvents.restore_load_context` parameter, in
500 order to resolve this scenario.
502 :param target: the mapped instance. If
503 the event is configured with ``raw=True``, this will
504 instead be the :class:`.InstanceState` state-management
505 object associated with the instance.
506 :param context: the :class:`.QueryContext` corresponding to the
507 current :class:`_query.Query` in progress.
508 :param attrs: sequence of attribute names which
509 were populated, or None if all column-mapped, non-deferred
510 attributes were populated.
512 .. seealso::
514 :ref:`mapped_class_load_events`
516 :meth:`.InstanceEvents.load`
518 """
520 def refresh_flush(
521 self,
522 target: _O,
523 flush_context: UOWTransaction,
524 attrs: Optional[Iterable[str]],
525 ) -> None:
526 """Receive an object instance after one or more attributes that
527 contain a column-level default or onupdate handler have been refreshed
528 during persistence of the object's state.
530 This event is the same as :meth:`.InstanceEvents.refresh` except
531 it is invoked within the unit of work flush process, and includes
532 only non-primary-key columns that have column level default or
533 onupdate handlers, including Python callables as well as server side
534 defaults and triggers which may be fetched via the RETURNING clause.
536 .. note::
538 While the :meth:`.InstanceEvents.refresh_flush` event is triggered
539 for an object that was INSERTed as well as for an object that was
540 UPDATEd, the event is geared primarily towards the UPDATE process;
541 it is mostly an internal artifact that INSERT actions can also
542 trigger this event, and note that **primary key columns for an
543 INSERTed row are explicitly omitted** from this event. In order to
544 intercept the newly INSERTed state of an object, the
545 :meth:`.SessionEvents.pending_to_persistent` and
546 :meth:`.MapperEvents.after_insert` are better choices.
548 :param target: the mapped instance. If
549 the event is configured with ``raw=True``, this will
550 instead be the :class:`.InstanceState` state-management
551 object associated with the instance.
552 :param flush_context: Internal :class:`.UOWTransaction` object
553 which handles the details of the flush.
554 :param attrs: sequence of attribute names which
555 were populated.
557 .. seealso::
559 :ref:`mapped_class_load_events`
561 :ref:`orm_server_defaults`
563 :ref:`metadata_defaults_toplevel`
565 """
567 def expire(self, target: _O, attrs: Optional[Iterable[str]]) -> None:
568 """Receive an object instance after its attributes or some subset
569 have been expired.
571 'keys' is a list of attribute names. If None, the entire
572 state was expired.
574 :param target: the mapped instance. If
575 the event is configured with ``raw=True``, this will
576 instead be the :class:`.InstanceState` state-management
577 object associated with the instance.
578 :param attrs: sequence of attribute
579 names which were expired, or None if all attributes were
580 expired.
582 """
584 def pickle(self, target: _O, state_dict: _InstanceDict) -> None:
585 """Receive an object instance when its associated state is
586 being pickled.
588 :param target: the mapped instance. If
589 the event is configured with ``raw=True``, this will
590 instead be the :class:`.InstanceState` state-management
591 object associated with the instance.
592 :param state_dict: the dictionary returned by
593 :class:`.InstanceState.__getstate__`, containing the state
594 to be pickled.
596 """
598 def unpickle(self, target: _O, state_dict: _InstanceDict) -> None:
599 """Receive an object instance after its associated state has
600 been unpickled.
602 :param target: the mapped instance. If
603 the event is configured with ``raw=True``, this will
604 instead be the :class:`.InstanceState` state-management
605 object associated with the instance.
606 :param state_dict: the dictionary sent to
607 :class:`.InstanceState.__setstate__`, containing the state
608 dictionary which was pickled.
610 """
613class _EventsHold(event.RefCollection[_ET]):
614 """Hold onto listeners against unmapped, uninstrumented classes.
616 Establish _listen() for that class' mapper/instrumentation when
617 those objects are created for that class.
619 """
621 all_holds: weakref.WeakKeyDictionary[Any, Any]
623 def __init__(
624 self,
625 class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type],
626 ) -> None:
627 self.class_ = class_
629 @classmethod
630 def _clear(cls) -> None:
631 cls.all_holds.clear()
633 class HoldEvents(Generic[_ET2]):
634 _dispatch_target: Optional[Type[_ET2]] = None
636 @classmethod
637 def _listen(
638 cls,
639 event_key: _EventKey[_ET2],
640 raw: bool = False,
641 propagate: bool = False,
642 retval: bool = False,
643 **kw: Any,
644 ) -> None:
645 target = event_key.dispatch_target
647 if target.class_ in target.all_holds:
648 collection = target.all_holds[target.class_]
649 else:
650 collection = target.all_holds[target.class_] = {}
652 event.registry._stored_in_collection(event_key, target)
653 collection[event_key._key] = (
654 event_key,
655 raw,
656 propagate,
657 retval,
658 kw,
659 )
661 if propagate:
662 stack = list(target.class_.__subclasses__())
663 while stack:
664 subclass = stack.pop(0)
665 stack.extend(subclass.__subclasses__())
666 subject = target.resolve(subclass)
667 if subject is not None:
668 # we are already going through __subclasses__()
669 # so leave generic propagate flag False
670 event_key.with_dispatch_target(subject).listen(
671 raw=raw, propagate=False, retval=retval, **kw
672 )
674 def remove(self, event_key: _EventKey[_ET]) -> None:
675 target = event_key.dispatch_target
677 if isinstance(target, _EventsHold):
678 collection = target.all_holds[target.class_]
679 del collection[event_key._key]
681 @classmethod
682 def populate(
683 cls,
684 class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type],
685 subject: Union[ClassManager[_O], Mapper[_O]],
686 ) -> None:
687 for subclass in class_.__mro__:
688 if subclass in cls.all_holds:
689 collection = cls.all_holds[subclass]
690 for (
691 event_key,
692 raw,
693 propagate,
694 retval,
695 kw,
696 ) in collection.values():
697 if propagate or subclass is class_:
698 # since we can't be sure in what order different
699 # classes in a hierarchy are triggered with
700 # populate(), we rely upon _EventsHold for all event
701 # assignment, instead of using the generic propagate
702 # flag.
703 event_key.with_dispatch_target(subject).listen(
704 raw=raw, propagate=False, retval=retval, **kw
705 )
708class _InstanceEventsHold(_EventsHold[_ET]):
709 all_holds: weakref.WeakKeyDictionary[Any, Any] = (
710 weakref.WeakKeyDictionary()
711 )
713 def resolve(self, class_: Type[_O]) -> Optional[ClassManager[_O]]:
714 return instrumentation.opt_manager_of_class(class_)
716 class HoldInstanceEvents(_EventsHold.HoldEvents[_ET], InstanceEvents): # type: ignore [misc] # noqa: E501
717 pass
719 dispatch = event.dispatcher(HoldInstanceEvents)
722class MapperEvents(event.Events[mapperlib.Mapper[Any]]):
723 """Define events specific to mappings.
725 e.g.::
727 from sqlalchemy import event
730 def my_before_insert_listener(mapper, connection, target):
731 # execute a stored procedure upon INSERT,
732 # apply the value to the row to be inserted
733 target.calculated_value = connection.execute(
734 text("select my_special_function(%d)" % target.special_number)
735 ).scalar()
738 # associate the listener function with SomeClass,
739 # to execute during the "before_insert" hook
740 event.listen(SomeClass, "before_insert", my_before_insert_listener)
742 Available targets include:
744 * mapped classes
745 * unmapped superclasses of mapped or to-be-mapped classes
746 (using the ``propagate=True`` flag)
747 * :class:`_orm.Mapper` objects
748 * the :class:`_orm.Mapper` class itself indicates listening for all
749 mappers.
751 Mapper events provide hooks into critical sections of the
752 mapper, including those related to object instrumentation,
753 object loading, and object persistence. In particular, the
754 persistence methods :meth:`~.MapperEvents.before_insert`,
755 and :meth:`~.MapperEvents.before_update` are popular
756 places to augment the state being persisted - however, these
757 methods operate with several significant restrictions. The
758 user is encouraged to evaluate the
759 :meth:`.SessionEvents.before_flush` and
760 :meth:`.SessionEvents.after_flush` methods as more
761 flexible and user-friendly hooks in which to apply
762 additional database state during a flush.
764 When using :class:`.MapperEvents`, several modifiers are
765 available to the :func:`.event.listen` function.
767 :param propagate=False: When True, the event listener should
768 be applied to all inheriting mappers and/or the mappers of
769 inheriting classes, as well as any
770 mapper which is the target of this listener.
771 :param raw=False: When True, the "target" argument passed
772 to applicable event listener functions will be the
773 instance's :class:`.InstanceState` management
774 object, rather than the mapped instance itself.
775 :param retval=False: when True, the user-defined event function
776 must have a return value, the purpose of which is either to
777 control subsequent event propagation, or to otherwise alter
778 the operation in progress by the mapper. Possible return
779 values are:
781 * ``sqlalchemy.orm.interfaces.EXT_CONTINUE`` - continue event
782 processing normally.
783 * ``sqlalchemy.orm.interfaces.EXT_STOP`` - cancel all subsequent
784 event handlers in the chain.
785 * other values - the return value specified by specific listeners.
787 """
789 _target_class_doc = "SomeClass"
790 _dispatch_target = mapperlib.Mapper
792 @classmethod
793 def _new_mapper_instance(
794 cls,
795 class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type],
796 mapper: Mapper[_O],
797 ) -> None:
798 _MapperEventsHold.populate(class_, mapper)
800 @classmethod
801 @util.preload_module("sqlalchemy.orm")
802 def _accept_with(
803 cls,
804 target: Union[mapperlib.Mapper[Any], Type[mapperlib.Mapper[Any]]],
805 identifier: str,
806 ) -> Optional[Union[mapperlib.Mapper[Any], Type[mapperlib.Mapper[Any]]]]:
807 orm = util.preloaded.orm
809 if target is orm.mapper: # type: ignore [attr-defined]
810 util.warn_deprecated(
811 "The `sqlalchemy.orm.mapper()` symbol is deprecated and "
812 "will be removed in a future release. For the mapper-wide "
813 "event target, use the 'sqlalchemy.orm.Mapper' class.",
814 "2.0",
815 )
816 return mapperlib.Mapper
817 elif isinstance(target, type):
818 if issubclass(target, mapperlib.Mapper):
819 return target
820 else:
821 mapper = _mapper_or_none(target)
822 if mapper is not None:
823 return mapper
824 else:
825 return _MapperEventsHold(target)
826 else:
827 return target
829 @classmethod
830 def _listen(
831 cls,
832 event_key: _EventKey[_ET],
833 raw: bool = False,
834 retval: bool = False,
835 propagate: bool = False,
836 **kw: Any,
837 ) -> None:
838 target, identifier, fn = (
839 event_key.dispatch_target,
840 event_key.identifier,
841 event_key._listen_fn,
842 )
844 if (
845 identifier in ("before_configured", "after_configured")
846 and target is not mapperlib.Mapper
847 ):
848 util.warn(
849 "'before_configured' and 'after_configured' ORM events "
850 "only invoke with the Mapper class "
851 "as the target."
852 )
854 if not raw or not retval:
855 if not raw:
856 meth = getattr(cls, identifier)
857 try:
858 target_index = (
859 inspect_getfullargspec(meth)[0].index("target") - 1
860 )
861 except ValueError:
862 target_index = None
864 def wrap(*arg: Any, **kw: Any) -> Any:
865 if not raw and target_index is not None:
866 arg = list(arg) # type: ignore [assignment]
867 arg[target_index] = arg[target_index].obj() # type: ignore [index] # noqa: E501
868 if not retval:
869 fn(*arg, **kw)
870 return interfaces.EXT_CONTINUE
871 else:
872 return fn(*arg, **kw)
874 event_key = event_key.with_wrapper(wrap)
876 if propagate:
877 for mapper in target.self_and_descendants:
878 event_key.with_dispatch_target(mapper).base_listen(
879 propagate=True, **kw
880 )
881 else:
882 event_key.base_listen(**kw)
884 @classmethod
885 def _clear(cls) -> None:
886 super()._clear()
887 _MapperEventsHold._clear()
889 def instrument_class(self, mapper: Mapper[_O], class_: Type[_O]) -> None:
890 r"""Receive a class when the mapper is first constructed,
891 before instrumentation is applied to the mapped class.
893 This event is the earliest phase of mapper construction.
894 Most attributes of the mapper are not yet initialized. To
895 receive an event within initial mapper construction where basic
896 state is available such as the :attr:`_orm.Mapper.attrs` collection,
897 the :meth:`_orm.MapperEvents.after_mapper_constructed` event may
898 be a better choice.
900 This listener can either be applied to the :class:`_orm.Mapper`
901 class overall, or to any un-mapped class which serves as a base
902 for classes that will be mapped (using the ``propagate=True`` flag)::
904 Base = declarative_base()
907 @event.listens_for(Base, "instrument_class", propagate=True)
908 def on_new_class(mapper, cls_):
909 "..."
911 :param mapper: the :class:`_orm.Mapper` which is the target
912 of this event.
913 :param class\_: the mapped class.
915 .. seealso::
917 :meth:`_orm.MapperEvents.after_mapper_constructed`
919 """
921 def after_mapper_constructed(
922 self, mapper: Mapper[_O], class_: Type[_O]
923 ) -> None:
924 """Receive a class and mapper when the :class:`_orm.Mapper` has been
925 fully constructed.
927 This event is called after the initial constructor for
928 :class:`_orm.Mapper` completes. This occurs after the
929 :meth:`_orm.MapperEvents.instrument_class` event and after the
930 :class:`_orm.Mapper` has done an initial pass of its arguments
931 to generate its collection of :class:`_orm.MapperProperty` objects,
932 which are accessible via the :meth:`_orm.Mapper.get_property`
933 method and the :attr:`_orm.Mapper.iterate_properties` attribute.
935 This event differs from the
936 :meth:`_orm.MapperEvents.before_mapper_configured` event in that it
937 is invoked within the constructor for :class:`_orm.Mapper`, rather
938 than within the :meth:`_orm.registry.configure` process. Currently,
939 this event is the only one which is appropriate for handlers that
940 wish to create additional mapped classes in response to the
941 construction of this :class:`_orm.Mapper`, which will be part of the
942 same configure step when :meth:`_orm.registry.configure` next runs.
944 .. versionadded:: 2.0.2
946 .. seealso::
948 :ref:`examples_versioning` - an example which illustrates the use
949 of the :meth:`_orm.MapperEvents.before_mapper_configured`
950 event to create new mappers to record change-audit histories on
951 objects.
953 """
955 @event._omit_standard_example
956 def before_mapper_configured(
957 self, mapper: Mapper[_O], class_: Type[_O]
958 ) -> None:
959 """Called right before a specific mapper is to be configured.
961 The :meth:`.MapperEvents.before_mapper_configured` event is invoked
962 for each mapper that is encountered when the
963 :func:`_orm.configure_mappers` function proceeds through the current
964 list of not-yet-configured mappers. It is similar to the
965 :meth:`.MapperEvents.mapper_configured` event, except that it's invoked
966 right before the configuration occurs, rather than afterwards.
968 The :meth:`.MapperEvents.before_mapper_configured` event includes
969 the special capability where it can force the configure step for a
970 specific mapper to be skipped; to use this feature, establish
971 the event using the ``retval=True`` parameter and return
972 the :attr:`.orm.interfaces.EXT_SKIP` symbol to indicate the mapper
973 should be left unconfigured::
975 from sqlalchemy import event
976 from sqlalchemy.orm import EXT_SKIP
977 from sqlalchemy.orm import DeclarativeBase
980 class DontConfigureBase(DeclarativeBase):
981 pass
984 @event.listens_for(
985 DontConfigureBase,
986 "before_mapper_configured",
987 # support return values for the event
988 retval=True,
989 # propagate the listener to all subclasses of
990 # DontConfigureBase
991 propagate=True,
992 )
993 def dont_configure(mapper, cls):
994 return EXT_SKIP
996 .. seealso::
998 :meth:`.MapperEvents.before_configured`
1000 :meth:`.MapperEvents.after_configured`
1002 :meth:`.MapperEvents.mapper_configured`
1004 """
1006 def mapper_configured(self, mapper: Mapper[_O], class_: Type[_O]) -> None:
1007 r"""Called when a specific mapper has completed its own configuration
1008 within the scope of the :func:`.configure_mappers` call.
1010 The :meth:`.MapperEvents.mapper_configured` event is invoked
1011 for each mapper that is encountered when the
1012 :func:`_orm.configure_mappers` function proceeds through the current
1013 list of not-yet-configured mappers.
1014 :func:`_orm.configure_mappers` is typically invoked
1015 automatically as mappings are first used, as well as each time
1016 new mappers have been made available and new mapper use is
1017 detected.
1019 When the event is called, the mapper should be in its final
1020 state, but **not including backrefs** that may be invoked from
1021 other mappers; they might still be pending within the
1022 configuration operation. Bidirectional relationships that
1023 are instead configured via the
1024 :paramref:`.orm.relationship.back_populates` argument
1025 *will* be fully available, since this style of relationship does not
1026 rely upon other possibly-not-configured mappers to know that they
1027 exist.
1029 For an event that is guaranteed to have **all** mappers ready
1030 to go including backrefs that are defined only on other
1031 mappings, use the :meth:`.MapperEvents.after_configured`
1032 event; this event invokes only after all known mappings have been
1033 fully configured.
1035 The :meth:`.MapperEvents.mapper_configured` event, unlike the
1036 :meth:`.MapperEvents.before_configured` or
1037 :meth:`.MapperEvents.after_configured` events, is called for each
1038 mapper/class individually, and the mapper is passed to the event
1039 itself. It also is called exactly once for a particular mapper. The
1040 event is therefore useful for configurational steps that benefit from
1041 being invoked just once on a specific mapper basis, which don't require
1042 that "backref" configurations are necessarily ready yet.
1044 :param mapper: the :class:`_orm.Mapper` which is the target
1045 of this event.
1046 :param class\_: the mapped class.
1048 .. seealso::
1050 :meth:`.MapperEvents.before_configured`
1052 :meth:`.MapperEvents.after_configured`
1054 :meth:`.MapperEvents.before_mapper_configured`
1056 """
1057 # TODO: need coverage for this event
1059 @event._omit_standard_example
1060 def before_configured(self) -> None:
1061 """Called before a series of mappers have been configured.
1063 The :meth:`.MapperEvents.before_configured` event is invoked
1064 each time the :func:`_orm.configure_mappers` function is
1065 invoked, before the function has done any of its work.
1066 :func:`_orm.configure_mappers` is typically invoked
1067 automatically as mappings are first used, as well as each time
1068 new mappers have been made available and new mapper use is
1069 detected.
1071 Similar events to this one include
1072 :meth:`.MapperEvents.after_configured`, which is invoked after a series
1073 of mappers has been configured, as well as
1074 :meth:`.MapperEvents.before_mapper_configured` and
1075 :meth:`.MapperEvents.mapper_configured`, which are both invoked on a
1076 per-mapper basis.
1078 This event can **only** be applied to the :class:`_orm.Mapper` class,
1079 and not to individual mappings or mapped classes::
1081 from sqlalchemy.orm import Mapper
1084 @event.listens_for(Mapper, "before_configured")
1085 def go(): ...
1087 Typically, this event is called once per application, but in practice
1088 may be called more than once, any time new mappers are to be affected
1089 by a :func:`_orm.configure_mappers` call. If new mappings are
1090 constructed after existing ones have already been used, this event will
1091 likely be called again.
1093 .. seealso::
1095 :meth:`.MapperEvents.before_mapper_configured`
1097 :meth:`.MapperEvents.mapper_configured`
1099 :meth:`.MapperEvents.after_configured`
1101 """
1103 @event._omit_standard_example
1104 def after_configured(self) -> None:
1105 """Called after a series of mappers have been configured.
1107 The :meth:`.MapperEvents.after_configured` event is invoked
1108 each time the :func:`_orm.configure_mappers` function is
1109 invoked, after the function has completed its work.
1110 :func:`_orm.configure_mappers` is typically invoked
1111 automatically as mappings are first used, as well as each time
1112 new mappers have been made available and new mapper use is
1113 detected.
1115 Similar events to this one include
1116 :meth:`.MapperEvents.before_configured`, which is invoked before a
1117 series of mappers are configured, as well as
1118 :meth:`.MapperEvents.before_mapper_configured` and
1119 :meth:`.MapperEvents.mapper_configured`, which are both invoked on a
1120 per-mapper basis.
1122 This event can **only** be applied to the :class:`_orm.Mapper` class,
1123 and not to individual mappings or mapped classes::
1125 from sqlalchemy.orm import Mapper
1128 @event.listens_for(Mapper, "after_configured")
1129 def go(): ...
1131 Typically, this event is called once per application, but in practice
1132 may be called more than once, any time new mappers are to be affected
1133 by a :func:`_orm.configure_mappers` call. If new mappings are
1134 constructed after existing ones have already been used, this event will
1135 likely be called again.
1137 .. seealso::
1139 :meth:`.MapperEvents.before_mapper_configured`
1141 :meth:`.MapperEvents.mapper_configured`
1143 :meth:`.MapperEvents.before_configured`
1145 """
1147 def before_insert(
1148 self, mapper: Mapper[_O], connection: Connection, target: _O
1149 ) -> None:
1150 """Receive an object instance before an INSERT statement
1151 is emitted corresponding to that instance.
1153 .. note:: this event **only** applies to the
1154 :ref:`session flush operation <session_flushing>`
1155 and does **not** apply to the ORM DML operations described at
1156 :ref:`orm_expression_update_delete`. To intercept ORM
1157 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1159 This event is used to modify local, non-object related
1160 attributes on the instance before an INSERT occurs, as well
1161 as to emit additional SQL statements on the given
1162 connection.
1164 The event is often called for a batch of objects of the
1165 same class before their INSERT statements are emitted at
1166 once in a later step. In the extremely rare case that
1167 this is not desirable, the :class:`_orm.Mapper` object can be
1168 configured with ``batch=False``, which will cause
1169 batches of instances to be broken up into individual
1170 (and more poorly performing) event->persist->event
1171 steps.
1173 .. warning::
1175 Mapper-level flush events only allow **very limited operations**,
1176 on attributes local to the row being operated upon only,
1177 as well as allowing any SQL to be emitted on the given
1178 :class:`_engine.Connection`. **Please read fully** the notes
1179 at :ref:`session_persistence_mapper` for guidelines on using
1180 these methods; generally, the :meth:`.SessionEvents.before_flush`
1181 method should be preferred for general on-flush changes.
1183 :param mapper: the :class:`_orm.Mapper` which is the target
1184 of this event.
1185 :param connection: the :class:`_engine.Connection` being used to
1186 emit INSERT statements for this instance. This
1187 provides a handle into the current transaction on the
1188 target database specific to this instance.
1189 :param target: the mapped instance being persisted. If
1190 the event is configured with ``raw=True``, this will
1191 instead be the :class:`.InstanceState` state-management
1192 object associated with the instance.
1193 :return: No return value is supported by this event.
1195 .. seealso::
1197 :ref:`session_persistence_events`
1199 """
1201 def after_insert(
1202 self, mapper: Mapper[_O], connection: Connection, target: _O
1203 ) -> None:
1204 """Receive an object instance after an INSERT statement
1205 is emitted corresponding to that instance.
1207 .. note:: this event **only** applies to the
1208 :ref:`session flush operation <session_flushing>`
1209 and does **not** apply to the ORM DML operations described at
1210 :ref:`orm_expression_update_delete`. To intercept ORM
1211 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1213 This event is used to modify in-Python-only
1214 state on the instance after an INSERT occurs, as well
1215 as to emit additional SQL statements on the given
1216 connection.
1218 The event is often called for a batch of objects of the
1219 same class after their INSERT statements have been
1220 emitted at once in a previous step. In the extremely
1221 rare case that this is not desirable, the
1222 :class:`_orm.Mapper` object can be configured with ``batch=False``,
1223 which will cause batches of instances to be broken up
1224 into individual (and more poorly performing)
1225 event->persist->event steps.
1227 .. warning::
1229 Mapper-level flush events only allow **very limited operations**,
1230 on attributes local to the row being operated upon only,
1231 as well as allowing any SQL to be emitted on the given
1232 :class:`_engine.Connection`. **Please read fully** the notes
1233 at :ref:`session_persistence_mapper` for guidelines on using
1234 these methods; generally, the :meth:`.SessionEvents.before_flush`
1235 method should be preferred for general on-flush changes.
1237 :param mapper: the :class:`_orm.Mapper` which is the target
1238 of this event.
1239 :param connection: the :class:`_engine.Connection` being used to
1240 emit INSERT statements for this instance. This
1241 provides a handle into the current transaction on the
1242 target database specific to this instance.
1243 :param target: the mapped instance being persisted. If
1244 the event is configured with ``raw=True``, this will
1245 instead be the :class:`.InstanceState` state-management
1246 object associated with the instance.
1247 :return: No return value is supported by this event.
1249 .. seealso::
1251 :ref:`session_persistence_events`
1253 """
1255 def before_update(
1256 self, mapper: Mapper[_O], connection: Connection, target: _O
1257 ) -> None:
1258 """Receive an object instance before an UPDATE statement
1259 is emitted corresponding to that instance.
1261 .. note:: this event **only** applies to the
1262 :ref:`session flush operation <session_flushing>`
1263 and does **not** apply to the ORM DML operations described at
1264 :ref:`orm_expression_update_delete`. To intercept ORM
1265 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1267 This event is used to modify local, non-object related
1268 attributes on the instance before an UPDATE occurs, as well
1269 as to emit additional SQL statements on the given
1270 connection.
1272 This method is called for all instances that are
1273 marked as "dirty", *even those which have no net changes
1274 to their column-based attributes*. An object is marked
1275 as dirty when any of its column-based attributes have a
1276 "set attribute" operation called or when any of its
1277 collections are modified. If, at update time, no
1278 column-based attributes have any net changes, no UPDATE
1279 statement will be issued. This means that an instance
1280 being sent to :meth:`~.MapperEvents.before_update` is
1281 *not* a guarantee that an UPDATE statement will be
1282 issued, although you can affect the outcome here by
1283 modifying attributes so that a net change in value does
1284 exist.
1286 To detect if the column-based attributes on the object have net
1287 changes, and will therefore generate an UPDATE statement, use
1288 ``object_session(instance).is_modified(instance,
1289 include_collections=False)``.
1291 The event is often called for a batch of objects of the
1292 same class before their UPDATE statements are emitted at
1293 once in a later step. In the extremely rare case that
1294 this is not desirable, the :class:`_orm.Mapper` can be
1295 configured with ``batch=False``, which will cause
1296 batches of instances to be broken up into individual
1297 (and more poorly performing) event->persist->event
1298 steps.
1300 .. warning::
1302 Mapper-level flush events only allow **very limited operations**,
1303 on attributes local to the row being operated upon only,
1304 as well as allowing any SQL to be emitted on the given
1305 :class:`_engine.Connection`. **Please read fully** the notes
1306 at :ref:`session_persistence_mapper` for guidelines on using
1307 these methods; generally, the :meth:`.SessionEvents.before_flush`
1308 method should be preferred for general on-flush changes.
1310 :param mapper: the :class:`_orm.Mapper` which is the target
1311 of this event.
1312 :param connection: the :class:`_engine.Connection` being used to
1313 emit UPDATE statements for this instance. This
1314 provides a handle into the current transaction on the
1315 target database specific to this instance.
1316 :param target: the mapped instance being persisted. If
1317 the event is configured with ``raw=True``, this will
1318 instead be the :class:`.InstanceState` state-management
1319 object associated with the instance.
1320 :return: No return value is supported by this event.
1322 .. seealso::
1324 :ref:`session_persistence_events`
1326 """
1328 def after_update(
1329 self, mapper: Mapper[_O], connection: Connection, target: _O
1330 ) -> None:
1331 """Receive an object instance after an UPDATE statement
1332 is emitted corresponding to that instance.
1334 .. note:: this event **only** applies to the
1335 :ref:`session flush operation <session_flushing>`
1336 and does **not** apply to the ORM DML operations described at
1337 :ref:`orm_expression_update_delete`. To intercept ORM
1338 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1340 This event is used to modify in-Python-only
1341 state on the instance after an UPDATE occurs, as well
1342 as to emit additional SQL statements on the given
1343 connection.
1345 This method is called for all instances that are
1346 marked as "dirty", *even those which have no net changes
1347 to their column-based attributes*, and for which
1348 no UPDATE statement has proceeded. An object is marked
1349 as dirty when any of its column-based attributes have a
1350 "set attribute" operation called or when any of its
1351 collections are modified. If, at update time, no
1352 column-based attributes have any net changes, no UPDATE
1353 statement will be issued. This means that an instance
1354 being sent to :meth:`~.MapperEvents.after_update` is
1355 *not* a guarantee that an UPDATE statement has been
1356 issued.
1358 To detect if the column-based attributes on the object have net
1359 changes, and therefore resulted in an UPDATE statement, use
1360 ``object_session(instance).is_modified(instance,
1361 include_collections=False)``.
1363 The event is often called for a batch of objects of the
1364 same class after their UPDATE statements have been emitted at
1365 once in a previous step. In the extremely rare case that
1366 this is not desirable, the :class:`_orm.Mapper` can be
1367 configured with ``batch=False``, which will cause
1368 batches of instances to be broken up into individual
1369 (and more poorly performing) event->persist->event
1370 steps.
1372 .. warning::
1374 Mapper-level flush events only allow **very limited operations**,
1375 on attributes local to the row being operated upon only,
1376 as well as allowing any SQL to be emitted on the given
1377 :class:`_engine.Connection`. **Please read fully** the notes
1378 at :ref:`session_persistence_mapper` for guidelines on using
1379 these methods; generally, the :meth:`.SessionEvents.before_flush`
1380 method should be preferred for general on-flush changes.
1382 :param mapper: the :class:`_orm.Mapper` which is the target
1383 of this event.
1384 :param connection: the :class:`_engine.Connection` being used to
1385 emit UPDATE statements for this instance. This
1386 provides a handle into the current transaction on the
1387 target database specific to this instance.
1388 :param target: the mapped instance being persisted. If
1389 the event is configured with ``raw=True``, this will
1390 instead be the :class:`.InstanceState` state-management
1391 object associated with the instance.
1392 :return: No return value is supported by this event.
1394 .. seealso::
1396 :ref:`session_persistence_events`
1398 """
1400 def before_delete(
1401 self, mapper: Mapper[_O], connection: Connection, target: _O
1402 ) -> None:
1403 """Receive an object instance before a DELETE statement
1404 is emitted corresponding to that instance.
1406 .. note:: this event **only** applies to the
1407 :ref:`session flush operation <session_flushing>`
1408 and does **not** apply to the ORM DML operations described at
1409 :ref:`orm_expression_update_delete`. To intercept ORM
1410 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1412 This event is used to emit additional SQL statements on
1413 the given connection as well as to perform application
1414 specific bookkeeping related to a deletion event.
1416 The event is often called for a batch of objects of the
1417 same class before their DELETE statements are emitted at
1418 once in a later step.
1420 .. warning::
1422 Mapper-level flush events only allow **very limited operations**,
1423 on attributes local to the row being operated upon only,
1424 as well as allowing any SQL to be emitted on the given
1425 :class:`_engine.Connection`. **Please read fully** the notes
1426 at :ref:`session_persistence_mapper` for guidelines on using
1427 these methods; generally, the :meth:`.SessionEvents.before_flush`
1428 method should be preferred for general on-flush changes.
1430 :param mapper: the :class:`_orm.Mapper` which is the target
1431 of this event.
1432 :param connection: the :class:`_engine.Connection` being used to
1433 emit DELETE statements for this instance. This
1434 provides a handle into the current transaction on the
1435 target database specific to this instance.
1436 :param target: the mapped instance being deleted. If
1437 the event is configured with ``raw=True``, this will
1438 instead be the :class:`.InstanceState` state-management
1439 object associated with the instance.
1440 :return: No return value is supported by this event.
1442 .. seealso::
1444 :ref:`session_persistence_events`
1446 """
1448 def after_delete(
1449 self, mapper: Mapper[_O], connection: Connection, target: _O
1450 ) -> None:
1451 """Receive an object instance after a DELETE statement
1452 has been emitted corresponding to that instance.
1454 .. note:: this event **only** applies to the
1455 :ref:`session flush operation <session_flushing>`
1456 and does **not** apply to the ORM DML operations described at
1457 :ref:`orm_expression_update_delete`. To intercept ORM
1458 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1460 This event is used to emit additional SQL statements on
1461 the given connection as well as to perform application
1462 specific bookkeeping related to a deletion event.
1464 The event is often called for a batch of objects of the
1465 same class after their DELETE statements have been emitted at
1466 once in a previous step.
1468 .. warning::
1470 Mapper-level flush events only allow **very limited operations**,
1471 on attributes local to the row being operated upon only,
1472 as well as allowing any SQL to be emitted on the given
1473 :class:`_engine.Connection`. **Please read fully** the notes
1474 at :ref:`session_persistence_mapper` for guidelines on using
1475 these methods; generally, the :meth:`.SessionEvents.before_flush`
1476 method should be preferred for general on-flush changes.
1478 :param mapper: the :class:`_orm.Mapper` which is the target
1479 of this event.
1480 :param connection: the :class:`_engine.Connection` being used to
1481 emit DELETE statements for this instance. This
1482 provides a handle into the current transaction on the
1483 target database specific to this instance.
1484 :param target: the mapped instance being deleted. If
1485 the event is configured with ``raw=True``, this will
1486 instead be the :class:`.InstanceState` state-management
1487 object associated with the instance.
1488 :return: No return value is supported by this event.
1490 .. seealso::
1492 :ref:`session_persistence_events`
1494 """
1497class _MapperEventsHold(_EventsHold[_ET]):
1498 all_holds = weakref.WeakKeyDictionary()
1500 def resolve(
1501 self, class_: Union[Type[_T], _InternalEntityType[_T]]
1502 ) -> Optional[Mapper[_T]]:
1503 return _mapper_or_none(class_)
1505 class HoldMapperEvents(_EventsHold.HoldEvents[_ET], MapperEvents): # type: ignore [misc] # noqa: E501
1506 pass
1508 dispatch = event.dispatcher(HoldMapperEvents)
1511_sessionevents_lifecycle_event_names: Set[str] = set()
1514class SessionEvents(event.Events[Session]):
1515 """Define events specific to :class:`.Session` lifecycle.
1517 e.g.::
1519 from sqlalchemy import event
1520 from sqlalchemy.orm import sessionmaker
1523 def my_before_commit(session):
1524 print("before commit!")
1527 Session = sessionmaker()
1529 event.listen(Session, "before_commit", my_before_commit)
1531 The :func:`~.event.listen` function will accept
1532 :class:`.Session` objects as well as the return result
1533 of :class:`~.sessionmaker()` and :class:`~.scoped_session()`.
1535 Additionally, it accepts the :class:`.Session` class which
1536 will apply listeners to all :class:`.Session` instances
1537 globally.
1539 :param raw=False: When True, the "target" argument passed
1540 to applicable event listener functions that work on individual
1541 objects will be the instance's :class:`.InstanceState` management
1542 object, rather than the mapped instance itself.
1544 :param restore_load_context=False: Applies to the
1545 :meth:`.SessionEvents.loaded_as_persistent` event. Restores the loader
1546 context of the object when the event hook is complete, so that ongoing
1547 eager load operations continue to target the object appropriately. A
1548 warning is emitted if the object is moved to a new loader context from
1549 within this event if this flag is not set.
1551 """
1553 _target_class_doc = "SomeSessionClassOrObject"
1555 _dispatch_target = Session
1557 def _lifecycle_event( # type: ignore [misc]
1558 fn: Callable[[SessionEvents, Session, Any], None],
1559 ) -> Callable[[SessionEvents, Session, Any], None]:
1560 _sessionevents_lifecycle_event_names.add(fn.__name__)
1561 return fn
1563 @classmethod
1564 def _accept_with( # type: ignore [return]
1565 cls, target: Any, identifier: str
1566 ) -> Union[Session, type]:
1567 if isinstance(target, scoped_session):
1568 target = target.session_factory
1569 if not isinstance(target, sessionmaker) and (
1570 not isinstance(target, type) or not issubclass(target, Session)
1571 ):
1572 raise exc.ArgumentError(
1573 "Session event listen on a scoped_session "
1574 "requires that its creation callable "
1575 "is associated with the Session class."
1576 )
1578 if isinstance(target, sessionmaker):
1579 return target.class_
1580 elif isinstance(target, type):
1581 if issubclass(target, scoped_session):
1582 return Session
1583 elif issubclass(target, Session):
1584 return target
1585 elif isinstance(target, Session):
1586 return target
1587 elif hasattr(target, "_no_async_engine_events"):
1588 target._no_async_engine_events()
1589 else:
1590 # allows alternate SessionEvents-like-classes to be consulted
1591 return event.Events._accept_with(target, identifier) # type: ignore [return-value] # noqa: E501
1593 @classmethod
1594 def _listen(
1595 cls,
1596 event_key: Any,
1597 *,
1598 raw: bool = False,
1599 restore_load_context: bool = False,
1600 **kw: Any,
1601 ) -> None:
1602 is_instance_event = (
1603 event_key.identifier in _sessionevents_lifecycle_event_names
1604 )
1606 if is_instance_event:
1607 if not raw or restore_load_context:
1608 fn = event_key._listen_fn
1610 def wrap(
1611 session: Session,
1612 state: InstanceState[_O],
1613 *arg: Any,
1614 **kw: Any,
1615 ) -> Optional[Any]:
1616 if not raw:
1617 target = state.obj()
1618 if target is None:
1619 # existing behavior is that if the object is
1620 # garbage collected, no event is emitted
1621 return None
1622 else:
1623 target = state # type: ignore [assignment]
1624 if restore_load_context:
1625 runid = state.runid
1626 try:
1627 return fn(session, target, *arg, **kw)
1628 finally:
1629 if restore_load_context:
1630 state.runid = runid
1632 event_key = event_key.with_wrapper(wrap)
1634 event_key.base_listen(**kw)
1636 def do_orm_execute(self, orm_execute_state: ORMExecuteState) -> None:
1637 """Intercept statement executions that occur on behalf of an
1638 ORM :class:`.Session` object.
1640 This event is invoked for all top-level SQL statements invoked from the
1641 :meth:`_orm.Session.execute` method, as well as related methods such as
1642 :meth:`_orm.Session.scalars` and :meth:`_orm.Session.scalar`. As of
1643 SQLAlchemy 1.4, all ORM queries that run through the
1644 :meth:`_orm.Session.execute` method as well as related methods
1645 :meth:`_orm.Session.scalars`, :meth:`_orm.Session.scalar` etc.
1646 will participate in this event.
1647 This event hook does **not** apply to the queries that are
1648 emitted internally within the ORM flush process, i.e. the
1649 process described at :ref:`session_flushing`.
1651 .. note:: The :meth:`_orm.SessionEvents.do_orm_execute` event hook
1652 is triggered **for ORM statement executions only**, meaning those
1653 invoked via the :meth:`_orm.Session.execute` and similar methods on
1654 the :class:`_orm.Session` object. It does **not** trigger for
1655 statements that are invoked by SQLAlchemy Core only, i.e. statements
1656 invoked directly using :meth:`_engine.Connection.execute` or
1657 otherwise originating from an :class:`_engine.Engine` object without
1658 any :class:`_orm.Session` involved. To intercept **all** SQL
1659 executions regardless of whether the Core or ORM APIs are in use,
1660 see the event hooks at :class:`.ConnectionEvents`, such as
1661 :meth:`.ConnectionEvents.before_execute` and
1662 :meth:`.ConnectionEvents.before_cursor_execute`.
1664 Also, this event hook does **not** apply to queries that are
1665 emitted internally within the ORM flush process,
1666 i.e. the process described at :ref:`session_flushing`; to
1667 intercept steps within the flush process, see the event
1668 hooks described at :ref:`session_persistence_events` as
1669 well as :ref:`session_persistence_mapper`.
1671 This event is a ``do_`` event, meaning it has the capability to replace
1672 the operation that the :meth:`_orm.Session.execute` method normally
1673 performs. The intended use for this includes sharding and
1674 result-caching schemes which may seek to invoke the same statement
1675 across multiple database connections, returning a result that is
1676 merged from each of them, or which don't invoke the statement at all,
1677 instead returning data from a cache.
1679 The hook intends to replace the use of the
1680 ``Query._execute_and_instances`` method that could be subclassed prior
1681 to SQLAlchemy 1.4.
1683 :param orm_execute_state: an instance of :class:`.ORMExecuteState`
1684 which contains all information about the current execution, as well
1685 as helper functions used to derive other commonly required
1686 information. See that object for details.
1688 .. seealso::
1690 :ref:`session_execute_events` - top level documentation on how
1691 to use :meth:`_orm.SessionEvents.do_orm_execute`
1693 :class:`.ORMExecuteState` - the object passed to the
1694 :meth:`_orm.SessionEvents.do_orm_execute` event which contains
1695 all information about the statement to be invoked. It also
1696 provides an interface to extend the current statement, options,
1697 and parameters as well as an option that allows programmatic
1698 invocation of the statement at any point.
1700 :ref:`examples_session_orm_events` - includes examples of using
1701 :meth:`_orm.SessionEvents.do_orm_execute`
1703 :ref:`examples_caching` - an example of how to integrate
1704 Dogpile caching with the ORM :class:`_orm.Session` making use
1705 of the :meth:`_orm.SessionEvents.do_orm_execute` event hook.
1707 :ref:`examples_sharding` - the Horizontal Sharding example /
1708 extension relies upon the
1709 :meth:`_orm.SessionEvents.do_orm_execute` event hook to invoke a
1710 SQL statement on multiple backends and return a merged result.
1713 .. versionadded:: 1.4
1715 """
1717 def after_transaction_create(
1718 self, session: Session, transaction: SessionTransaction
1719 ) -> None:
1720 """Execute when a new :class:`.SessionTransaction` is created.
1722 This event differs from :meth:`~.SessionEvents.after_begin`
1723 in that it occurs for each :class:`.SessionTransaction`
1724 overall, as opposed to when transactions are begun
1725 on individual database connections. It is also invoked
1726 for nested transactions and subtransactions, and is always
1727 matched by a corresponding
1728 :meth:`~.SessionEvents.after_transaction_end` event
1729 (assuming normal operation of the :class:`.Session`).
1731 :param session: the target :class:`.Session`.
1732 :param transaction: the target :class:`.SessionTransaction`.
1734 To detect if this is the outermost
1735 :class:`.SessionTransaction`, as opposed to a "subtransaction" or a
1736 SAVEPOINT, test that the :attr:`.SessionTransaction.parent` attribute
1737 is ``None``::
1739 @event.listens_for(session, "after_transaction_create")
1740 def after_transaction_create(session, transaction):
1741 if transaction.parent is None:
1742 ... # work with top-level transaction
1744 To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the
1745 :attr:`.SessionTransaction.nested` attribute::
1747 @event.listens_for(session, "after_transaction_create")
1748 def after_transaction_create(session, transaction):
1749 if transaction.nested:
1750 ... # work with SAVEPOINT transaction
1752 .. seealso::
1754 :class:`.SessionTransaction`
1756 :meth:`~.SessionEvents.after_transaction_end`
1758 """
1760 def after_transaction_end(
1761 self, session: Session, transaction: SessionTransaction
1762 ) -> None:
1763 """Execute when the span of a :class:`.SessionTransaction` ends.
1765 This event differs from :meth:`~.SessionEvents.after_commit`
1766 in that it corresponds to all :class:`.SessionTransaction`
1767 objects in use, including those for nested transactions
1768 and subtransactions, and is always matched by a corresponding
1769 :meth:`~.SessionEvents.after_transaction_create` event.
1771 :param session: the target :class:`.Session`.
1772 :param transaction: the target :class:`.SessionTransaction`.
1774 To detect if this is the outermost
1775 :class:`.SessionTransaction`, as opposed to a "subtransaction" or a
1776 SAVEPOINT, test that the :attr:`.SessionTransaction.parent` attribute
1777 is ``None``::
1779 @event.listens_for(session, "after_transaction_create")
1780 def after_transaction_end(session, transaction):
1781 if transaction.parent is None:
1782 ... # work with top-level transaction
1784 To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the
1785 :attr:`.SessionTransaction.nested` attribute::
1787 @event.listens_for(session, "after_transaction_create")
1788 def after_transaction_end(session, transaction):
1789 if transaction.nested:
1790 ... # work with SAVEPOINT transaction
1792 .. seealso::
1794 :class:`.SessionTransaction`
1796 :meth:`~.SessionEvents.after_transaction_create`
1798 """
1800 def before_commit(self, session: Session) -> None:
1801 """Execute before commit is called.
1803 .. note::
1805 The :meth:`~.SessionEvents.before_commit` hook is *not* per-flush,
1806 that is, the :class:`.Session` can emit SQL to the database
1807 many times within the scope of a transaction.
1808 For interception of these events, use the
1809 :meth:`~.SessionEvents.before_flush`,
1810 :meth:`~.SessionEvents.after_flush`, or
1811 :meth:`~.SessionEvents.after_flush_postexec`
1812 events.
1814 :param session: The target :class:`.Session`.
1816 .. seealso::
1818 :meth:`~.SessionEvents.after_commit`
1820 :meth:`~.SessionEvents.after_begin`
1822 :meth:`~.SessionEvents.after_transaction_create`
1824 :meth:`~.SessionEvents.after_transaction_end`
1826 """
1828 def after_commit(self, session: Session) -> None:
1829 """Execute after a commit has occurred.
1831 .. note::
1833 The :meth:`~.SessionEvents.after_commit` hook is *not* per-flush,
1834 that is, the :class:`.Session` can emit SQL to the database
1835 many times within the scope of a transaction.
1836 For interception of these events, use the
1837 :meth:`~.SessionEvents.before_flush`,
1838 :meth:`~.SessionEvents.after_flush`, or
1839 :meth:`~.SessionEvents.after_flush_postexec`
1840 events.
1842 .. note::
1844 The :class:`.Session` is not in an active transaction
1845 when the :meth:`~.SessionEvents.after_commit` event is invoked,
1846 and therefore can not emit SQL. To emit SQL corresponding to
1847 every transaction, use the :meth:`~.SessionEvents.before_commit`
1848 event.
1850 :param session: The target :class:`.Session`.
1852 .. seealso::
1854 :meth:`~.SessionEvents.before_commit`
1856 :meth:`~.SessionEvents.after_begin`
1858 :meth:`~.SessionEvents.after_transaction_create`
1860 :meth:`~.SessionEvents.after_transaction_end`
1862 """
1864 def after_rollback(self, session: Session) -> None:
1865 """Execute after a real DBAPI rollback has occurred.
1867 Note that this event only fires when the *actual* rollback against
1868 the database occurs - it does *not* fire each time the
1869 :meth:`.Session.rollback` method is called, if the underlying
1870 DBAPI transaction has already been rolled back. In many
1871 cases, the :class:`.Session` will not be in
1872 an "active" state during this event, as the current
1873 transaction is not valid. To acquire a :class:`.Session`
1874 which is active after the outermost rollback has proceeded,
1875 use the :meth:`.SessionEvents.after_soft_rollback` event, checking the
1876 :attr:`.Session.is_active` flag.
1878 :param session: The target :class:`.Session`.
1880 """
1882 def after_soft_rollback(
1883 self, session: Session, previous_transaction: SessionTransaction
1884 ) -> None:
1885 """Execute after any rollback has occurred, including "soft"
1886 rollbacks that don't actually emit at the DBAPI level.
1888 This corresponds to both nested and outer rollbacks, i.e.
1889 the innermost rollback that calls the DBAPI's
1890 rollback() method, as well as the enclosing rollback
1891 calls that only pop themselves from the transaction stack.
1893 The given :class:`.Session` can be used to invoke SQL and
1894 :meth:`.Session.query` operations after an outermost rollback
1895 by first checking the :attr:`.Session.is_active` flag::
1897 @event.listens_for(Session, "after_soft_rollback")
1898 def do_something(session, previous_transaction):
1899 if session.is_active:
1900 session.execute(text("select * from some_table"))
1902 :param session: The target :class:`.Session`.
1903 :param previous_transaction: The :class:`.SessionTransaction`
1904 transactional marker object which was just closed. The current
1905 :class:`.SessionTransaction` for the given :class:`.Session` is
1906 available via the :attr:`.Session.transaction` attribute.
1908 """
1910 def before_flush(
1911 self,
1912 session: Session,
1913 flush_context: UOWTransaction,
1914 instances: Optional[Sequence[_O]],
1915 ) -> None:
1916 """Execute before flush process has started.
1918 :param session: The target :class:`.Session`.
1919 :param flush_context: Internal :class:`.UOWTransaction` object
1920 which handles the details of the flush.
1921 :param instances: Usually ``None``, this is the collection of
1922 objects which can be passed to the :meth:`.Session.flush` method
1923 (note this usage is deprecated).
1925 .. seealso::
1927 :meth:`~.SessionEvents.after_flush`
1929 :meth:`~.SessionEvents.after_flush_postexec`
1931 :ref:`session_persistence_events`
1933 """
1935 def after_flush(
1936 self, session: Session, flush_context: UOWTransaction
1937 ) -> None:
1938 """Execute after flush has completed, but before commit has been
1939 called.
1941 Note that the session's state is still in pre-flush, i.e. 'new',
1942 'dirty', and 'deleted' lists still show pre-flush state as well
1943 as the history settings on instance attributes.
1945 .. warning:: This event runs after the :class:`.Session` has emitted
1946 SQL to modify the database, but **before** it has altered its
1947 internal state to reflect those changes, including that newly
1948 inserted objects are placed into the identity map. ORM operations
1949 emitted within this event such as loads of related items
1950 may produce new identity map entries that will immediately
1951 be replaced, sometimes causing confusing results. SQLAlchemy will
1952 emit a warning for this condition as of version 1.3.9.
1954 :param session: The target :class:`.Session`.
1955 :param flush_context: Internal :class:`.UOWTransaction` object
1956 which handles the details of the flush.
1958 .. seealso::
1960 :meth:`~.SessionEvents.before_flush`
1962 :meth:`~.SessionEvents.after_flush_postexec`
1964 :ref:`session_persistence_events`
1966 """
1968 def after_flush_postexec(
1969 self, session: Session, flush_context: UOWTransaction
1970 ) -> None:
1971 """Execute after flush has completed, and after the post-exec
1972 state occurs.
1974 This will be when the 'new', 'dirty', and 'deleted' lists are in
1975 their final state. An actual commit() may or may not have
1976 occurred, depending on whether or not the flush started its own
1977 transaction or participated in a larger transaction.
1979 :param session: The target :class:`.Session`.
1980 :param flush_context: Internal :class:`.UOWTransaction` object
1981 which handles the details of the flush.
1984 .. seealso::
1986 :meth:`~.SessionEvents.before_flush`
1988 :meth:`~.SessionEvents.after_flush`
1990 :ref:`session_persistence_events`
1992 """
1994 def after_begin(
1995 self,
1996 session: Session,
1997 transaction: SessionTransaction,
1998 connection: Connection,
1999 ) -> None:
2000 """Execute after a transaction is begun on a connection.
2002 .. note:: This event is called within the process of the
2003 :class:`_orm.Session` modifying its own internal state.
2004 To invoke SQL operations within this hook, use the
2005 :class:`_engine.Connection` provided to the event;
2006 do not run SQL operations using the :class:`_orm.Session`
2007 directly.
2009 :param session: The target :class:`.Session`.
2010 :param transaction: The :class:`.SessionTransaction`.
2011 :param connection: The :class:`_engine.Connection` object
2012 which will be used for SQL statements.
2014 .. seealso::
2016 :meth:`~.SessionEvents.before_commit`
2018 :meth:`~.SessionEvents.after_commit`
2020 :meth:`~.SessionEvents.after_transaction_create`
2022 :meth:`~.SessionEvents.after_transaction_end`
2024 """
2026 @_lifecycle_event
2027 def before_attach(self, session: Session, instance: _O) -> None:
2028 """Execute before an instance is attached to a session.
2030 This is called before an add, delete or merge causes
2031 the object to be part of the session.
2033 .. seealso::
2035 :meth:`~.SessionEvents.after_attach`
2037 :ref:`session_lifecycle_events`
2039 """
2041 @_lifecycle_event
2042 def after_attach(self, session: Session, instance: _O) -> None:
2043 """Execute after an instance is attached to a session.
2045 This is called after an add, delete or merge.
2047 .. note::
2049 As of 0.8, this event fires off *after* the item
2050 has been fully associated with the session, which is
2051 different than previous releases. For event
2052 handlers that require the object not yet
2053 be part of session state (such as handlers which
2054 may autoflush while the target object is not
2055 yet complete) consider the
2056 new :meth:`.before_attach` event.
2058 .. seealso::
2060 :meth:`~.SessionEvents.before_attach`
2062 :ref:`session_lifecycle_events`
2064 """
2066 def after_bulk_update(self, update_context: _O) -> None:
2067 """Event for after the legacy :meth:`_orm.Query.update` method
2068 has been called.
2070 .. legacy:: The :meth:`_orm.SessionEvents.after_bulk_update` method
2071 is a legacy event hook as of SQLAlchemy 2.0. The event
2072 **does not participate** in :term:`2.0 style` invocations
2073 using :func:`_dml.update` documented at
2074 :ref:`orm_queryguide_update_delete_where`. For 2.0 style use,
2075 the :meth:`_orm.SessionEvents.do_orm_execute` hook will intercept
2076 these calls.
2078 :param update_context: an "update context" object which contains
2079 details about the update, including these attributes:
2081 * ``session`` - the :class:`.Session` involved
2082 * ``query`` -the :class:`_query.Query`
2083 object that this update operation
2084 was called upon.
2085 * ``values`` The "values" dictionary that was passed to
2086 :meth:`_query.Query.update`.
2087 * ``result`` the :class:`_engine.CursorResult`
2088 returned as a result of the
2089 bulk UPDATE operation.
2091 .. versionchanged:: 1.4 the update_context no longer has a
2092 ``QueryContext`` object associated with it.
2094 .. seealso::
2096 :meth:`.QueryEvents.before_compile_update`
2098 :meth:`.SessionEvents.after_bulk_delete`
2100 """
2102 def after_bulk_delete(self, delete_context: _O) -> None:
2103 """Event for after the legacy :meth:`_orm.Query.delete` method
2104 has been called.
2106 .. legacy:: The :meth:`_orm.SessionEvents.after_bulk_delete` method
2107 is a legacy event hook as of SQLAlchemy 2.0. The event
2108 **does not participate** in :term:`2.0 style` invocations
2109 using :func:`_dml.delete` documented at
2110 :ref:`orm_queryguide_update_delete_where`. For 2.0 style use,
2111 the :meth:`_orm.SessionEvents.do_orm_execute` hook will intercept
2112 these calls.
2114 :param delete_context: a "delete context" object which contains
2115 details about the update, including these attributes:
2117 * ``session`` - the :class:`.Session` involved
2118 * ``query`` -the :class:`_query.Query`
2119 object that this update operation
2120 was called upon.
2121 * ``result`` the :class:`_engine.CursorResult`
2122 returned as a result of the
2123 bulk DELETE operation.
2125 .. versionchanged:: 1.4 the update_context no longer has a
2126 ``QueryContext`` object associated with it.
2128 .. seealso::
2130 :meth:`.QueryEvents.before_compile_delete`
2132 :meth:`.SessionEvents.after_bulk_update`
2134 """
2136 @_lifecycle_event
2137 def transient_to_pending(self, session: Session, instance: _O) -> None:
2138 """Intercept the "transient to pending" transition for a specific
2139 object.
2141 This event is a specialization of the
2142 :meth:`.SessionEvents.after_attach` event which is only invoked
2143 for this specific transition. It is invoked typically during the
2144 :meth:`.Session.add` call.
2146 :param session: target :class:`.Session`
2148 :param instance: the ORM-mapped instance being operated upon.
2150 .. seealso::
2152 :ref:`session_lifecycle_events`
2154 """
2156 @_lifecycle_event
2157 def pending_to_transient(self, session: Session, instance: _O) -> None:
2158 """Intercept the "pending to transient" transition for a specific
2159 object.
2161 This less common transition occurs when an pending object that has
2162 not been flushed is evicted from the session; this can occur
2163 when the :meth:`.Session.rollback` method rolls back the transaction,
2164 or when the :meth:`.Session.expunge` method is used.
2166 :param session: target :class:`.Session`
2168 :param instance: the ORM-mapped instance being operated upon.
2170 .. seealso::
2172 :ref:`session_lifecycle_events`
2174 """
2176 @_lifecycle_event
2177 def persistent_to_transient(self, session: Session, instance: _O) -> None:
2178 """Intercept the "persistent to transient" transition for a specific
2179 object.
2181 This less common transition occurs when an pending object that has
2182 has been flushed is evicted from the session; this can occur
2183 when the :meth:`.Session.rollback` method rolls back the transaction.
2185 :param session: target :class:`.Session`
2187 :param instance: the ORM-mapped instance being operated upon.
2189 .. seealso::
2191 :ref:`session_lifecycle_events`
2193 """
2195 @_lifecycle_event
2196 def pending_to_persistent(self, session: Session, instance: _O) -> None:
2197 """Intercept the "pending to persistent"" transition for a specific
2198 object.
2200 This event is invoked within the flush process, and is
2201 similar to scanning the :attr:`.Session.new` collection within
2202 the :meth:`.SessionEvents.after_flush` event. However, in this
2203 case the object has already been moved to the persistent state
2204 when the event is called.
2206 :param session: target :class:`.Session`
2208 :param instance: the ORM-mapped instance being operated upon.
2210 .. seealso::
2212 :ref:`session_lifecycle_events`
2214 """
2216 @_lifecycle_event
2217 def detached_to_persistent(self, session: Session, instance: _O) -> None:
2218 """Intercept the "detached to persistent" transition for a specific
2219 object.
2221 This event is a specialization of the
2222 :meth:`.SessionEvents.after_attach` event which is only invoked
2223 for this specific transition. It is invoked typically during the
2224 :meth:`.Session.add` call, as well as during the
2225 :meth:`.Session.delete` call if the object was not previously
2226 associated with the
2227 :class:`.Session` (note that an object marked as "deleted" remains
2228 in the "persistent" state until the flush proceeds).
2230 .. note::
2232 If the object becomes persistent as part of a call to
2233 :meth:`.Session.delete`, the object is **not** yet marked as
2234 deleted when this event is called. To detect deleted objects,
2235 check the ``deleted`` flag sent to the
2236 :meth:`.SessionEvents.persistent_to_detached` to event after the
2237 flush proceeds, or check the :attr:`.Session.deleted` collection
2238 within the :meth:`.SessionEvents.before_flush` event if deleted
2239 objects need to be intercepted before the flush.
2241 :param session: target :class:`.Session`
2243 :param instance: the ORM-mapped instance being operated upon.
2245 .. seealso::
2247 :ref:`session_lifecycle_events`
2249 """
2251 @_lifecycle_event
2252 def loaded_as_persistent(self, session: Session, instance: _O) -> None:
2253 """Intercept the "loaded as persistent" transition for a specific
2254 object.
2256 This event is invoked within the ORM loading process, and is invoked
2257 very similarly to the :meth:`.InstanceEvents.load` event. However,
2258 the event here is linkable to a :class:`.Session` class or instance,
2259 rather than to a mapper or class hierarchy, and integrates
2260 with the other session lifecycle events smoothly. The object
2261 is guaranteed to be present in the session's identity map when
2262 this event is called.
2264 .. note:: This event is invoked within the loader process before
2265 eager loaders may have been completed, and the object's state may
2266 not be complete. Additionally, invoking row-level refresh
2267 operations on the object will place the object into a new loader
2268 context, interfering with the existing load context. See the note
2269 on :meth:`.InstanceEvents.load` for background on making use of the
2270 :paramref:`.SessionEvents.restore_load_context` parameter, which
2271 works in the same manner as that of
2272 :paramref:`.InstanceEvents.restore_load_context`, in order to
2273 resolve this scenario.
2275 :param session: target :class:`.Session`
2277 :param instance: the ORM-mapped instance being operated upon.
2279 .. seealso::
2281 :ref:`session_lifecycle_events`
2283 """
2285 @_lifecycle_event
2286 def persistent_to_deleted(self, session: Session, instance: _O) -> None:
2287 """Intercept the "persistent to deleted" transition for a specific
2288 object.
2290 This event is invoked when a persistent object's identity
2291 is deleted from the database within a flush, however the object
2292 still remains associated with the :class:`.Session` until the
2293 transaction completes.
2295 If the transaction is rolled back, the object moves again
2296 to the persistent state, and the
2297 :meth:`.SessionEvents.deleted_to_persistent` event is called.
2298 If the transaction is committed, the object becomes detached,
2299 which will emit the :meth:`.SessionEvents.deleted_to_detached`
2300 event.
2302 Note that while the :meth:`.Session.delete` method is the primary
2303 public interface to mark an object as deleted, many objects
2304 get deleted due to cascade rules, which are not always determined
2305 until flush time. Therefore, there's no way to catch
2306 every object that will be deleted until the flush has proceeded.
2307 the :meth:`.SessionEvents.persistent_to_deleted` event is therefore
2308 invoked at the end of a flush.
2310 .. seealso::
2312 :ref:`session_lifecycle_events`
2314 """
2316 @_lifecycle_event
2317 def deleted_to_persistent(self, session: Session, instance: _O) -> None:
2318 """Intercept the "deleted to persistent" transition for a specific
2319 object.
2321 This transition occurs only when an object that's been deleted
2322 successfully in a flush is restored due to a call to
2323 :meth:`.Session.rollback`. The event is not called under
2324 any other circumstances.
2326 .. seealso::
2328 :ref:`session_lifecycle_events`
2330 """
2332 @_lifecycle_event
2333 def deleted_to_detached(self, session: Session, instance: _O) -> None:
2334 """Intercept the "deleted to detached" transition for a specific
2335 object.
2337 This event is invoked when a deleted object is evicted
2338 from the session. The typical case when this occurs is when
2339 the transaction for a :class:`.Session` in which the object
2340 was deleted is committed; the object moves from the deleted
2341 state to the detached state.
2343 It is also invoked for objects that were deleted in a flush
2344 when the :meth:`.Session.expunge_all` or :meth:`.Session.close`
2345 events are called, as well as if the object is individually
2346 expunged from its deleted state via :meth:`.Session.expunge`.
2348 .. seealso::
2350 :ref:`session_lifecycle_events`
2352 """
2354 @_lifecycle_event
2355 def persistent_to_detached(self, session: Session, instance: _O) -> None:
2356 """Intercept the "persistent to detached" transition for a specific
2357 object.
2359 This event is invoked when a persistent object is evicted
2360 from the session. There are many conditions that cause this
2361 to happen, including:
2363 * using a method such as :meth:`.Session.expunge`
2364 or :meth:`.Session.close`
2366 * Calling the :meth:`.Session.rollback` method, when the object
2367 was part of an INSERT statement for that session's transaction
2370 :param session: target :class:`.Session`
2372 :param instance: the ORM-mapped instance being operated upon.
2374 :param deleted: boolean. If True, indicates this object moved
2375 to the detached state because it was marked as deleted and flushed.
2378 .. seealso::
2380 :ref:`session_lifecycle_events`
2382 """
2385class AttributeEvents(event.Events[QueryableAttribute[Any]]):
2386 r"""Define events for object attributes.
2388 These are typically defined on the class-bound descriptor for the
2389 target class.
2391 For example, to register a listener that will receive the
2392 :meth:`_orm.AttributeEvents.append` event::
2394 from sqlalchemy import event
2397 @event.listens_for(MyClass.collection, "append", propagate=True)
2398 def my_append_listener(target, value, initiator):
2399 print("received append event for target: %s" % target)
2401 Listeners have the option to return a possibly modified version of the
2402 value, when the :paramref:`.AttributeEvents.retval` flag is passed to
2403 :func:`.event.listen` or :func:`.event.listens_for`, such as below,
2404 illustrated using the :meth:`_orm.AttributeEvents.set` event::
2406 def validate_phone(target, value, oldvalue, initiator):
2407 "Strip non-numeric characters from a phone number"
2409 return re.sub(r"\D", "", value)
2412 # setup listener on UserContact.phone attribute, instructing
2413 # it to use the return value
2414 listen(UserContact.phone, "set", validate_phone, retval=True)
2416 A validation function like the above can also raise an exception
2417 such as :exc:`ValueError` to halt the operation.
2419 The :paramref:`.AttributeEvents.propagate` flag is also important when
2420 applying listeners to mapped classes that also have mapped subclasses,
2421 as when using mapper inheritance patterns::
2424 @event.listens_for(MySuperClass.attr, "set", propagate=True)
2425 def receive_set(target, value, initiator):
2426 print("value set: %s" % target)
2428 The full list of modifiers available to the :func:`.event.listen`
2429 and :func:`.event.listens_for` functions are below.
2431 :param active_history=False: When True, indicates that the
2432 "set" event would like to receive the "old" value being
2433 replaced unconditionally, even if this requires firing off
2434 database loads. Note that ``active_history`` can also be
2435 set directly via :func:`.column_property` and
2436 :func:`_orm.relationship`.
2438 :param propagate=False: When True, the listener function will
2439 be established not just for the class attribute given, but
2440 for attributes of the same name on all current subclasses
2441 of that class, as well as all future subclasses of that
2442 class, using an additional listener that listens for
2443 instrumentation events.
2444 :param raw=False: When True, the "target" argument to the
2445 event will be the :class:`.InstanceState` management
2446 object, rather than the mapped instance itself.
2447 :param retval=False: when True, the user-defined event
2448 listening must return the "value" argument from the
2449 function. This gives the listening function the opportunity
2450 to change the value that is ultimately used for a "set"
2451 or "append" event.
2453 """
2455 _target_class_doc = "SomeClass.some_attribute"
2456 _dispatch_target = QueryableAttribute
2458 @staticmethod
2459 def _set_dispatch(
2460 cls: Type[_HasEventsDispatch[Any]], dispatch_cls: Type[_Dispatch[Any]]
2461 ) -> _Dispatch[Any]:
2462 dispatch = event.Events._set_dispatch(cls, dispatch_cls)
2463 dispatch_cls._active_history = False
2464 return dispatch
2466 @classmethod
2467 def _accept_with(
2468 cls,
2469 target: Union[QueryableAttribute[Any], Type[QueryableAttribute[Any]]],
2470 identifier: str,
2471 ) -> Union[QueryableAttribute[Any], Type[QueryableAttribute[Any]]]:
2472 # TODO: coverage
2473 if isinstance(target, interfaces.MapperProperty):
2474 return getattr(target.parent.class_, target.key)
2475 else:
2476 return target
2478 @classmethod
2479 def _listen( # type: ignore [override]
2480 cls,
2481 event_key: _EventKey[QueryableAttribute[Any]],
2482 active_history: bool = False,
2483 raw: bool = False,
2484 retval: bool = False,
2485 propagate: bool = False,
2486 include_key: bool = False,
2487 ) -> None:
2488 target, fn = event_key.dispatch_target, event_key._listen_fn
2490 if active_history:
2491 target.dispatch._active_history = True
2493 if not raw or not retval or not include_key:
2495 def wrap(target: InstanceState[_O], *arg: Any, **kw: Any) -> Any:
2496 if not raw:
2497 target = target.obj() # type: ignore [assignment]
2498 if not retval:
2499 if arg:
2500 value = arg[0]
2501 else:
2502 value = None
2503 if include_key:
2504 fn(target, *arg, **kw)
2505 else:
2506 fn(target, *arg)
2507 return value
2508 else:
2509 if include_key:
2510 return fn(target, *arg, **kw)
2511 else:
2512 return fn(target, *arg)
2514 event_key = event_key.with_wrapper(wrap)
2516 event_key.base_listen(propagate=propagate)
2518 if propagate:
2519 manager = instrumentation.manager_of_class(target.class_)
2521 for mgr in manager.subclass_managers(True): # type: ignore [no-untyped-call] # noqa: E501
2522 event_key.with_dispatch_target(mgr[target.key]).base_listen(
2523 propagate=True
2524 )
2525 if active_history:
2526 mgr[target.key].dispatch._active_history = True
2528 def append(
2529 self,
2530 target: _O,
2531 value: _T,
2532 initiator: Event,
2533 *,
2534 key: EventConstants = NO_KEY,
2535 ) -> Optional[_T]:
2536 """Receive a collection append event.
2538 The append event is invoked for each element as it is appended
2539 to the collection. This occurs for single-item appends as well
2540 as for a "bulk replace" operation.
2542 :param target: the object instance receiving the event.
2543 If the listener is registered with ``raw=True``, this will
2544 be the :class:`.InstanceState` object.
2545 :param value: the value being appended. If this listener
2546 is registered with ``retval=True``, the listener
2547 function must return this value, or a new value which
2548 replaces it.
2549 :param initiator: An instance of :class:`.attributes.Event`
2550 representing the initiation of the event. May be modified
2551 from its original value by backref handlers in order to control
2552 chained event propagation, as well as be inspected for information
2553 about the source of the event.
2554 :param key: When the event is established using the
2555 :paramref:`.AttributeEvents.include_key` parameter set to
2556 True, this will be the key used in the operation, such as
2557 ``collection[some_key_or_index] = value``.
2558 The parameter is not passed
2559 to the event at all if the the
2560 :paramref:`.AttributeEvents.include_key`
2561 was not used to set up the event; this is to allow backwards
2562 compatibility with existing event handlers that don't include the
2563 ``key`` parameter.
2565 .. versionadded:: 2.0
2567 :return: if the event was registered with ``retval=True``,
2568 the given value, or a new effective value, should be returned.
2570 .. seealso::
2572 :class:`.AttributeEvents` - background on listener options such
2573 as propagation to subclasses.
2575 :meth:`.AttributeEvents.bulk_replace`
2577 """
2579 def append_wo_mutation(
2580 self,
2581 target: _O,
2582 value: _T,
2583 initiator: Event,
2584 *,
2585 key: EventConstants = NO_KEY,
2586 ) -> None:
2587 """Receive a collection append event where the collection was not
2588 actually mutated.
2590 This event differs from :meth:`_orm.AttributeEvents.append` in that
2591 it is fired off for de-duplicating collections such as sets and
2592 dictionaries, when the object already exists in the target collection.
2593 The event does not have a return value and the identity of the
2594 given object cannot be changed.
2596 The event is used for cascading objects into a :class:`_orm.Session`
2597 when the collection has already been mutated via a backref event.
2599 :param target: the object instance receiving the event.
2600 If the listener is registered with ``raw=True``, this will
2601 be the :class:`.InstanceState` object.
2602 :param value: the value that would be appended if the object did not
2603 already exist in the collection.
2604 :param initiator: An instance of :class:`.attributes.Event`
2605 representing the initiation of the event. May be modified
2606 from its original value by backref handlers in order to control
2607 chained event propagation, as well as be inspected for information
2608 about the source of the event.
2609 :param key: When the event is established using the
2610 :paramref:`.AttributeEvents.include_key` parameter set to
2611 True, this will be the key used in the operation, such as
2612 ``collection[some_key_or_index] = value``.
2613 The parameter is not passed
2614 to the event at all if the the
2615 :paramref:`.AttributeEvents.include_key`
2616 was not used to set up the event; this is to allow backwards
2617 compatibility with existing event handlers that don't include the
2618 ``key`` parameter.
2620 .. versionadded:: 2.0
2622 :return: No return value is defined for this event.
2624 .. versionadded:: 1.4.15
2626 """
2628 def bulk_replace(
2629 self,
2630 target: _O,
2631 values: Iterable[_T],
2632 initiator: Event,
2633 *,
2634 keys: Optional[Iterable[EventConstants]] = None,
2635 ) -> None:
2636 """Receive a collection 'bulk replace' event.
2638 This event is invoked for a sequence of values as they are incoming
2639 to a bulk collection set operation, which can be
2640 modified in place before the values are treated as ORM objects.
2641 This is an "early hook" that runs before the bulk replace routine
2642 attempts to reconcile which objects are already present in the
2643 collection and which are being removed by the net replace operation.
2645 It is typical that this method be combined with use of the
2646 :meth:`.AttributeEvents.append` event. When using both of these
2647 events, note that a bulk replace operation will invoke
2648 the :meth:`.AttributeEvents.append` event for all new items,
2649 even after :meth:`.AttributeEvents.bulk_replace` has been invoked
2650 for the collection as a whole. In order to determine if an
2651 :meth:`.AttributeEvents.append` event is part of a bulk replace,
2652 use the symbol :attr:`~.attributes.OP_BULK_REPLACE` to test the
2653 incoming initiator::
2655 from sqlalchemy.orm.attributes import OP_BULK_REPLACE
2658 @event.listens_for(SomeObject.collection, "bulk_replace")
2659 def process_collection(target, values, initiator):
2660 values[:] = [_make_value(value) for value in values]
2663 @event.listens_for(SomeObject.collection, "append", retval=True)
2664 def process_collection(target, value, initiator):
2665 # make sure bulk_replace didn't already do it
2666 if initiator is None or initiator.op is not OP_BULK_REPLACE:
2667 return _make_value(value)
2668 else:
2669 return value
2671 :param target: the object instance receiving the event.
2672 If the listener is registered with ``raw=True``, this will
2673 be the :class:`.InstanceState` object.
2674 :param value: a sequence (e.g. a list) of the values being set. The
2675 handler can modify this list in place.
2676 :param initiator: An instance of :class:`.attributes.Event`
2677 representing the initiation of the event.
2678 :param keys: When the event is established using the
2679 :paramref:`.AttributeEvents.include_key` parameter set to
2680 True, this will be the sequence of keys used in the operation,
2681 typically only for a dictionary update. The parameter is not passed
2682 to the event at all if the the
2683 :paramref:`.AttributeEvents.include_key`
2684 was not used to set up the event; this is to allow backwards
2685 compatibility with existing event handlers that don't include the
2686 ``key`` parameter.
2688 .. versionadded:: 2.0
2690 .. seealso::
2692 :class:`.AttributeEvents` - background on listener options such
2693 as propagation to subclasses.
2696 """
2698 def remove(
2699 self,
2700 target: _O,
2701 value: _T,
2702 initiator: Event,
2703 *,
2704 key: EventConstants = NO_KEY,
2705 ) -> None:
2706 """Receive a collection remove event.
2708 :param target: the object instance receiving the event.
2709 If the listener is registered with ``raw=True``, this will
2710 be the :class:`.InstanceState` object.
2711 :param value: the value being removed.
2712 :param initiator: An instance of :class:`.attributes.Event`
2713 representing the initiation of the event. May be modified
2714 from its original value by backref handlers in order to control
2715 chained event propagation.
2717 :param key: When the event is established using the
2718 :paramref:`.AttributeEvents.include_key` parameter set to
2719 True, this will be the key used in the operation, such as
2720 ``del collection[some_key_or_index]``. The parameter is not passed
2721 to the event at all if the the
2722 :paramref:`.AttributeEvents.include_key`
2723 was not used to set up the event; this is to allow backwards
2724 compatibility with existing event handlers that don't include the
2725 ``key`` parameter.
2727 .. versionadded:: 2.0
2729 :return: No return value is defined for this event.
2732 .. seealso::
2734 :class:`.AttributeEvents` - background on listener options such
2735 as propagation to subclasses.
2737 """
2739 def set(
2740 self, target: _O, value: _T, oldvalue: _T, initiator: Event
2741 ) -> None:
2742 """Receive a scalar set event.
2744 :param target: the object instance receiving the event.
2745 If the listener is registered with ``raw=True``, this will
2746 be the :class:`.InstanceState` object.
2747 :param value: the value being set. If this listener
2748 is registered with ``retval=True``, the listener
2749 function must return this value, or a new value which
2750 replaces it.
2751 :param oldvalue: the previous value being replaced. This
2752 may also be the symbol ``NEVER_SET`` or ``NO_VALUE``.
2753 If the listener is registered with ``active_history=True``,
2754 the previous value of the attribute will be loaded from
2755 the database if the existing value is currently unloaded
2756 or expired.
2757 :param initiator: An instance of :class:`.attributes.Event`
2758 representing the initiation of the event. May be modified
2759 from its original value by backref handlers in order to control
2760 chained event propagation.
2762 :return: if the event was registered with ``retval=True``,
2763 the given value, or a new effective value, should be returned.
2765 .. seealso::
2767 :class:`.AttributeEvents` - background on listener options such
2768 as propagation to subclasses.
2770 """
2772 def init_scalar(
2773 self, target: _O, value: _T, dict_: Dict[Any, Any]
2774 ) -> None:
2775 r"""Receive a scalar "init" event.
2777 This event is invoked when an uninitialized, unpersisted scalar
2778 attribute is accessed, e.g. read::
2781 x = my_object.some_attribute
2783 The ORM's default behavior when this occurs for an un-initialized
2784 attribute is to return the value ``None``; note this differs from
2785 Python's usual behavior of raising ``AttributeError``. The
2786 event here can be used to customize what value is actually returned,
2787 with the assumption that the event listener would be mirroring
2788 a default generator that is configured on the Core
2789 :class:`_schema.Column`
2790 object as well.
2792 Since a default generator on a :class:`_schema.Column`
2793 might also produce
2794 a changing value such as a timestamp, the
2795 :meth:`.AttributeEvents.init_scalar`
2796 event handler can also be used to **set** the newly returned value, so
2797 that a Core-level default generation function effectively fires off
2798 only once, but at the moment the attribute is accessed on the
2799 non-persisted object. Normally, no change to the object's state
2800 is made when an uninitialized attribute is accessed (much older
2801 SQLAlchemy versions did in fact change the object's state).
2803 If a default generator on a column returned a particular constant,
2804 a handler might be used as follows::
2806 SOME_CONSTANT = 3.1415926
2809 class MyClass(Base):
2810 # ...
2812 some_attribute = Column(Numeric, default=SOME_CONSTANT)
2815 @event.listens_for(
2816 MyClass.some_attribute, "init_scalar", retval=True, propagate=True
2817 )
2818 def _init_some_attribute(target, dict_, value):
2819 dict_["some_attribute"] = SOME_CONSTANT
2820 return SOME_CONSTANT
2822 Above, we initialize the attribute ``MyClass.some_attribute`` to the
2823 value of ``SOME_CONSTANT``. The above code includes the following
2824 features:
2826 * By setting the value ``SOME_CONSTANT`` in the given ``dict_``,
2827 we indicate that this value is to be persisted to the database.
2828 This supersedes the use of ``SOME_CONSTANT`` in the default generator
2829 for the :class:`_schema.Column`. The ``active_column_defaults.py``
2830 example given at :ref:`examples_instrumentation` illustrates using
2831 the same approach for a changing default, e.g. a timestamp
2832 generator. In this particular example, it is not strictly
2833 necessary to do this since ``SOME_CONSTANT`` would be part of the
2834 INSERT statement in either case.
2836 * By establishing the ``retval=True`` flag, the value we return
2837 from the function will be returned by the attribute getter.
2838 Without this flag, the event is assumed to be a passive observer
2839 and the return value of our function is ignored.
2841 * The ``propagate=True`` flag is significant if the mapped class
2842 includes inheriting subclasses, which would also make use of this
2843 event listener. Without this flag, an inheriting subclass will
2844 not use our event handler.
2846 In the above example, the attribute set event
2847 :meth:`.AttributeEvents.set` as well as the related validation feature
2848 provided by :obj:`_orm.validates` is **not** invoked when we apply our
2849 value to the given ``dict_``. To have these events to invoke in
2850 response to our newly generated value, apply the value to the given
2851 object as a normal attribute set operation::
2853 SOME_CONSTANT = 3.1415926
2856 @event.listens_for(
2857 MyClass.some_attribute, "init_scalar", retval=True, propagate=True
2858 )
2859 def _init_some_attribute(target, dict_, value):
2860 # will also fire off attribute set events
2861 target.some_attribute = SOME_CONSTANT
2862 return SOME_CONSTANT
2864 When multiple listeners are set up, the generation of the value
2865 is "chained" from one listener to the next by passing the value
2866 returned by the previous listener that specifies ``retval=True``
2867 as the ``value`` argument of the next listener.
2869 :param target: the object instance receiving the event.
2870 If the listener is registered with ``raw=True``, this will
2871 be the :class:`.InstanceState` object.
2872 :param value: the value that is to be returned before this event
2873 listener were invoked. This value begins as the value ``None``,
2874 however will be the return value of the previous event handler
2875 function if multiple listeners are present.
2876 :param dict\_: the attribute dictionary of this mapped object.
2877 This is normally the ``__dict__`` of the object, but in all cases
2878 represents the destination that the attribute system uses to get
2879 at the actual value of this attribute. Placing the value in this
2880 dictionary has the effect that the value will be used in the
2881 INSERT statement generated by the unit of work.
2884 .. seealso::
2886 :meth:`.AttributeEvents.init_collection` - collection version
2887 of this event
2889 :class:`.AttributeEvents` - background on listener options such
2890 as propagation to subclasses.
2892 :ref:`examples_instrumentation` - see the
2893 ``active_column_defaults.py`` example.
2895 """ # noqa: E501
2897 def init_collection(
2898 self,
2899 target: _O,
2900 collection: Type[Collection[Any]],
2901 collection_adapter: CollectionAdapter,
2902 ) -> None:
2903 """Receive a 'collection init' event.
2905 This event is triggered for a collection-based attribute, when
2906 the initial "empty collection" is first generated for a blank
2907 attribute, as well as for when the collection is replaced with
2908 a new one, such as via a set event.
2910 E.g., given that ``User.addresses`` is a relationship-based
2911 collection, the event is triggered here::
2913 u1 = User()
2914 u1.addresses.append(a1) # <- new collection
2916 and also during replace operations::
2918 u1.addresses = [a2, a3] # <- new collection
2920 :param target: the object instance receiving the event.
2921 If the listener is registered with ``raw=True``, this will
2922 be the :class:`.InstanceState` object.
2923 :param collection: the new collection. This will always be generated
2924 from what was specified as
2925 :paramref:`_orm.relationship.collection_class`, and will always
2926 be empty.
2927 :param collection_adapter: the :class:`.CollectionAdapter` that will
2928 mediate internal access to the collection.
2930 .. seealso::
2932 :class:`.AttributeEvents` - background on listener options such
2933 as propagation to subclasses.
2935 :meth:`.AttributeEvents.init_scalar` - "scalar" version of this
2936 event.
2938 """
2940 def dispose_collection(
2941 self,
2942 target: _O,
2943 collection: Collection[Any],
2944 collection_adapter: CollectionAdapter,
2945 ) -> None:
2946 """Receive a 'collection dispose' event.
2948 This event is triggered for a collection-based attribute when
2949 a collection is replaced, that is::
2951 u1.addresses.append(a1)
2953 u1.addresses = [a2, a3] # <- old collection is disposed
2955 The old collection received will contain its previous contents.
2957 .. seealso::
2959 :class:`.AttributeEvents` - background on listener options such
2960 as propagation to subclasses.
2962 """
2964 def modified(self, target: _O, initiator: Event) -> None:
2965 """Receive a 'modified' event.
2967 This event is triggered when the :func:`.attributes.flag_modified`
2968 function is used to trigger a modify event on an attribute without
2969 any specific value being set.
2971 :param target: the object instance receiving the event.
2972 If the listener is registered with ``raw=True``, this will
2973 be the :class:`.InstanceState` object.
2975 :param initiator: An instance of :class:`.attributes.Event`
2976 representing the initiation of the event.
2978 .. seealso::
2980 :class:`.AttributeEvents` - background on listener options such
2981 as propagation to subclasses.
2983 """
2986class QueryEvents(event.Events[Query[Any]]):
2987 """Represent events within the construction of a :class:`_query.Query`
2988 object.
2990 .. legacy:: The :class:`_orm.QueryEvents` event methods are legacy
2991 as of SQLAlchemy 2.0, and only apply to direct use of the
2992 :class:`_orm.Query` object. They are not used for :term:`2.0 style`
2993 statements. For events to intercept and modify 2.0 style ORM use,
2994 use the :meth:`_orm.SessionEvents.do_orm_execute` hook.
2997 The :class:`_orm.QueryEvents` hooks are now superseded by the
2998 :meth:`_orm.SessionEvents.do_orm_execute` event hook.
3000 """
3002 _target_class_doc = "SomeQuery"
3003 _dispatch_target = Query
3005 def before_compile(self, query: Query[Any]) -> None:
3006 """Receive the :class:`_query.Query`
3007 object before it is composed into a
3008 core :class:`_expression.Select` object.
3010 .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile` event
3011 is superseded by the much more capable
3012 :meth:`_orm.SessionEvents.do_orm_execute` hook. In version 1.4,
3013 the :meth:`_orm.QueryEvents.before_compile` event is **no longer
3014 used** for ORM-level attribute loads, such as loads of deferred
3015 or expired attributes as well as relationship loaders. See the
3016 new examples in :ref:`examples_session_orm_events` which
3017 illustrate new ways of intercepting and modifying ORM queries
3018 for the most common purpose of adding arbitrary filter criteria.
3021 This event is intended to allow changes to the query given::
3023 @event.listens_for(Query, "before_compile", retval=True)
3024 def no_deleted(query):
3025 for desc in query.column_descriptions:
3026 if desc["type"] is User:
3027 entity = desc["entity"]
3028 query = query.filter(entity.deleted == False)
3029 return query
3031 The event should normally be listened with the ``retval=True``
3032 parameter set, so that the modified query may be returned.
3034 The :meth:`.QueryEvents.before_compile` event by default
3035 will disallow "baked" queries from caching a query, if the event
3036 hook returns a new :class:`_query.Query` object.
3037 This affects both direct
3038 use of the baked query extension as well as its operation within
3039 lazy loaders and eager loaders for relationships. In order to
3040 re-establish the query being cached, apply the event adding the
3041 ``bake_ok`` flag::
3043 @event.listens_for(Query, "before_compile", retval=True, bake_ok=True)
3044 def my_event(query):
3045 for desc in query.column_descriptions:
3046 if desc["type"] is User:
3047 entity = desc["entity"]
3048 query = query.filter(entity.deleted == False)
3049 return query
3051 When ``bake_ok`` is set to True, the event hook will only be invoked
3052 once, and not called for subsequent invocations of a particular query
3053 that is being cached.
3055 .. seealso::
3057 :meth:`.QueryEvents.before_compile_update`
3059 :meth:`.QueryEvents.before_compile_delete`
3061 :ref:`baked_with_before_compile`
3063 """ # noqa: E501
3065 def before_compile_update(
3066 self, query: Query[Any], update_context: BulkUpdate
3067 ) -> None:
3068 """Allow modifications to the :class:`_query.Query` object within
3069 :meth:`_query.Query.update`.
3071 .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_update`
3072 event is superseded by the much more capable
3073 :meth:`_orm.SessionEvents.do_orm_execute` hook.
3075 Like the :meth:`.QueryEvents.before_compile` event, if the event
3076 is to be used to alter the :class:`_query.Query` object, it should
3077 be configured with ``retval=True``, and the modified
3078 :class:`_query.Query` object returned, as in ::
3080 @event.listens_for(Query, "before_compile_update", retval=True)
3081 def no_deleted(query, update_context):
3082 for desc in query.column_descriptions:
3083 if desc["type"] is User:
3084 entity = desc["entity"]
3085 query = query.filter(entity.deleted == False)
3087 update_context.values["timestamp"] = datetime.datetime.now(
3088 datetime.UTC
3089 )
3090 return query
3092 The ``.values`` dictionary of the "update context" object can also
3093 be modified in place as illustrated above.
3095 :param query: a :class:`_query.Query` instance; this is also
3096 the ``.query`` attribute of the given "update context"
3097 object.
3099 :param update_context: an "update context" object which is
3100 the same kind of object as described in
3101 :paramref:`.QueryEvents.after_bulk_update.update_context`.
3102 The object has a ``.values`` attribute in an UPDATE context which is
3103 the dictionary of parameters passed to :meth:`_query.Query.update`.
3104 This
3105 dictionary can be modified to alter the VALUES clause of the
3106 resulting UPDATE statement.
3108 .. seealso::
3110 :meth:`.QueryEvents.before_compile`
3112 :meth:`.QueryEvents.before_compile_delete`
3115 """ # noqa: E501
3117 def before_compile_delete(
3118 self, query: Query[Any], delete_context: BulkDelete
3119 ) -> None:
3120 """Allow modifications to the :class:`_query.Query` object within
3121 :meth:`_query.Query.delete`.
3123 .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_delete`
3124 event is superseded by the much more capable
3125 :meth:`_orm.SessionEvents.do_orm_execute` hook.
3127 Like the :meth:`.QueryEvents.before_compile` event, this event
3128 should be configured with ``retval=True``, and the modified
3129 :class:`_query.Query` object returned, as in ::
3131 @event.listens_for(Query, "before_compile_delete", retval=True)
3132 def no_deleted(query, delete_context):
3133 for desc in query.column_descriptions:
3134 if desc["type"] is User:
3135 entity = desc["entity"]
3136 query = query.filter(entity.deleted == False)
3137 return query
3139 :param query: a :class:`_query.Query` instance; this is also
3140 the ``.query`` attribute of the given "delete context"
3141 object.
3143 :param delete_context: a "delete context" object which is
3144 the same kind of object as described in
3145 :paramref:`.QueryEvents.after_bulk_delete.delete_context`.
3147 .. seealso::
3149 :meth:`.QueryEvents.before_compile`
3151 :meth:`.QueryEvents.before_compile_update`
3154 """
3156 @classmethod
3157 def _listen(
3158 cls,
3159 event_key: _EventKey[_ET],
3160 retval: bool = False,
3161 bake_ok: bool = False,
3162 **kw: Any,
3163 ) -> None:
3164 fn = event_key._listen_fn
3166 if not retval:
3168 def wrap(*arg: Any, **kw: Any) -> Any:
3169 if not retval:
3170 query = arg[0]
3171 fn(*arg, **kw)
3172 return query
3173 else:
3174 return fn(*arg, **kw)
3176 event_key = event_key.with_wrapper(wrap)
3177 else:
3178 # don't assume we can apply an attribute to the callable
3179 def wrap(*arg: Any, **kw: Any) -> Any:
3180 return fn(*arg, **kw)
3182 event_key = event_key.with_wrapper(wrap)
3184 wrap._bake_ok = bake_ok # type: ignore [attr-defined]
3186 event_key.base_listen(**kw)