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 .. versionadded:: 1.3.14
249 """
251 _target_class_doc = "SomeClass"
253 _dispatch_target = ClassManager
255 @classmethod
256 def _new_classmanager_instance(
257 cls,
258 class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type],
259 classmanager: ClassManager[_O],
260 ) -> None:
261 _InstanceEventsHold.populate(class_, classmanager)
263 @classmethod
264 @util.preload_module("sqlalchemy.orm")
265 def _accept_with(
266 cls,
267 target: Union[
268 ClassManager[Any],
269 Type[ClassManager[Any]],
270 ],
271 identifier: str,
272 ) -> Optional[Union[ClassManager[Any], Type[ClassManager[Any]]]]:
273 orm = util.preloaded.orm
275 if isinstance(target, ClassManager):
276 return target
277 elif isinstance(target, mapperlib.Mapper):
278 return target.class_manager
279 elif target is orm.mapper: # type: ignore [attr-defined]
280 util.warn_deprecated(
281 "The `sqlalchemy.orm.mapper()` symbol is deprecated and "
282 "will be removed in a future release. For the mapper-wide "
283 "event target, use the 'sqlalchemy.orm.Mapper' class.",
284 "2.0",
285 )
286 return ClassManager
287 elif isinstance(target, type):
288 if issubclass(target, mapperlib.Mapper):
289 return ClassManager
290 else:
291 manager = instrumentation.opt_manager_of_class(target)
292 if manager:
293 return manager
294 else:
295 return _InstanceEventsHold(target) # type: ignore [return-value] # noqa: E501
296 return None
298 @classmethod
299 def _listen(
300 cls,
301 event_key: _EventKey[ClassManager[Any]],
302 raw: bool = False,
303 propagate: bool = False,
304 restore_load_context: bool = False,
305 **kw: Any,
306 ) -> None:
307 target, fn = (event_key.dispatch_target, event_key._listen_fn)
309 if not raw or restore_load_context:
311 def wrap(
312 state: InstanceState[_O], *arg: Any, **kw: Any
313 ) -> Optional[Any]:
314 if not raw:
315 target: Any = state.obj()
316 else:
317 target = state
318 if restore_load_context:
319 runid = state.runid
320 try:
321 return fn(target, *arg, **kw)
322 finally:
323 if restore_load_context:
324 state.runid = runid
326 event_key = event_key.with_wrapper(wrap)
328 event_key.base_listen(propagate=propagate, **kw)
330 if propagate:
331 for mgr in target.subclass_managers(True):
332 event_key.with_dispatch_target(mgr).base_listen(propagate=True)
334 @classmethod
335 def _clear(cls) -> None:
336 super()._clear()
337 _InstanceEventsHold._clear()
339 def first_init(self, manager: ClassManager[_O], cls: Type[_O]) -> None:
340 """Called when the first instance of a particular mapping is called.
342 This event is called when the ``__init__`` method of a class
343 is called the first time for that particular class. The event
344 invokes before ``__init__`` actually proceeds as well as before
345 the :meth:`.InstanceEvents.init` event is invoked.
347 """
349 def init(self, target: _O, args: Any, kwargs: Any) -> None:
350 """Receive an instance when its constructor is called.
352 This method is only called during a userland construction of
353 an object, in conjunction with the object's constructor, e.g.
354 its ``__init__`` method. It is not called when an object is
355 loaded from the database; see the :meth:`.InstanceEvents.load`
356 event in order to intercept a database load.
358 The event is called before the actual ``__init__`` constructor
359 of the object is called. The ``kwargs`` dictionary may be
360 modified in-place in order to affect what is passed to
361 ``__init__``.
363 :param target: the mapped instance. If
364 the event is configured with ``raw=True``, this will
365 instead be the :class:`.InstanceState` state-management
366 object associated with the instance.
367 :param args: positional arguments passed to the ``__init__`` method.
368 This is passed as a tuple and is currently immutable.
369 :param kwargs: keyword arguments passed to the ``__init__`` method.
370 This structure *can* be altered in place.
372 .. seealso::
374 :meth:`.InstanceEvents.init_failure`
376 :meth:`.InstanceEvents.load`
378 """
380 def init_failure(self, target: _O, args: Any, kwargs: Any) -> None:
381 """Receive an instance when its constructor has been called,
382 and raised an exception.
384 This method is only called during a userland construction of
385 an object, in conjunction with the object's constructor, e.g.
386 its ``__init__`` method. It is not called when an object is loaded
387 from the database.
389 The event is invoked after an exception raised by the ``__init__``
390 method is caught. After the event
391 is invoked, the original exception is re-raised outwards, so that
392 the construction of the object still raises an exception. The
393 actual exception and stack trace raised should be present in
394 ``sys.exc_info()``.
396 :param target: the mapped instance. If
397 the event is configured with ``raw=True``, this will
398 instead be the :class:`.InstanceState` state-management
399 object associated with the instance.
400 :param args: positional arguments that were passed to the ``__init__``
401 method.
402 :param kwargs: keyword arguments that were passed to the ``__init__``
403 method.
405 .. seealso::
407 :meth:`.InstanceEvents.init`
409 :meth:`.InstanceEvents.load`
411 """
413 def _sa_event_merge_wo_load(
414 self, target: _O, context: QueryContext
415 ) -> None:
416 """receive an object instance after it was the subject of a merge()
417 call, when load=False was passed.
419 The target would be the already-loaded object in the Session which
420 would have had its attributes overwritten by the incoming object. This
421 overwrite operation does not use attribute events, instead just
422 populating dict directly. Therefore the purpose of this event is so
423 that extensions like sqlalchemy.ext.mutable know that object state has
424 changed and incoming state needs to be set up for "parents" etc.
426 This functionality is acceptable to be made public in a later release.
428 .. versionadded:: 1.4.41
430 """
432 def load(self, target: _O, context: QueryContext) -> None:
433 """Receive an object instance after it has been created via
434 ``__new__``, and after initial attribute population has
435 occurred.
437 This typically occurs when the instance is created based on
438 incoming result rows, and is only called once for that
439 instance's lifetime.
441 .. warning::
443 During a result-row load, this event is invoked when the
444 first row received for this instance is processed. When using
445 eager loading with collection-oriented attributes, the additional
446 rows that are to be loaded / processed in order to load subsequent
447 collection items have not occurred yet. This has the effect
448 both that collections will not be fully loaded, as well as that
449 if an operation occurs within this event handler that emits
450 another database load operation for the object, the "loading
451 context" for the object can change and interfere with the
452 existing eager loaders still in progress.
454 Examples of what can cause the "loading context" to change within
455 the event handler include, but are not necessarily limited to:
457 * accessing deferred attributes that weren't part of the row,
458 will trigger an "undefer" operation and refresh the object
460 * accessing attributes on a joined-inheritance subclass that
461 weren't part of the row, will trigger a refresh operation.
463 As of SQLAlchemy 1.3.14, a warning is emitted when this occurs. The
464 :paramref:`.InstanceEvents.restore_load_context` option may be
465 used on the event to prevent this warning; this will ensure that
466 the existing loading context is maintained for the object after the
467 event is called::
469 @event.listens_for(SomeClass, "load", restore_load_context=True)
470 def on_load(instance, context):
471 instance.some_unloaded_attribute
473 .. versionchanged:: 1.3.14 Added
474 :paramref:`.InstanceEvents.restore_load_context`
475 and :paramref:`.SessionEvents.restore_load_context` flags which
476 apply to "on load" events, which will ensure that the loading
477 context for an object is restored when the event hook is
478 complete; a warning is emitted if the load context of the object
479 changes without this flag being set.
482 The :meth:`.InstanceEvents.load` event is also available in a
483 class-method decorator format called :func:`_orm.reconstructor`.
485 :param target: the mapped instance. If
486 the event is configured with ``raw=True``, this will
487 instead be the :class:`.InstanceState` state-management
488 object associated with the instance.
489 :param context: the :class:`.QueryContext` corresponding to the
490 current :class:`_query.Query` in progress. This argument may be
491 ``None`` if the load does not correspond to a :class:`_query.Query`,
492 such as during :meth:`.Session.merge`.
494 .. seealso::
496 :ref:`mapped_class_load_events`
498 :meth:`.InstanceEvents.init`
500 :meth:`.InstanceEvents.refresh`
502 :meth:`.SessionEvents.loaded_as_persistent`
504 """ # noqa: E501
506 def refresh(
507 self, target: _O, context: QueryContext, attrs: Optional[Iterable[str]]
508 ) -> None:
509 """Receive an object instance after one or more attributes have
510 been refreshed from a query.
512 Contrast this to the :meth:`.InstanceEvents.load` method, which
513 is invoked when the object is first loaded from a query.
515 .. note:: This event is invoked within the loader process before
516 eager loaders may have been completed, and the object's state may
517 not be complete. Additionally, invoking row-level refresh
518 operations on the object will place the object into a new loader
519 context, interfering with the existing load context. See the note
520 on :meth:`.InstanceEvents.load` for background on making use of the
521 :paramref:`.InstanceEvents.restore_load_context` parameter, in
522 order to resolve this scenario.
524 :param target: the mapped instance. If
525 the event is configured with ``raw=True``, this will
526 instead be the :class:`.InstanceState` state-management
527 object associated with the instance.
528 :param context: the :class:`.QueryContext` corresponding to the
529 current :class:`_query.Query` in progress.
530 :param attrs: sequence of attribute names which
531 were populated, or None if all column-mapped, non-deferred
532 attributes were populated.
534 .. seealso::
536 :ref:`mapped_class_load_events`
538 :meth:`.InstanceEvents.load`
540 """
542 def refresh_flush(
543 self,
544 target: _O,
545 flush_context: UOWTransaction,
546 attrs: Optional[Iterable[str]],
547 ) -> None:
548 """Receive an object instance after one or more attributes that
549 contain a column-level default or onupdate handler have been refreshed
550 during persistence of the object's state.
552 This event is the same as :meth:`.InstanceEvents.refresh` except
553 it is invoked within the unit of work flush process, and includes
554 only non-primary-key columns that have column level default or
555 onupdate handlers, including Python callables as well as server side
556 defaults and triggers which may be fetched via the RETURNING clause.
558 .. note::
560 While the :meth:`.InstanceEvents.refresh_flush` event is triggered
561 for an object that was INSERTed as well as for an object that was
562 UPDATEd, the event is geared primarily towards the UPDATE process;
563 it is mostly an internal artifact that INSERT actions can also
564 trigger this event, and note that **primary key columns for an
565 INSERTed row are explicitly omitted** from this event. In order to
566 intercept the newly INSERTed state of an object, the
567 :meth:`.SessionEvents.pending_to_persistent` and
568 :meth:`.MapperEvents.after_insert` are better choices.
570 :param target: the mapped instance. If
571 the event is configured with ``raw=True``, this will
572 instead be the :class:`.InstanceState` state-management
573 object associated with the instance.
574 :param flush_context: Internal :class:`.UOWTransaction` object
575 which handles the details of the flush.
576 :param attrs: sequence of attribute names which
577 were populated.
579 .. seealso::
581 :ref:`mapped_class_load_events`
583 :ref:`orm_server_defaults`
585 :ref:`metadata_defaults_toplevel`
587 """
589 def expire(self, target: _O, attrs: Optional[Iterable[str]]) -> None:
590 """Receive an object instance after its attributes or some subset
591 have been expired.
593 'keys' is a list of attribute names. If None, the entire
594 state was expired.
596 :param target: the mapped instance. If
597 the event is configured with ``raw=True``, this will
598 instead be the :class:`.InstanceState` state-management
599 object associated with the instance.
600 :param attrs: sequence of attribute
601 names which were expired, or None if all attributes were
602 expired.
604 """
606 def pickle(self, target: _O, state_dict: _InstanceDict) -> None:
607 """Receive an object instance when its associated state is
608 being pickled.
610 :param target: the mapped instance. If
611 the event is configured with ``raw=True``, this will
612 instead be the :class:`.InstanceState` state-management
613 object associated with the instance.
614 :param state_dict: the dictionary returned by
615 :class:`.InstanceState.__getstate__`, containing the state
616 to be pickled.
618 """
620 def unpickle(self, target: _O, state_dict: _InstanceDict) -> None:
621 """Receive an object instance after its associated state has
622 been unpickled.
624 :param target: the mapped instance. If
625 the event is configured with ``raw=True``, this will
626 instead be the :class:`.InstanceState` state-management
627 object associated with the instance.
628 :param state_dict: the dictionary sent to
629 :class:`.InstanceState.__setstate__`, containing the state
630 dictionary which was pickled.
632 """
635class _EventsHold(event.RefCollection[_ET]):
636 """Hold onto listeners against unmapped, uninstrumented classes.
638 Establish _listen() for that class' mapper/instrumentation when
639 those objects are created for that class.
641 """
643 all_holds: weakref.WeakKeyDictionary[Any, Any]
645 def __init__(
646 self,
647 class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type],
648 ) -> None:
649 self.class_ = class_
651 @classmethod
652 def _clear(cls) -> None:
653 cls.all_holds.clear()
655 class HoldEvents(Generic[_ET2]):
656 _dispatch_target: Optional[Type[_ET2]] = None
658 @classmethod
659 def _listen(
660 cls,
661 event_key: _EventKey[_ET2],
662 raw: bool = False,
663 propagate: bool = False,
664 retval: bool = False,
665 **kw: Any,
666 ) -> None:
667 target = event_key.dispatch_target
669 if target.class_ in target.all_holds:
670 collection = target.all_holds[target.class_]
671 else:
672 collection = target.all_holds[target.class_] = {}
674 event.registry._stored_in_collection(event_key, target)
675 collection[event_key._key] = (
676 event_key,
677 raw,
678 propagate,
679 retval,
680 kw,
681 )
683 if propagate:
684 stack = list(target.class_.__subclasses__())
685 while stack:
686 subclass = stack.pop(0)
687 stack.extend(subclass.__subclasses__())
688 subject = target.resolve(subclass)
689 if subject is not None:
690 # we are already going through __subclasses__()
691 # so leave generic propagate flag False
692 event_key.with_dispatch_target(subject).listen(
693 raw=raw, propagate=False, retval=retval, **kw
694 )
696 def remove(self, event_key: _EventKey[_ET]) -> None:
697 target = event_key.dispatch_target
699 if isinstance(target, _EventsHold):
700 collection = target.all_holds[target.class_]
701 del collection[event_key._key]
703 @classmethod
704 def populate(
705 cls,
706 class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type],
707 subject: Union[ClassManager[_O], Mapper[_O]],
708 ) -> None:
709 for subclass in class_.__mro__:
710 if subclass in cls.all_holds:
711 collection = cls.all_holds[subclass]
712 for (
713 event_key,
714 raw,
715 propagate,
716 retval,
717 kw,
718 ) in collection.values():
719 if propagate or subclass is class_:
720 # since we can't be sure in what order different
721 # classes in a hierarchy are triggered with
722 # populate(), we rely upon _EventsHold for all event
723 # assignment, instead of using the generic propagate
724 # flag.
725 event_key.with_dispatch_target(subject).listen(
726 raw=raw, propagate=False, retval=retval, **kw
727 )
730class _InstanceEventsHold(_EventsHold[_ET]):
731 all_holds: weakref.WeakKeyDictionary[Any, Any] = (
732 weakref.WeakKeyDictionary()
733 )
735 def resolve(self, class_: Type[_O]) -> Optional[ClassManager[_O]]:
736 return instrumentation.opt_manager_of_class(class_)
738 # this fails on pyright if you use Any. Fails on mypy if you use _ET
739 class HoldInstanceEvents(_EventsHold.HoldEvents[_ET], InstanceEvents): # type: ignore[valid-type,misc] # noqa: E501
740 pass
742 dispatch = event.dispatcher(HoldInstanceEvents)
745class MapperEvents(event.Events[mapperlib.Mapper[Any]]):
746 """Define events specific to mappings.
748 e.g.::
750 from sqlalchemy import event
753 def my_before_insert_listener(mapper, connection, target):
754 # execute a stored procedure upon INSERT,
755 # apply the value to the row to be inserted
756 target.calculated_value = connection.execute(
757 text("select my_special_function(%d)" % target.special_number)
758 ).scalar()
761 # associate the listener function with SomeClass,
762 # to execute during the "before_insert" hook
763 event.listen(SomeClass, "before_insert", my_before_insert_listener)
765 Available targets include:
767 * mapped classes
768 * unmapped superclasses of mapped or to-be-mapped classes
769 (using the ``propagate=True`` flag)
770 * :class:`_orm.Mapper` objects
771 * the :class:`_orm.Mapper` class itself indicates listening for all
772 mappers.
774 Mapper events provide hooks into critical sections of the
775 mapper, including those related to object instrumentation,
776 object loading, and object persistence. In particular, the
777 persistence methods :meth:`~.MapperEvents.before_insert`,
778 and :meth:`~.MapperEvents.before_update` are popular
779 places to augment the state being persisted - however, these
780 methods operate with several significant restrictions. The
781 user is encouraged to evaluate the
782 :meth:`.SessionEvents.before_flush` and
783 :meth:`.SessionEvents.after_flush` methods as more
784 flexible and user-friendly hooks in which to apply
785 additional database state during a flush.
787 When using :class:`.MapperEvents`, several modifiers are
788 available to the :func:`.event.listen` function.
790 :param propagate=False: When True, the event listener should
791 be applied to all inheriting mappers and/or the mappers of
792 inheriting classes, as well as any
793 mapper which is the target of this listener.
794 :param raw=False: When True, the "target" argument passed
795 to applicable event listener functions will be the
796 instance's :class:`.InstanceState` management
797 object, rather than the mapped instance itself.
798 :param retval=False: when True, the user-defined event function
799 must have a return value, the purpose of which is either to
800 control subsequent event propagation, or to otherwise alter
801 the operation in progress by the mapper. Possible return
802 values are:
804 * ``sqlalchemy.orm.interfaces.EXT_CONTINUE`` - continue event
805 processing normally.
806 * ``sqlalchemy.orm.interfaces.EXT_STOP`` - cancel all subsequent
807 event handlers in the chain.
808 * other values - the return value specified by specific listeners.
810 """
812 _target_class_doc = "SomeClass"
813 _dispatch_target = mapperlib.Mapper
815 @classmethod
816 def _new_mapper_instance(
817 cls,
818 class_: Union[DeclarativeAttributeIntercept, DeclarativeMeta, type],
819 mapper: Mapper[_O],
820 ) -> None:
821 _MapperEventsHold.populate(class_, mapper)
823 @classmethod
824 @util.preload_module("sqlalchemy.orm")
825 def _accept_with(
826 cls,
827 target: Union[mapperlib.Mapper[Any], Type[mapperlib.Mapper[Any]]],
828 identifier: str,
829 ) -> Optional[Union[mapperlib.Mapper[Any], Type[mapperlib.Mapper[Any]]]]:
830 orm = util.preloaded.orm
832 if target is orm.mapper: # type: ignore [attr-defined]
833 util.warn_deprecated(
834 "The `sqlalchemy.orm.mapper()` symbol is deprecated and "
835 "will be removed in a future release. For the mapper-wide "
836 "event target, use the 'sqlalchemy.orm.Mapper' class.",
837 "2.0",
838 )
839 return mapperlib.Mapper
840 elif isinstance(target, type):
841 if issubclass(target, mapperlib.Mapper):
842 return target
843 else:
844 mapper = _mapper_or_none(target)
845 if mapper is not None:
846 return mapper
847 else:
848 return _MapperEventsHold(target)
849 else:
850 return target
852 @classmethod
853 def _listen(
854 cls,
855 event_key: _EventKey[_ET],
856 raw: bool = False,
857 retval: bool = False,
858 propagate: bool = False,
859 **kw: Any,
860 ) -> None:
861 target, identifier, fn = (
862 event_key.dispatch_target,
863 event_key.identifier,
864 event_key._listen_fn,
865 )
867 if (
868 identifier in ("before_configured", "after_configured")
869 and target is not mapperlib.Mapper
870 ):
871 util.warn(
872 "'before_configured' and 'after_configured' ORM events "
873 "only invoke with the Mapper class "
874 "as the target."
875 )
877 if not raw or not retval:
878 if not raw:
879 meth = getattr(cls, identifier)
880 try:
881 target_index = (
882 inspect_getfullargspec(meth)[0].index("target") - 1
883 )
884 except ValueError:
885 target_index = None
887 def wrap(*arg: Any, **kw: Any) -> Any:
888 if not raw and target_index is not None:
889 arg = list(arg) # type: ignore [assignment]
890 arg[target_index] = arg[target_index].obj() # type: ignore [index] # noqa: E501
891 if not retval:
892 fn(*arg, **kw)
893 return interfaces.EXT_CONTINUE
894 else:
895 return fn(*arg, **kw)
897 event_key = event_key.with_wrapper(wrap)
899 if propagate:
900 for mapper in target.self_and_descendants:
901 event_key.with_dispatch_target(mapper).base_listen(
902 propagate=True, **kw
903 )
904 else:
905 event_key.base_listen(**kw)
907 @classmethod
908 def _clear(cls) -> None:
909 super()._clear()
910 _MapperEventsHold._clear()
912 def instrument_class(self, mapper: Mapper[_O], class_: Type[_O]) -> None:
913 r"""Receive a class when the mapper is first constructed,
914 before instrumentation is applied to the mapped class.
916 This event is the earliest phase of mapper construction.
917 Most attributes of the mapper are not yet initialized. To
918 receive an event within initial mapper construction where basic
919 state is available such as the :attr:`_orm.Mapper.attrs` collection,
920 the :meth:`_orm.MapperEvents.after_mapper_constructed` event may
921 be a better choice.
923 This listener can either be applied to the :class:`_orm.Mapper`
924 class overall, or to any un-mapped class which serves as a base
925 for classes that will be mapped (using the ``propagate=True`` flag)::
927 Base = declarative_base()
930 @event.listens_for(Base, "instrument_class", propagate=True)
931 def on_new_class(mapper, cls_):
932 "..."
934 :param mapper: the :class:`_orm.Mapper` which is the target
935 of this event.
936 :param class\_: the mapped class.
938 .. seealso::
940 :meth:`_orm.MapperEvents.after_mapper_constructed`
942 """
944 def after_mapper_constructed(
945 self, mapper: Mapper[_O], class_: Type[_O]
946 ) -> None:
947 """Receive a class and mapper when the :class:`_orm.Mapper` has been
948 fully constructed.
950 This event is called after the initial constructor for
951 :class:`_orm.Mapper` completes. This occurs after the
952 :meth:`_orm.MapperEvents.instrument_class` event and after the
953 :class:`_orm.Mapper` has done an initial pass of its arguments
954 to generate its collection of :class:`_orm.MapperProperty` objects,
955 which are accessible via the :meth:`_orm.Mapper.get_property`
956 method and the :attr:`_orm.Mapper.iterate_properties` attribute.
958 This event differs from the
959 :meth:`_orm.MapperEvents.before_mapper_configured` event in that it
960 is invoked within the constructor for :class:`_orm.Mapper`, rather
961 than within the :meth:`_orm.registry.configure` process. Currently,
962 this event is the only one which is appropriate for handlers that
963 wish to create additional mapped classes in response to the
964 construction of this :class:`_orm.Mapper`, which will be part of the
965 same configure step when :meth:`_orm.registry.configure` next runs.
967 .. versionadded:: 2.0.2
969 .. seealso::
971 :ref:`examples_versioning` - an example which illustrates the use
972 of the :meth:`_orm.MapperEvents.before_mapper_configured`
973 event to create new mappers to record change-audit histories on
974 objects.
976 """
978 @event._omit_standard_example
979 def before_mapper_configured(
980 self, mapper: Mapper[_O], class_: Type[_O]
981 ) -> None:
982 """Called right before a specific mapper is to be configured.
984 The :meth:`.MapperEvents.before_mapper_configured` event is invoked
985 for each mapper that is encountered when the
986 :func:`_orm.configure_mappers` function proceeds through the current
987 list of not-yet-configured mappers. It is similar to the
988 :meth:`.MapperEvents.mapper_configured` event, except that it's invoked
989 right before the configuration occurs, rather than afterwards.
991 The :meth:`.MapperEvents.before_mapper_configured` event includes
992 the special capability where it can force the configure step for a
993 specific mapper to be skipped; to use this feature, establish
994 the event using the ``retval=True`` parameter and return
995 the :attr:`.orm.interfaces.EXT_SKIP` symbol to indicate the mapper
996 should be left unconfigured::
998 from sqlalchemy import event
999 from sqlalchemy.orm import EXT_SKIP
1000 from sqlalchemy.orm import DeclarativeBase
1003 class DontConfigureBase(DeclarativeBase):
1004 pass
1007 @event.listens_for(
1008 DontConfigureBase,
1009 "before_mapper_configured",
1010 # support return values for the event
1011 retval=True,
1012 # propagate the listener to all subclasses of
1013 # DontConfigureBase
1014 propagate=True,
1015 )
1016 def dont_configure(mapper, cls):
1017 return EXT_SKIP
1019 .. seealso::
1021 :meth:`.MapperEvents.before_configured`
1023 :meth:`.MapperEvents.after_configured`
1025 :meth:`.MapperEvents.mapper_configured`
1027 """
1029 def mapper_configured(self, mapper: Mapper[_O], class_: Type[_O]) -> None:
1030 r"""Called when a specific mapper has completed its own configuration
1031 within the scope of the :func:`.configure_mappers` call.
1033 The :meth:`.MapperEvents.mapper_configured` event is invoked
1034 for each mapper that is encountered when the
1035 :func:`_orm.configure_mappers` function proceeds through the current
1036 list of not-yet-configured mappers.
1037 :func:`_orm.configure_mappers` is typically invoked
1038 automatically as mappings are first used, as well as each time
1039 new mappers have been made available and new mapper use is
1040 detected.
1042 When the event is called, the mapper should be in its final
1043 state, but **not including backrefs** that may be invoked from
1044 other mappers; they might still be pending within the
1045 configuration operation. Bidirectional relationships that
1046 are instead configured via the
1047 :paramref:`.orm.relationship.back_populates` argument
1048 *will* be fully available, since this style of relationship does not
1049 rely upon other possibly-not-configured mappers to know that they
1050 exist.
1052 For an event that is guaranteed to have **all** mappers ready
1053 to go including backrefs that are defined only on other
1054 mappings, use the :meth:`.MapperEvents.after_configured`
1055 event; this event invokes only after all known mappings have been
1056 fully configured.
1058 The :meth:`.MapperEvents.mapper_configured` event, unlike the
1059 :meth:`.MapperEvents.before_configured` or
1060 :meth:`.MapperEvents.after_configured` events, is called for each
1061 mapper/class individually, and the mapper is passed to the event
1062 itself. It also is called exactly once for a particular mapper. The
1063 event is therefore useful for configurational steps that benefit from
1064 being invoked just once on a specific mapper basis, which don't require
1065 that "backref" configurations are necessarily ready yet.
1067 :param mapper: the :class:`_orm.Mapper` which is the target
1068 of this event.
1069 :param class\_: the mapped class.
1071 .. seealso::
1073 :meth:`.MapperEvents.before_configured`
1075 :meth:`.MapperEvents.after_configured`
1077 :meth:`.MapperEvents.before_mapper_configured`
1079 """
1080 # TODO: need coverage for this event
1082 @event._omit_standard_example
1083 def before_configured(self) -> None:
1084 """Called before a series of mappers have been configured.
1086 The :meth:`.MapperEvents.before_configured` event is invoked
1087 each time the :func:`_orm.configure_mappers` function is
1088 invoked, before the function has done any of its work.
1089 :func:`_orm.configure_mappers` is typically invoked
1090 automatically as mappings are first used, as well as each time
1091 new mappers have been made available and new mapper use is
1092 detected.
1094 Similar events to this one include
1095 :meth:`.MapperEvents.after_configured`, which is invoked after a series
1096 of mappers has been configured, as well as
1097 :meth:`.MapperEvents.before_mapper_configured` and
1098 :meth:`.MapperEvents.mapper_configured`, which are both invoked on a
1099 per-mapper basis.
1101 This event can **only** be applied to the :class:`_orm.Mapper` class,
1102 and not to individual mappings or mapped classes::
1104 from sqlalchemy.orm import Mapper
1107 @event.listens_for(Mapper, "before_configured")
1108 def go(): ...
1110 Typically, this event is called once per application, but in practice
1111 may be called more than once, any time new mappers are to be affected
1112 by a :func:`_orm.configure_mappers` call. If new mappings are
1113 constructed after existing ones have already been used, this event will
1114 likely be called again.
1116 .. seealso::
1118 :meth:`.MapperEvents.before_mapper_configured`
1120 :meth:`.MapperEvents.mapper_configured`
1122 :meth:`.MapperEvents.after_configured`
1124 """
1126 @event._omit_standard_example
1127 def after_configured(self) -> None:
1128 """Called after a series of mappers have been configured.
1130 The :meth:`.MapperEvents.after_configured` event is invoked
1131 each time the :func:`_orm.configure_mappers` function is
1132 invoked, after the function has completed its work.
1133 :func:`_orm.configure_mappers` is typically invoked
1134 automatically as mappings are first used, as well as each time
1135 new mappers have been made available and new mapper use is
1136 detected.
1138 Similar events to this one include
1139 :meth:`.MapperEvents.before_configured`, which is invoked before a
1140 series of mappers are configured, as well as
1141 :meth:`.MapperEvents.before_mapper_configured` and
1142 :meth:`.MapperEvents.mapper_configured`, which are both invoked on a
1143 per-mapper basis.
1145 This event can **only** be applied to the :class:`_orm.Mapper` class,
1146 and not to individual mappings or mapped classes::
1148 from sqlalchemy.orm import Mapper
1151 @event.listens_for(Mapper, "after_configured")
1152 def go(): ...
1154 Typically, this event is called once per application, but in practice
1155 may be called more than once, any time new mappers are to be affected
1156 by a :func:`_orm.configure_mappers` call. If new mappings are
1157 constructed after existing ones have already been used, this event will
1158 likely be called again.
1160 .. seealso::
1162 :meth:`.MapperEvents.before_mapper_configured`
1164 :meth:`.MapperEvents.mapper_configured`
1166 :meth:`.MapperEvents.before_configured`
1168 """
1170 def before_insert(
1171 self, mapper: Mapper[_O], connection: Connection, target: _O
1172 ) -> None:
1173 """Receive an object instance before an INSERT statement
1174 is emitted corresponding to that instance.
1176 .. note:: this event **only** applies to the
1177 :ref:`session flush operation <session_flushing>`
1178 and does **not** apply to the ORM DML operations described at
1179 :ref:`orm_expression_update_delete`. To intercept ORM
1180 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1182 This event is used to modify local, non-object related
1183 attributes on the instance before an INSERT occurs, as well
1184 as to emit additional SQL statements on the given
1185 connection.
1187 The event is often called for a batch of objects of the
1188 same class before their INSERT statements are emitted at
1189 once in a later step. In the extremely rare case that
1190 this is not desirable, the :class:`_orm.Mapper` object can be
1191 configured with ``batch=False``, which will cause
1192 batches of instances to be broken up into individual
1193 (and more poorly performing) event->persist->event
1194 steps.
1196 .. warning::
1198 Mapper-level flush events only allow **very limited operations**,
1199 on attributes local to the row being operated upon only,
1200 as well as allowing any SQL to be emitted on the given
1201 :class:`_engine.Connection`. **Please read fully** the notes
1202 at :ref:`session_persistence_mapper` for guidelines on using
1203 these methods; generally, the :meth:`.SessionEvents.before_flush`
1204 method should be preferred for general on-flush changes.
1206 :param mapper: the :class:`_orm.Mapper` which is the target
1207 of this event.
1208 :param connection: the :class:`_engine.Connection` being used to
1209 emit INSERT statements for this instance. This
1210 provides a handle into the current transaction on the
1211 target database specific to this instance.
1212 :param target: the mapped instance being persisted. If
1213 the event is configured with ``raw=True``, this will
1214 instead be the :class:`.InstanceState` state-management
1215 object associated with the instance.
1216 :return: No return value is supported by this event.
1218 .. seealso::
1220 :ref:`session_persistence_events`
1222 """
1224 def after_insert(
1225 self, mapper: Mapper[_O], connection: Connection, target: _O
1226 ) -> None:
1227 """Receive an object instance after an INSERT statement
1228 is emitted corresponding to that instance.
1230 .. note:: this event **only** applies to the
1231 :ref:`session flush operation <session_flushing>`
1232 and does **not** apply to the ORM DML operations described at
1233 :ref:`orm_expression_update_delete`. To intercept ORM
1234 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1236 This event is used to modify in-Python-only
1237 state on the instance after an INSERT occurs, as well
1238 as to emit additional SQL statements on the given
1239 connection.
1241 The event is often called for a batch of objects of the
1242 same class after their INSERT statements have been
1243 emitted at once in a previous step. In the extremely
1244 rare case that this is not desirable, the
1245 :class:`_orm.Mapper` object can be configured with ``batch=False``,
1246 which will cause batches of instances to be broken up
1247 into individual (and more poorly performing)
1248 event->persist->event steps.
1250 .. warning::
1252 Mapper-level flush events only allow **very limited operations**,
1253 on attributes local to the row being operated upon only,
1254 as well as allowing any SQL to be emitted on the given
1255 :class:`_engine.Connection`. **Please read fully** the notes
1256 at :ref:`session_persistence_mapper` for guidelines on using
1257 these methods; generally, the :meth:`.SessionEvents.before_flush`
1258 method should be preferred for general on-flush changes.
1260 :param mapper: the :class:`_orm.Mapper` which is the target
1261 of this event.
1262 :param connection: the :class:`_engine.Connection` being used to
1263 emit INSERT statements for this instance. This
1264 provides a handle into the current transaction on the
1265 target database specific to this instance.
1266 :param target: the mapped instance being persisted. If
1267 the event is configured with ``raw=True``, this will
1268 instead be the :class:`.InstanceState` state-management
1269 object associated with the instance.
1270 :return: No return value is supported by this event.
1272 .. seealso::
1274 :ref:`session_persistence_events`
1276 """
1278 def before_update(
1279 self, mapper: Mapper[_O], connection: Connection, target: _O
1280 ) -> None:
1281 """Receive an object instance before an UPDATE statement
1282 is emitted corresponding to that instance.
1284 .. note:: this event **only** applies to the
1285 :ref:`session flush operation <session_flushing>`
1286 and does **not** apply to the ORM DML operations described at
1287 :ref:`orm_expression_update_delete`. To intercept ORM
1288 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1290 This event is used to modify local, non-object related
1291 attributes on the instance before an UPDATE occurs, as well
1292 as to emit additional SQL statements on the given
1293 connection.
1295 This method is called for all instances that are
1296 marked as "dirty", *even those which have no net changes
1297 to their column-based attributes*. An object is marked
1298 as dirty when any of its column-based attributes have a
1299 "set attribute" operation called or when any of its
1300 collections are modified. If, at update time, no
1301 column-based attributes have any net changes, no UPDATE
1302 statement will be issued. This means that an instance
1303 being sent to :meth:`~.MapperEvents.before_update` is
1304 *not* a guarantee that an UPDATE statement will be
1305 issued, although you can affect the outcome here by
1306 modifying attributes so that a net change in value does
1307 exist.
1309 To detect if the column-based attributes on the object have net
1310 changes, and will therefore generate an UPDATE statement, use
1311 ``object_session(instance).is_modified(instance,
1312 include_collections=False)``.
1314 The event is often called for a batch of objects of the
1315 same class before their UPDATE statements are emitted at
1316 once in a later step. In the extremely rare case that
1317 this is not desirable, the :class:`_orm.Mapper` can be
1318 configured with ``batch=False``, which will cause
1319 batches of instances to be broken up into individual
1320 (and more poorly performing) event->persist->event
1321 steps.
1323 .. warning::
1325 Mapper-level flush events only allow **very limited operations**,
1326 on attributes local to the row being operated upon only,
1327 as well as allowing any SQL to be emitted on the given
1328 :class:`_engine.Connection`. **Please read fully** the notes
1329 at :ref:`session_persistence_mapper` for guidelines on using
1330 these methods; generally, the :meth:`.SessionEvents.before_flush`
1331 method should be preferred for general on-flush changes.
1333 :param mapper: the :class:`_orm.Mapper` which is the target
1334 of this event.
1335 :param connection: the :class:`_engine.Connection` being used to
1336 emit UPDATE statements for this instance. This
1337 provides a handle into the current transaction on the
1338 target database specific to this instance.
1339 :param target: the mapped instance being persisted. If
1340 the event is configured with ``raw=True``, this will
1341 instead be the :class:`.InstanceState` state-management
1342 object associated with the instance.
1343 :return: No return value is supported by this event.
1345 .. seealso::
1347 :ref:`session_persistence_events`
1349 """
1351 def after_update(
1352 self, mapper: Mapper[_O], connection: Connection, target: _O
1353 ) -> None:
1354 """Receive an object instance after an UPDATE statement
1355 is emitted corresponding to that instance.
1357 .. note:: this event **only** applies to the
1358 :ref:`session flush operation <session_flushing>`
1359 and does **not** apply to the ORM DML operations described at
1360 :ref:`orm_expression_update_delete`. To intercept ORM
1361 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1363 This event is used to modify in-Python-only
1364 state on the instance after an UPDATE occurs, as well
1365 as to emit additional SQL statements on the given
1366 connection.
1368 This method is called for all instances that are
1369 marked as "dirty", *even those which have no net changes
1370 to their column-based attributes*, and for which
1371 no UPDATE statement has proceeded. An object is marked
1372 as dirty when any of its column-based attributes have a
1373 "set attribute" operation called or when any of its
1374 collections are modified. If, at update time, no
1375 column-based attributes have any net changes, no UPDATE
1376 statement will be issued. This means that an instance
1377 being sent to :meth:`~.MapperEvents.after_update` is
1378 *not* a guarantee that an UPDATE statement has been
1379 issued.
1381 To detect if the column-based attributes on the object have net
1382 changes, and therefore resulted in an UPDATE statement, use
1383 ``object_session(instance).is_modified(instance,
1384 include_collections=False)``.
1386 The event is often called for a batch of objects of the
1387 same class after their UPDATE statements have been emitted at
1388 once in a previous step. In the extremely rare case that
1389 this is not desirable, the :class:`_orm.Mapper` can be
1390 configured with ``batch=False``, which will cause
1391 batches of instances to be broken up into individual
1392 (and more poorly performing) event->persist->event
1393 steps.
1395 .. warning::
1397 Mapper-level flush events only allow **very limited operations**,
1398 on attributes local to the row being operated upon only,
1399 as well as allowing any SQL to be emitted on the given
1400 :class:`_engine.Connection`. **Please read fully** the notes
1401 at :ref:`session_persistence_mapper` for guidelines on using
1402 these methods; generally, the :meth:`.SessionEvents.before_flush`
1403 method should be preferred for general on-flush changes.
1405 :param mapper: the :class:`_orm.Mapper` which is the target
1406 of this event.
1407 :param connection: the :class:`_engine.Connection` being used to
1408 emit UPDATE statements for this instance. This
1409 provides a handle into the current transaction on the
1410 target database specific to this instance.
1411 :param target: the mapped instance being persisted. If
1412 the event is configured with ``raw=True``, this will
1413 instead be the :class:`.InstanceState` state-management
1414 object associated with the instance.
1415 :return: No return value is supported by this event.
1417 .. seealso::
1419 :ref:`session_persistence_events`
1421 """
1423 def before_delete(
1424 self, mapper: Mapper[_O], connection: Connection, target: _O
1425 ) -> None:
1426 """Receive an object instance before a DELETE statement
1427 is emitted corresponding to that instance.
1429 .. note:: this event **only** applies to the
1430 :ref:`session flush operation <session_flushing>`
1431 and does **not** apply to the ORM DML operations described at
1432 :ref:`orm_expression_update_delete`. To intercept ORM
1433 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1435 This event is used to emit additional SQL statements on
1436 the given connection as well as to perform application
1437 specific bookkeeping related to a deletion event.
1439 The event is often called for a batch of objects of the
1440 same class before their DELETE statements are emitted at
1441 once in a later step.
1443 .. warning::
1445 Mapper-level flush events only allow **very limited operations**,
1446 on attributes local to the row being operated upon only,
1447 as well as allowing any SQL to be emitted on the given
1448 :class:`_engine.Connection`. **Please read fully** the notes
1449 at :ref:`session_persistence_mapper` for guidelines on using
1450 these methods; generally, the :meth:`.SessionEvents.before_flush`
1451 method should be preferred for general on-flush changes.
1453 :param mapper: the :class:`_orm.Mapper` which is the target
1454 of this event.
1455 :param connection: the :class:`_engine.Connection` being used to
1456 emit DELETE statements for this instance. This
1457 provides a handle into the current transaction on the
1458 target database specific to this instance.
1459 :param target: the mapped instance being deleted. If
1460 the event is configured with ``raw=True``, this will
1461 instead be the :class:`.InstanceState` state-management
1462 object associated with the instance.
1463 :return: No return value is supported by this event.
1465 .. seealso::
1467 :ref:`session_persistence_events`
1469 """
1471 def after_delete(
1472 self, mapper: Mapper[_O], connection: Connection, target: _O
1473 ) -> None:
1474 """Receive an object instance after a DELETE statement
1475 has been emitted corresponding to that instance.
1477 .. note:: this event **only** applies to the
1478 :ref:`session flush operation <session_flushing>`
1479 and does **not** apply to the ORM DML operations described at
1480 :ref:`orm_expression_update_delete`. To intercept ORM
1481 DML events, use :meth:`_orm.SessionEvents.do_orm_execute`.
1483 This event is used to emit additional SQL statements on
1484 the given connection as well as to perform application
1485 specific bookkeeping related to a deletion event.
1487 The event is often called for a batch of objects of the
1488 same class after their DELETE statements have been emitted at
1489 once in a previous step.
1491 .. warning::
1493 Mapper-level flush events only allow **very limited operations**,
1494 on attributes local to the row being operated upon only,
1495 as well as allowing any SQL to be emitted on the given
1496 :class:`_engine.Connection`. **Please read fully** the notes
1497 at :ref:`session_persistence_mapper` for guidelines on using
1498 these methods; generally, the :meth:`.SessionEvents.before_flush`
1499 method should be preferred for general on-flush changes.
1501 :param mapper: the :class:`_orm.Mapper` which is the target
1502 of this event.
1503 :param connection: the :class:`_engine.Connection` being used to
1504 emit DELETE statements for this instance. This
1505 provides a handle into the current transaction on the
1506 target database specific to this instance.
1507 :param target: the mapped instance being deleted. If
1508 the event is configured with ``raw=True``, this will
1509 instead be the :class:`.InstanceState` state-management
1510 object associated with the instance.
1511 :return: No return value is supported by this event.
1513 .. seealso::
1515 :ref:`session_persistence_events`
1517 """
1520class _MapperEventsHold(_EventsHold[_ET]):
1521 all_holds = weakref.WeakKeyDictionary()
1523 def resolve(
1524 self, class_: Union[Type[_T], _InternalEntityType[_T]]
1525 ) -> Optional[Mapper[_T]]:
1526 return _mapper_or_none(class_)
1528 # this fails on pyright if you use Any. Fails on mypy if you use _ET
1529 class HoldMapperEvents(_EventsHold.HoldEvents[_ET], MapperEvents): # type: ignore[valid-type,misc] # noqa: E501
1530 pass
1532 dispatch = event.dispatcher(HoldMapperEvents)
1535_sessionevents_lifecycle_event_names: Set[str] = set()
1538class SessionEvents(event.Events[Session]):
1539 """Define events specific to :class:`.Session` lifecycle.
1541 e.g.::
1543 from sqlalchemy import event
1544 from sqlalchemy.orm import sessionmaker
1547 def my_before_commit(session):
1548 print("before commit!")
1551 Session = sessionmaker()
1553 event.listen(Session, "before_commit", my_before_commit)
1555 The :func:`~.event.listen` function will accept
1556 :class:`.Session` objects as well as the return result
1557 of :class:`~.sessionmaker()` and :class:`~.scoped_session()`.
1559 Additionally, it accepts the :class:`.Session` class which
1560 will apply listeners to all :class:`.Session` instances
1561 globally.
1563 :param raw=False: When True, the "target" argument passed
1564 to applicable event listener functions that work on individual
1565 objects will be the instance's :class:`.InstanceState` management
1566 object, rather than the mapped instance itself.
1568 .. versionadded:: 1.3.14
1570 :param restore_load_context=False: Applies to the
1571 :meth:`.SessionEvents.loaded_as_persistent` event. Restores the loader
1572 context of the object when the event hook is complete, so that ongoing
1573 eager load operations continue to target the object appropriately. A
1574 warning is emitted if the object is moved to a new loader context from
1575 within this event if this flag is not set.
1577 .. versionadded:: 1.3.14
1579 """
1581 _target_class_doc = "SomeSessionClassOrObject"
1583 _dispatch_target = Session
1585 def _lifecycle_event( # type: ignore [misc]
1586 fn: Callable[[SessionEvents, Session, Any], None],
1587 ) -> Callable[[SessionEvents, Session, Any], None]:
1588 _sessionevents_lifecycle_event_names.add(fn.__name__)
1589 return fn
1591 @classmethod
1592 def _accept_with( # type: ignore [return]
1593 cls, target: Any, identifier: str
1594 ) -> Union[Session, type]:
1595 if isinstance(target, scoped_session):
1596 target = target.session_factory
1597 if not isinstance(target, sessionmaker) and (
1598 not isinstance(target, type) or not issubclass(target, Session)
1599 ):
1600 raise exc.ArgumentError(
1601 "Session event listen on a scoped_session "
1602 "requires that its creation callable "
1603 "is associated with the Session class."
1604 )
1606 if isinstance(target, sessionmaker):
1607 return target.class_
1608 elif isinstance(target, type):
1609 if issubclass(target, scoped_session):
1610 return Session
1611 elif issubclass(target, Session):
1612 return target
1613 elif isinstance(target, Session):
1614 return target
1615 elif hasattr(target, "_no_async_engine_events"):
1616 target._no_async_engine_events()
1617 else:
1618 # allows alternate SessionEvents-like-classes to be consulted
1619 return event.Events._accept_with(target, identifier) # type: ignore [return-value] # noqa: E501
1621 @classmethod
1622 def _listen(
1623 cls,
1624 event_key: Any,
1625 *,
1626 raw: bool = False,
1627 restore_load_context: bool = False,
1628 **kw: Any,
1629 ) -> None:
1630 is_instance_event = (
1631 event_key.identifier in _sessionevents_lifecycle_event_names
1632 )
1634 if is_instance_event:
1635 if not raw or restore_load_context:
1636 fn = event_key._listen_fn
1638 def wrap(
1639 session: Session,
1640 state: InstanceState[_O],
1641 *arg: Any,
1642 **kw: Any,
1643 ) -> Optional[Any]:
1644 if not raw:
1645 target = state.obj()
1646 if target is None:
1647 # existing behavior is that if the object is
1648 # garbage collected, no event is emitted
1649 return None
1650 else:
1651 target = state # type: ignore [assignment]
1652 if restore_load_context:
1653 runid = state.runid
1654 try:
1655 return fn(session, target, *arg, **kw)
1656 finally:
1657 if restore_load_context:
1658 state.runid = runid
1660 event_key = event_key.with_wrapper(wrap)
1662 event_key.base_listen(**kw)
1664 def do_orm_execute(self, orm_execute_state: ORMExecuteState) -> None:
1665 """Intercept statement executions that occur on behalf of an
1666 ORM :class:`.Session` object.
1668 This event is invoked for all top-level SQL statements invoked from the
1669 :meth:`_orm.Session.execute` method, as well as related methods such as
1670 :meth:`_orm.Session.scalars` and :meth:`_orm.Session.scalar`. As of
1671 SQLAlchemy 1.4, all ORM queries that run through the
1672 :meth:`_orm.Session.execute` method as well as related methods
1673 :meth:`_orm.Session.scalars`, :meth:`_orm.Session.scalar` etc.
1674 will participate in this event.
1675 This event hook does **not** apply to the queries that are
1676 emitted internally within the ORM flush process, i.e. the
1677 process described at :ref:`session_flushing`.
1679 .. note:: The :meth:`_orm.SessionEvents.do_orm_execute` event hook
1680 is triggered **for ORM statement executions only**, meaning those
1681 invoked via the :meth:`_orm.Session.execute` and similar methods on
1682 the :class:`_orm.Session` object. It does **not** trigger for
1683 statements that are invoked by SQLAlchemy Core only, i.e. statements
1684 invoked directly using :meth:`_engine.Connection.execute` or
1685 otherwise originating from an :class:`_engine.Engine` object without
1686 any :class:`_orm.Session` involved. To intercept **all** SQL
1687 executions regardless of whether the Core or ORM APIs are in use,
1688 see the event hooks at :class:`.ConnectionEvents`, such as
1689 :meth:`.ConnectionEvents.before_execute` and
1690 :meth:`.ConnectionEvents.before_cursor_execute`.
1692 Also, this event hook does **not** apply to queries that are
1693 emitted internally within the ORM flush process,
1694 i.e. the process described at :ref:`session_flushing`; to
1695 intercept steps within the flush process, see the event
1696 hooks described at :ref:`session_persistence_events` as
1697 well as :ref:`session_persistence_mapper`.
1699 This event is a ``do_`` event, meaning it has the capability to replace
1700 the operation that the :meth:`_orm.Session.execute` method normally
1701 performs. The intended use for this includes sharding and
1702 result-caching schemes which may seek to invoke the same statement
1703 across multiple database connections, returning a result that is
1704 merged from each of them, or which don't invoke the statement at all,
1705 instead returning data from a cache.
1707 The hook intends to replace the use of the
1708 ``Query._execute_and_instances`` method that could be subclassed prior
1709 to SQLAlchemy 1.4.
1711 :param orm_execute_state: an instance of :class:`.ORMExecuteState`
1712 which contains all information about the current execution, as well
1713 as helper functions used to derive other commonly required
1714 information. See that object for details.
1716 .. seealso::
1718 :ref:`session_execute_events` - top level documentation on how
1719 to use :meth:`_orm.SessionEvents.do_orm_execute`
1721 :class:`.ORMExecuteState` - the object passed to the
1722 :meth:`_orm.SessionEvents.do_orm_execute` event which contains
1723 all information about the statement to be invoked. It also
1724 provides an interface to extend the current statement, options,
1725 and parameters as well as an option that allows programmatic
1726 invocation of the statement at any point.
1728 :ref:`examples_session_orm_events` - includes examples of using
1729 :meth:`_orm.SessionEvents.do_orm_execute`
1731 :ref:`examples_caching` - an example of how to integrate
1732 Dogpile caching with the ORM :class:`_orm.Session` making use
1733 of the :meth:`_orm.SessionEvents.do_orm_execute` event hook.
1735 :ref:`examples_sharding` - the Horizontal Sharding example /
1736 extension relies upon the
1737 :meth:`_orm.SessionEvents.do_orm_execute` event hook to invoke a
1738 SQL statement on multiple backends and return a merged result.
1741 .. versionadded:: 1.4
1743 """
1745 def after_transaction_create(
1746 self, session: Session, transaction: SessionTransaction
1747 ) -> None:
1748 """Execute when a new :class:`.SessionTransaction` is created.
1750 This event differs from :meth:`~.SessionEvents.after_begin`
1751 in that it occurs for each :class:`.SessionTransaction`
1752 overall, as opposed to when transactions are begun
1753 on individual database connections. It is also invoked
1754 for nested transactions and subtransactions, and is always
1755 matched by a corresponding
1756 :meth:`~.SessionEvents.after_transaction_end` event
1757 (assuming normal operation of the :class:`.Session`).
1759 :param session: the target :class:`.Session`.
1760 :param transaction: the target :class:`.SessionTransaction`.
1762 To detect if this is the outermost
1763 :class:`.SessionTransaction`, as opposed to a "subtransaction" or a
1764 SAVEPOINT, test that the :attr:`.SessionTransaction.parent` attribute
1765 is ``None``::
1767 @event.listens_for(session, "after_transaction_create")
1768 def after_transaction_create(session, transaction):
1769 if transaction.parent is None:
1770 ... # work with top-level transaction
1772 To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the
1773 :attr:`.SessionTransaction.nested` attribute::
1775 @event.listens_for(session, "after_transaction_create")
1776 def after_transaction_create(session, transaction):
1777 if transaction.nested:
1778 ... # work with SAVEPOINT transaction
1780 .. seealso::
1782 :class:`.SessionTransaction`
1784 :meth:`~.SessionEvents.after_transaction_end`
1786 """
1788 def after_transaction_end(
1789 self, session: Session, transaction: SessionTransaction
1790 ) -> None:
1791 """Execute when the span of a :class:`.SessionTransaction` ends.
1793 This event differs from :meth:`~.SessionEvents.after_commit`
1794 in that it corresponds to all :class:`.SessionTransaction`
1795 objects in use, including those for nested transactions
1796 and subtransactions, and is always matched by a corresponding
1797 :meth:`~.SessionEvents.after_transaction_create` event.
1799 :param session: the target :class:`.Session`.
1800 :param transaction: the target :class:`.SessionTransaction`.
1802 To detect if this is the outermost
1803 :class:`.SessionTransaction`, as opposed to a "subtransaction" or a
1804 SAVEPOINT, test that the :attr:`.SessionTransaction.parent` attribute
1805 is ``None``::
1807 @event.listens_for(session, "after_transaction_create")
1808 def after_transaction_end(session, transaction):
1809 if transaction.parent is None:
1810 ... # work with top-level transaction
1812 To detect if the :class:`.SessionTransaction` is a SAVEPOINT, use the
1813 :attr:`.SessionTransaction.nested` attribute::
1815 @event.listens_for(session, "after_transaction_create")
1816 def after_transaction_end(session, transaction):
1817 if transaction.nested:
1818 ... # work with SAVEPOINT transaction
1820 .. seealso::
1822 :class:`.SessionTransaction`
1824 :meth:`~.SessionEvents.after_transaction_create`
1826 """
1828 def before_commit(self, session: Session) -> None:
1829 """Execute before commit is called.
1831 .. note::
1833 The :meth:`~.SessionEvents.before_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 :param session: The target :class:`.Session`.
1844 .. seealso::
1846 :meth:`~.SessionEvents.after_commit`
1848 :meth:`~.SessionEvents.after_begin`
1850 :meth:`~.SessionEvents.after_transaction_create`
1852 :meth:`~.SessionEvents.after_transaction_end`
1854 """
1856 def after_commit(self, session: Session) -> None:
1857 """Execute after a commit has occurred.
1859 .. note::
1861 The :meth:`~.SessionEvents.after_commit` hook is *not* per-flush,
1862 that is, the :class:`.Session` can emit SQL to the database
1863 many times within the scope of a transaction.
1864 For interception of these events, use the
1865 :meth:`~.SessionEvents.before_flush`,
1866 :meth:`~.SessionEvents.after_flush`, or
1867 :meth:`~.SessionEvents.after_flush_postexec`
1868 events.
1870 .. note::
1872 The :class:`.Session` is not in an active transaction
1873 when the :meth:`~.SessionEvents.after_commit` event is invoked,
1874 and therefore can not emit SQL. To emit SQL corresponding to
1875 every transaction, use the :meth:`~.SessionEvents.before_commit`
1876 event.
1878 :param session: The target :class:`.Session`.
1880 .. seealso::
1882 :meth:`~.SessionEvents.before_commit`
1884 :meth:`~.SessionEvents.after_begin`
1886 :meth:`~.SessionEvents.after_transaction_create`
1888 :meth:`~.SessionEvents.after_transaction_end`
1890 """
1892 def after_rollback(self, session: Session) -> None:
1893 """Execute after a real DBAPI rollback has occurred.
1895 Note that this event only fires when the *actual* rollback against
1896 the database occurs - it does *not* fire each time the
1897 :meth:`.Session.rollback` method is called, if the underlying
1898 DBAPI transaction has already been rolled back. In many
1899 cases, the :class:`.Session` will not be in
1900 an "active" state during this event, as the current
1901 transaction is not valid. To acquire a :class:`.Session`
1902 which is active after the outermost rollback has proceeded,
1903 use the :meth:`.SessionEvents.after_soft_rollback` event, checking the
1904 :attr:`.Session.is_active` flag.
1906 :param session: The target :class:`.Session`.
1908 """
1910 def after_soft_rollback(
1911 self, session: Session, previous_transaction: SessionTransaction
1912 ) -> None:
1913 """Execute after any rollback has occurred, including "soft"
1914 rollbacks that don't actually emit at the DBAPI level.
1916 This corresponds to both nested and outer rollbacks, i.e.
1917 the innermost rollback that calls the DBAPI's
1918 rollback() method, as well as the enclosing rollback
1919 calls that only pop themselves from the transaction stack.
1921 The given :class:`.Session` can be used to invoke SQL and
1922 :meth:`.Session.query` operations after an outermost rollback
1923 by first checking the :attr:`.Session.is_active` flag::
1925 @event.listens_for(Session, "after_soft_rollback")
1926 def do_something(session, previous_transaction):
1927 if session.is_active:
1928 session.execute(text("select * from some_table"))
1930 :param session: The target :class:`.Session`.
1931 :param previous_transaction: The :class:`.SessionTransaction`
1932 transactional marker object which was just closed. The current
1933 :class:`.SessionTransaction` for the given :class:`.Session` is
1934 available via the :attr:`.Session.transaction` attribute.
1936 """
1938 def before_flush(
1939 self,
1940 session: Session,
1941 flush_context: UOWTransaction,
1942 instances: Optional[Sequence[_O]],
1943 ) -> None:
1944 """Execute before flush process has started.
1946 :param session: The target :class:`.Session`.
1947 :param flush_context: Internal :class:`.UOWTransaction` object
1948 which handles the details of the flush.
1949 :param instances: Usually ``None``, this is the collection of
1950 objects which can be passed to the :meth:`.Session.flush` method
1951 (note this usage is deprecated).
1953 .. seealso::
1955 :meth:`~.SessionEvents.after_flush`
1957 :meth:`~.SessionEvents.after_flush_postexec`
1959 :ref:`session_persistence_events`
1961 """
1963 def after_flush(
1964 self, session: Session, flush_context: UOWTransaction
1965 ) -> None:
1966 """Execute after flush has completed, but before commit has been
1967 called.
1969 Note that the session's state is still in pre-flush, i.e. 'new',
1970 'dirty', and 'deleted' lists still show pre-flush state as well
1971 as the history settings on instance attributes.
1973 .. warning:: This event runs after the :class:`.Session` has emitted
1974 SQL to modify the database, but **before** it has altered its
1975 internal state to reflect those changes, including that newly
1976 inserted objects are placed into the identity map. ORM operations
1977 emitted within this event such as loads of related items
1978 may produce new identity map entries that will immediately
1979 be replaced, sometimes causing confusing results. SQLAlchemy will
1980 emit a warning for this condition as of version 1.3.9.
1982 :param session: The target :class:`.Session`.
1983 :param flush_context: Internal :class:`.UOWTransaction` object
1984 which handles the details of the flush.
1986 .. seealso::
1988 :meth:`~.SessionEvents.before_flush`
1990 :meth:`~.SessionEvents.after_flush_postexec`
1992 :ref:`session_persistence_events`
1994 """
1996 def after_flush_postexec(
1997 self, session: Session, flush_context: UOWTransaction
1998 ) -> None:
1999 """Execute after flush has completed, and after the post-exec
2000 state occurs.
2002 This will be when the 'new', 'dirty', and 'deleted' lists are in
2003 their final state. An actual commit() may or may not have
2004 occurred, depending on whether or not the flush started its own
2005 transaction or participated in a larger transaction.
2007 :param session: The target :class:`.Session`.
2008 :param flush_context: Internal :class:`.UOWTransaction` object
2009 which handles the details of the flush.
2012 .. seealso::
2014 :meth:`~.SessionEvents.before_flush`
2016 :meth:`~.SessionEvents.after_flush`
2018 :ref:`session_persistence_events`
2020 """
2022 def after_begin(
2023 self,
2024 session: Session,
2025 transaction: SessionTransaction,
2026 connection: Connection,
2027 ) -> None:
2028 """Execute after a transaction is begun on a connection.
2030 .. note:: This event is called within the process of the
2031 :class:`_orm.Session` modifying its own internal state.
2032 To invoke SQL operations within this hook, use the
2033 :class:`_engine.Connection` provided to the event;
2034 do not run SQL operations using the :class:`_orm.Session`
2035 directly.
2037 :param session: The target :class:`.Session`.
2038 :param transaction: The :class:`.SessionTransaction`.
2039 :param connection: The :class:`_engine.Connection` object
2040 which will be used for SQL statements.
2042 .. seealso::
2044 :meth:`~.SessionEvents.before_commit`
2046 :meth:`~.SessionEvents.after_commit`
2048 :meth:`~.SessionEvents.after_transaction_create`
2050 :meth:`~.SessionEvents.after_transaction_end`
2052 """
2054 @_lifecycle_event
2055 def before_attach(self, session: Session, instance: _O) -> None:
2056 """Execute before an instance is attached to a session.
2058 This is called before an add, delete or merge causes
2059 the object to be part of the session.
2061 .. seealso::
2063 :meth:`~.SessionEvents.after_attach`
2065 :ref:`session_lifecycle_events`
2067 """
2069 @_lifecycle_event
2070 def after_attach(self, session: Session, instance: _O) -> None:
2071 """Execute after an instance is attached to a session.
2073 This is called after an add, delete or merge.
2075 .. note::
2077 As of 0.8, this event fires off *after* the item
2078 has been fully associated with the session, which is
2079 different than previous releases. For event
2080 handlers that require the object not yet
2081 be part of session state (such as handlers which
2082 may autoflush while the target object is not
2083 yet complete) consider the
2084 new :meth:`.before_attach` event.
2086 .. seealso::
2088 :meth:`~.SessionEvents.before_attach`
2090 :ref:`session_lifecycle_events`
2092 """
2094 @event._legacy_signature(
2095 "0.9",
2096 ["session", "query", "query_context", "result"],
2097 lambda update_context: (
2098 update_context.session,
2099 update_context.query,
2100 None,
2101 update_context.result,
2102 ),
2103 )
2104 def after_bulk_update(self, update_context: _O) -> None:
2105 """Event for after the legacy :meth:`_orm.Query.update` method
2106 has been called.
2108 .. legacy:: The :meth:`_orm.SessionEvents.after_bulk_update` method
2109 is a legacy event hook as of SQLAlchemy 2.0. The event
2110 **does not participate** in :term:`2.0 style` invocations
2111 using :func:`_dml.update` documented at
2112 :ref:`orm_queryguide_update_delete_where`. For 2.0 style use,
2113 the :meth:`_orm.SessionEvents.do_orm_execute` hook will intercept
2114 these calls.
2116 :param update_context: an "update context" object which contains
2117 details about the update, including these attributes:
2119 * ``session`` - the :class:`.Session` involved
2120 * ``query`` -the :class:`_query.Query`
2121 object that this update operation
2122 was called upon.
2123 * ``values`` The "values" dictionary that was passed to
2124 :meth:`_query.Query.update`.
2125 * ``result`` the :class:`_engine.CursorResult`
2126 returned as a result of the
2127 bulk UPDATE operation.
2129 .. versionchanged:: 1.4 the update_context no longer has a
2130 ``QueryContext`` object associated with it.
2132 .. seealso::
2134 :meth:`.QueryEvents.before_compile_update`
2136 :meth:`.SessionEvents.after_bulk_delete`
2138 """
2140 @event._legacy_signature(
2141 "0.9",
2142 ["session", "query", "query_context", "result"],
2143 lambda delete_context: (
2144 delete_context.session,
2145 delete_context.query,
2146 None,
2147 delete_context.result,
2148 ),
2149 )
2150 def after_bulk_delete(self, delete_context: _O) -> None:
2151 """Event for after the legacy :meth:`_orm.Query.delete` method
2152 has been called.
2154 .. legacy:: The :meth:`_orm.SessionEvents.after_bulk_delete` method
2155 is a legacy event hook as of SQLAlchemy 2.0. The event
2156 **does not participate** in :term:`2.0 style` invocations
2157 using :func:`_dml.delete` documented at
2158 :ref:`orm_queryguide_update_delete_where`. For 2.0 style use,
2159 the :meth:`_orm.SessionEvents.do_orm_execute` hook will intercept
2160 these calls.
2162 :param delete_context: a "delete context" object which contains
2163 details about the update, including these attributes:
2165 * ``session`` - the :class:`.Session` involved
2166 * ``query`` -the :class:`_query.Query`
2167 object that this update operation
2168 was called upon.
2169 * ``result`` the :class:`_engine.CursorResult`
2170 returned as a result of the
2171 bulk DELETE operation.
2173 .. versionchanged:: 1.4 the update_context no longer has a
2174 ``QueryContext`` object associated with it.
2176 .. seealso::
2178 :meth:`.QueryEvents.before_compile_delete`
2180 :meth:`.SessionEvents.after_bulk_update`
2182 """
2184 @_lifecycle_event
2185 def transient_to_pending(self, session: Session, instance: _O) -> None:
2186 """Intercept the "transient to pending" transition for a specific
2187 object.
2189 This event is a specialization of the
2190 :meth:`.SessionEvents.after_attach` event which is only invoked
2191 for this specific transition. It is invoked typically during the
2192 :meth:`.Session.add` call.
2194 :param session: target :class:`.Session`
2196 :param instance: the ORM-mapped instance being operated upon.
2198 .. seealso::
2200 :ref:`session_lifecycle_events`
2202 """
2204 @_lifecycle_event
2205 def pending_to_transient(self, session: Session, instance: _O) -> None:
2206 """Intercept the "pending to transient" transition for a specific
2207 object.
2209 This less common transition occurs when an pending object that has
2210 not been flushed is evicted from the session; this can occur
2211 when the :meth:`.Session.rollback` method rolls back the transaction,
2212 or when the :meth:`.Session.expunge` method is used.
2214 :param session: target :class:`.Session`
2216 :param instance: the ORM-mapped instance being operated upon.
2218 .. seealso::
2220 :ref:`session_lifecycle_events`
2222 """
2224 @_lifecycle_event
2225 def persistent_to_transient(self, session: Session, instance: _O) -> None:
2226 """Intercept the "persistent to transient" transition for a specific
2227 object.
2229 This less common transition occurs when an pending object that has
2230 has been flushed is evicted from the session; this can occur
2231 when the :meth:`.Session.rollback` method rolls back the transaction.
2233 :param session: target :class:`.Session`
2235 :param instance: the ORM-mapped instance being operated upon.
2237 .. seealso::
2239 :ref:`session_lifecycle_events`
2241 """
2243 @_lifecycle_event
2244 def pending_to_persistent(self, session: Session, instance: _O) -> None:
2245 """Intercept the "pending to persistent"" transition for a specific
2246 object.
2248 This event is invoked within the flush process, and is
2249 similar to scanning the :attr:`.Session.new` collection within
2250 the :meth:`.SessionEvents.after_flush` event. However, in this
2251 case the object has already been moved to the persistent state
2252 when the event is called.
2254 :param session: target :class:`.Session`
2256 :param instance: the ORM-mapped instance being operated upon.
2258 .. seealso::
2260 :ref:`session_lifecycle_events`
2262 """
2264 @_lifecycle_event
2265 def detached_to_persistent(self, session: Session, instance: _O) -> None:
2266 """Intercept the "detached to persistent" transition for a specific
2267 object.
2269 This event is a specialization of the
2270 :meth:`.SessionEvents.after_attach` event which is only invoked
2271 for this specific transition. It is invoked typically during the
2272 :meth:`.Session.add` call, as well as during the
2273 :meth:`.Session.delete` call if the object was not previously
2274 associated with the
2275 :class:`.Session` (note that an object marked as "deleted" remains
2276 in the "persistent" state until the flush proceeds).
2278 .. note::
2280 If the object becomes persistent as part of a call to
2281 :meth:`.Session.delete`, the object is **not** yet marked as
2282 deleted when this event is called. To detect deleted objects,
2283 check the ``deleted`` flag sent to the
2284 :meth:`.SessionEvents.persistent_to_detached` to event after the
2285 flush proceeds, or check the :attr:`.Session.deleted` collection
2286 within the :meth:`.SessionEvents.before_flush` event if deleted
2287 objects need to be intercepted before the flush.
2289 :param session: target :class:`.Session`
2291 :param instance: the ORM-mapped instance being operated upon.
2293 .. seealso::
2295 :ref:`session_lifecycle_events`
2297 """
2299 @_lifecycle_event
2300 def loaded_as_persistent(self, session: Session, instance: _O) -> None:
2301 """Intercept the "loaded as persistent" transition for a specific
2302 object.
2304 This event is invoked within the ORM loading process, and is invoked
2305 very similarly to the :meth:`.InstanceEvents.load` event. However,
2306 the event here is linkable to a :class:`.Session` class or instance,
2307 rather than to a mapper or class hierarchy, and integrates
2308 with the other session lifecycle events smoothly. The object
2309 is guaranteed to be present in the session's identity map when
2310 this event is called.
2312 .. note:: This event is invoked within the loader process before
2313 eager loaders may have been completed, and the object's state may
2314 not be complete. Additionally, invoking row-level refresh
2315 operations on the object will place the object into a new loader
2316 context, interfering with the existing load context. See the note
2317 on :meth:`.InstanceEvents.load` for background on making use of the
2318 :paramref:`.SessionEvents.restore_load_context` parameter, which
2319 works in the same manner as that of
2320 :paramref:`.InstanceEvents.restore_load_context`, in order to
2321 resolve this scenario.
2323 :param session: target :class:`.Session`
2325 :param instance: the ORM-mapped instance being operated upon.
2327 .. seealso::
2329 :ref:`session_lifecycle_events`
2331 """
2333 @_lifecycle_event
2334 def persistent_to_deleted(self, session: Session, instance: _O) -> None:
2335 """Intercept the "persistent to deleted" transition for a specific
2336 object.
2338 This event is invoked when a persistent object's identity
2339 is deleted from the database within a flush, however the object
2340 still remains associated with the :class:`.Session` until the
2341 transaction completes.
2343 If the transaction is rolled back, the object moves again
2344 to the persistent state, and the
2345 :meth:`.SessionEvents.deleted_to_persistent` event is called.
2346 If the transaction is committed, the object becomes detached,
2347 which will emit the :meth:`.SessionEvents.deleted_to_detached`
2348 event.
2350 Note that while the :meth:`.Session.delete` method is the primary
2351 public interface to mark an object as deleted, many objects
2352 get deleted due to cascade rules, which are not always determined
2353 until flush time. Therefore, there's no way to catch
2354 every object that will be deleted until the flush has proceeded.
2355 the :meth:`.SessionEvents.persistent_to_deleted` event is therefore
2356 invoked at the end of a flush.
2358 .. seealso::
2360 :ref:`session_lifecycle_events`
2362 """
2364 @_lifecycle_event
2365 def deleted_to_persistent(self, session: Session, instance: _O) -> None:
2366 """Intercept the "deleted to persistent" transition for a specific
2367 object.
2369 This transition occurs only when an object that's been deleted
2370 successfully in a flush is restored due to a call to
2371 :meth:`.Session.rollback`. The event is not called under
2372 any other circumstances.
2374 .. seealso::
2376 :ref:`session_lifecycle_events`
2378 """
2380 @_lifecycle_event
2381 def deleted_to_detached(self, session: Session, instance: _O) -> None:
2382 """Intercept the "deleted to detached" transition for a specific
2383 object.
2385 This event is invoked when a deleted object is evicted
2386 from the session. The typical case when this occurs is when
2387 the transaction for a :class:`.Session` in which the object
2388 was deleted is committed; the object moves from the deleted
2389 state to the detached state.
2391 It is also invoked for objects that were deleted in a flush
2392 when the :meth:`.Session.expunge_all` or :meth:`.Session.close`
2393 events are called, as well as if the object is individually
2394 expunged from its deleted state via :meth:`.Session.expunge`.
2396 .. seealso::
2398 :ref:`session_lifecycle_events`
2400 """
2402 @_lifecycle_event
2403 def persistent_to_detached(self, session: Session, instance: _O) -> None:
2404 """Intercept the "persistent to detached" transition for a specific
2405 object.
2407 This event is invoked when a persistent object is evicted
2408 from the session. There are many conditions that cause this
2409 to happen, including:
2411 * using a method such as :meth:`.Session.expunge`
2412 or :meth:`.Session.close`
2414 * Calling the :meth:`.Session.rollback` method, when the object
2415 was part of an INSERT statement for that session's transaction
2418 :param session: target :class:`.Session`
2420 :param instance: the ORM-mapped instance being operated upon.
2422 :param deleted: boolean. If True, indicates this object moved
2423 to the detached state because it was marked as deleted and flushed.
2426 .. seealso::
2428 :ref:`session_lifecycle_events`
2430 """
2433class AttributeEvents(event.Events[QueryableAttribute[Any]]):
2434 r"""Define events for object attributes.
2436 These are typically defined on the class-bound descriptor for the
2437 target class.
2439 For example, to register a listener that will receive the
2440 :meth:`_orm.AttributeEvents.append` event::
2442 from sqlalchemy import event
2445 @event.listens_for(MyClass.collection, "append", propagate=True)
2446 def my_append_listener(target, value, initiator):
2447 print("received append event for target: %s" % target)
2449 Listeners have the option to return a possibly modified version of the
2450 value, when the :paramref:`.AttributeEvents.retval` flag is passed to
2451 :func:`.event.listen` or :func:`.event.listens_for`, such as below,
2452 illustrated using the :meth:`_orm.AttributeEvents.set` event::
2454 def validate_phone(target, value, oldvalue, initiator):
2455 "Strip non-numeric characters from a phone number"
2457 return re.sub(r"\D", "", value)
2460 # setup listener on UserContact.phone attribute, instructing
2461 # it to use the return value
2462 listen(UserContact.phone, "set", validate_phone, retval=True)
2464 A validation function like the above can also raise an exception
2465 such as :exc:`ValueError` to halt the operation.
2467 The :paramref:`.AttributeEvents.propagate` flag is also important when
2468 applying listeners to mapped classes that also have mapped subclasses,
2469 as when using mapper inheritance patterns::
2472 @event.listens_for(MySuperClass.attr, "set", propagate=True)
2473 def receive_set(target, value, initiator):
2474 print("value set: %s" % target)
2476 The full list of modifiers available to the :func:`.event.listen`
2477 and :func:`.event.listens_for` functions are below.
2479 :param active_history=False: When True, indicates that the
2480 "set" event would like to receive the "old" value being
2481 replaced unconditionally, even if this requires firing off
2482 database loads. Note that ``active_history`` can also be
2483 set directly via :func:`.column_property` and
2484 :func:`_orm.relationship`.
2486 :param propagate=False: When True, the listener function will
2487 be established not just for the class attribute given, but
2488 for attributes of the same name on all current subclasses
2489 of that class, as well as all future subclasses of that
2490 class, using an additional listener that listens for
2491 instrumentation events.
2492 :param raw=False: When True, the "target" argument to the
2493 event will be the :class:`.InstanceState` management
2494 object, rather than the mapped instance itself.
2495 :param retval=False: when True, the user-defined event
2496 listening must return the "value" argument from the
2497 function. This gives the listening function the opportunity
2498 to change the value that is ultimately used for a "set"
2499 or "append" event.
2501 """
2503 _target_class_doc = "SomeClass.some_attribute"
2504 _dispatch_target = QueryableAttribute
2506 @staticmethod
2507 def _set_dispatch(
2508 cls: Type[_HasEventsDispatch[Any]], dispatch_cls: Type[_Dispatch[Any]]
2509 ) -> _Dispatch[Any]:
2510 dispatch = event.Events._set_dispatch(cls, dispatch_cls)
2511 dispatch_cls._active_history = False
2512 return dispatch
2514 @classmethod
2515 def _accept_with(
2516 cls,
2517 target: Union[QueryableAttribute[Any], Type[QueryableAttribute[Any]]],
2518 identifier: str,
2519 ) -> Union[QueryableAttribute[Any], Type[QueryableAttribute[Any]]]:
2520 # TODO: coverage
2521 if isinstance(target, interfaces.MapperProperty):
2522 return getattr(target.parent.class_, target.key)
2523 else:
2524 return target
2526 @classmethod
2527 def _listen( # type: ignore [override]
2528 cls,
2529 event_key: _EventKey[QueryableAttribute[Any]],
2530 active_history: bool = False,
2531 raw: bool = False,
2532 retval: bool = False,
2533 propagate: bool = False,
2534 include_key: bool = False,
2535 ) -> None:
2536 target, fn = event_key.dispatch_target, event_key._listen_fn
2538 if active_history:
2539 target.dispatch._active_history = True
2541 if not raw or not retval or not include_key:
2543 def wrap(target: InstanceState[_O], *arg: Any, **kw: Any) -> Any:
2544 if not raw:
2545 target = target.obj() # type: ignore [assignment]
2546 if not retval:
2547 if arg:
2548 value = arg[0]
2549 else:
2550 value = None
2551 if include_key:
2552 fn(target, *arg, **kw)
2553 else:
2554 fn(target, *arg)
2555 return value
2556 else:
2557 if include_key:
2558 return fn(target, *arg, **kw)
2559 else:
2560 return fn(target, *arg)
2562 event_key = event_key.with_wrapper(wrap)
2564 event_key.base_listen(propagate=propagate)
2566 if propagate:
2567 manager = instrumentation.manager_of_class(target.class_)
2569 for mgr in manager.subclass_managers(True): # type: ignore [no-untyped-call] # noqa: E501
2570 event_key.with_dispatch_target(mgr[target.key]).base_listen(
2571 propagate=True
2572 )
2573 if active_history:
2574 mgr[target.key].dispatch._active_history = True
2576 def append(
2577 self,
2578 target: _O,
2579 value: _T,
2580 initiator: Event,
2581 *,
2582 key: EventConstants = NO_KEY,
2583 ) -> Optional[_T]:
2584 """Receive a collection append event.
2586 The append event is invoked for each element as it is appended
2587 to the collection. This occurs for single-item appends as well
2588 as for a "bulk replace" operation.
2590 :param target: the object instance receiving the event.
2591 If the listener is registered with ``raw=True``, this will
2592 be the :class:`.InstanceState` object.
2593 :param value: the value being appended. If this listener
2594 is registered with ``retval=True``, the listener
2595 function must return this value, or a new value which
2596 replaces it.
2597 :param initiator: An instance of :class:`.attributes.Event`
2598 representing the initiation of the event. May be modified
2599 from its original value by backref handlers in order to control
2600 chained event propagation, as well as be inspected for information
2601 about the source of the event.
2602 :param key: When the event is established using the
2603 :paramref:`.AttributeEvents.include_key` parameter set to
2604 True, this will be the key used in the operation, such as
2605 ``collection[some_key_or_index] = value``.
2606 The parameter is not passed
2607 to the event at all if the the
2608 :paramref:`.AttributeEvents.include_key`
2609 was not used to set up the event; this is to allow backwards
2610 compatibility with existing event handlers that don't include the
2611 ``key`` parameter.
2613 .. versionadded:: 2.0
2615 :return: if the event was registered with ``retval=True``,
2616 the given value, or a new effective value, should be returned.
2618 .. seealso::
2620 :class:`.AttributeEvents` - background on listener options such
2621 as propagation to subclasses.
2623 :meth:`.AttributeEvents.bulk_replace`
2625 """
2627 def append_wo_mutation(
2628 self,
2629 target: _O,
2630 value: _T,
2631 initiator: Event,
2632 *,
2633 key: EventConstants = NO_KEY,
2634 ) -> None:
2635 """Receive a collection append event where the collection was not
2636 actually mutated.
2638 This event differs from :meth:`_orm.AttributeEvents.append` in that
2639 it is fired off for de-duplicating collections such as sets and
2640 dictionaries, when the object already exists in the target collection.
2641 The event does not have a return value and the identity of the
2642 given object cannot be changed.
2644 The event is used for cascading objects into a :class:`_orm.Session`
2645 when the collection has already been mutated via a backref event.
2647 :param target: the object instance receiving the event.
2648 If the listener is registered with ``raw=True``, this will
2649 be the :class:`.InstanceState` object.
2650 :param value: the value that would be appended if the object did not
2651 already exist in the collection.
2652 :param initiator: An instance of :class:`.attributes.Event`
2653 representing the initiation of the event. May be modified
2654 from its original value by backref handlers in order to control
2655 chained event propagation, as well as be inspected for information
2656 about the source of the event.
2657 :param key: When the event is established using the
2658 :paramref:`.AttributeEvents.include_key` parameter set to
2659 True, this will be the key used in the operation, such as
2660 ``collection[some_key_or_index] = value``.
2661 The parameter is not passed
2662 to the event at all if the the
2663 :paramref:`.AttributeEvents.include_key`
2664 was not used to set up the event; this is to allow backwards
2665 compatibility with existing event handlers that don't include the
2666 ``key`` parameter.
2668 .. versionadded:: 2.0
2670 :return: No return value is defined for this event.
2672 .. versionadded:: 1.4.15
2674 """
2676 def bulk_replace(
2677 self,
2678 target: _O,
2679 values: Iterable[_T],
2680 initiator: Event,
2681 *,
2682 keys: Optional[Iterable[EventConstants]] = None,
2683 ) -> None:
2684 """Receive a collection 'bulk replace' event.
2686 This event is invoked for a sequence of values as they are incoming
2687 to a bulk collection set operation, which can be
2688 modified in place before the values are treated as ORM objects.
2689 This is an "early hook" that runs before the bulk replace routine
2690 attempts to reconcile which objects are already present in the
2691 collection and which are being removed by the net replace operation.
2693 It is typical that this method be combined with use of the
2694 :meth:`.AttributeEvents.append` event. When using both of these
2695 events, note that a bulk replace operation will invoke
2696 the :meth:`.AttributeEvents.append` event for all new items,
2697 even after :meth:`.AttributeEvents.bulk_replace` has been invoked
2698 for the collection as a whole. In order to determine if an
2699 :meth:`.AttributeEvents.append` event is part of a bulk replace,
2700 use the symbol :attr:`~.attributes.OP_BULK_REPLACE` to test the
2701 incoming initiator::
2703 from sqlalchemy.orm.attributes import OP_BULK_REPLACE
2706 @event.listens_for(SomeObject.collection, "bulk_replace")
2707 def process_collection(target, values, initiator):
2708 values[:] = [_make_value(value) for value in values]
2711 @event.listens_for(SomeObject.collection, "append", retval=True)
2712 def process_collection(target, value, initiator):
2713 # make sure bulk_replace didn't already do it
2714 if initiator is None or initiator.op is not OP_BULK_REPLACE:
2715 return _make_value(value)
2716 else:
2717 return value
2719 .. versionadded:: 1.2
2721 :param target: the object instance receiving the event.
2722 If the listener is registered with ``raw=True``, this will
2723 be the :class:`.InstanceState` object.
2724 :param value: a sequence (e.g. a list) of the values being set. The
2725 handler can modify this list in place.
2726 :param initiator: An instance of :class:`.attributes.Event`
2727 representing the initiation of the event.
2728 :param keys: When the event is established using the
2729 :paramref:`.AttributeEvents.include_key` parameter set to
2730 True, this will be the sequence of keys used in the operation,
2731 typically only for a dictionary update. The parameter is not passed
2732 to the event at all if the the
2733 :paramref:`.AttributeEvents.include_key`
2734 was not used to set up the event; this is to allow backwards
2735 compatibility with existing event handlers that don't include the
2736 ``key`` parameter.
2738 .. versionadded:: 2.0
2740 .. seealso::
2742 :class:`.AttributeEvents` - background on listener options such
2743 as propagation to subclasses.
2746 """
2748 def remove(
2749 self,
2750 target: _O,
2751 value: _T,
2752 initiator: Event,
2753 *,
2754 key: EventConstants = NO_KEY,
2755 ) -> None:
2756 """Receive a collection remove event.
2758 :param target: the object instance receiving the event.
2759 If the listener is registered with ``raw=True``, this will
2760 be the :class:`.InstanceState` object.
2761 :param value: the value being removed.
2762 :param initiator: An instance of :class:`.attributes.Event`
2763 representing the initiation of the event. May be modified
2764 from its original value by backref handlers in order to control
2765 chained event propagation.
2767 :param key: When the event is established using the
2768 :paramref:`.AttributeEvents.include_key` parameter set to
2769 True, this will be the key used in the operation, such as
2770 ``del collection[some_key_or_index]``. The parameter is not passed
2771 to the event at all if the the
2772 :paramref:`.AttributeEvents.include_key`
2773 was not used to set up the event; this is to allow backwards
2774 compatibility with existing event handlers that don't include the
2775 ``key`` parameter.
2777 .. versionadded:: 2.0
2779 :return: No return value is defined for this event.
2782 .. seealso::
2784 :class:`.AttributeEvents` - background on listener options such
2785 as propagation to subclasses.
2787 """
2789 def set(
2790 self, target: _O, value: _T, oldvalue: _T, initiator: Event
2791 ) -> None:
2792 """Receive a scalar set event.
2794 :param target: the object instance receiving the event.
2795 If the listener is registered with ``raw=True``, this will
2796 be the :class:`.InstanceState` object.
2797 :param value: the value being set. If this listener
2798 is registered with ``retval=True``, the listener
2799 function must return this value, or a new value which
2800 replaces it.
2801 :param oldvalue: the previous value being replaced. This
2802 may also be the symbol ``NEVER_SET`` or ``NO_VALUE``.
2803 If the listener is registered with ``active_history=True``,
2804 the previous value of the attribute will be loaded from
2805 the database if the existing value is currently unloaded
2806 or expired.
2807 :param initiator: An instance of :class:`.attributes.Event`
2808 representing the initiation of the event. May be modified
2809 from its original value by backref handlers in order to control
2810 chained event propagation.
2812 :return: if the event was registered with ``retval=True``,
2813 the given value, or a new effective value, should be returned.
2815 .. seealso::
2817 :class:`.AttributeEvents` - background on listener options such
2818 as propagation to subclasses.
2820 """
2822 def init_scalar(
2823 self, target: _O, value: _T, dict_: Dict[Any, Any]
2824 ) -> None:
2825 r"""Receive a scalar "init" event.
2827 This event is invoked when an uninitialized, unpersisted scalar
2828 attribute is accessed, e.g. read::
2831 x = my_object.some_attribute
2833 The ORM's default behavior when this occurs for an un-initialized
2834 attribute is to return the value ``None``; note this differs from
2835 Python's usual behavior of raising ``AttributeError``. The
2836 event here can be used to customize what value is actually returned,
2837 with the assumption that the event listener would be mirroring
2838 a default generator that is configured on the Core
2839 :class:`_schema.Column`
2840 object as well.
2842 Since a default generator on a :class:`_schema.Column`
2843 might also produce
2844 a changing value such as a timestamp, the
2845 :meth:`.AttributeEvents.init_scalar`
2846 event handler can also be used to **set** the newly returned value, so
2847 that a Core-level default generation function effectively fires off
2848 only once, but at the moment the attribute is accessed on the
2849 non-persisted object. Normally, no change to the object's state
2850 is made when an uninitialized attribute is accessed (much older
2851 SQLAlchemy versions did in fact change the object's state).
2853 If a default generator on a column returned a particular constant,
2854 a handler might be used as follows::
2856 SOME_CONSTANT = 3.1415926
2859 class MyClass(Base):
2860 # ...
2862 some_attribute = Column(Numeric, default=SOME_CONSTANT)
2865 @event.listens_for(
2866 MyClass.some_attribute, "init_scalar", retval=True, propagate=True
2867 )
2868 def _init_some_attribute(target, dict_, value):
2869 dict_["some_attribute"] = SOME_CONSTANT
2870 return SOME_CONSTANT
2872 Above, we initialize the attribute ``MyClass.some_attribute`` to the
2873 value of ``SOME_CONSTANT``. The above code includes the following
2874 features:
2876 * By setting the value ``SOME_CONSTANT`` in the given ``dict_``,
2877 we indicate that this value is to be persisted to the database.
2878 This supersedes the use of ``SOME_CONSTANT`` in the default generator
2879 for the :class:`_schema.Column`. The ``active_column_defaults.py``
2880 example given at :ref:`examples_instrumentation` illustrates using
2881 the same approach for a changing default, e.g. a timestamp
2882 generator. In this particular example, it is not strictly
2883 necessary to do this since ``SOME_CONSTANT`` would be part of the
2884 INSERT statement in either case.
2886 * By establishing the ``retval=True`` flag, the value we return
2887 from the function will be returned by the attribute getter.
2888 Without this flag, the event is assumed to be a passive observer
2889 and the return value of our function is ignored.
2891 * The ``propagate=True`` flag is significant if the mapped class
2892 includes inheriting subclasses, which would also make use of this
2893 event listener. Without this flag, an inheriting subclass will
2894 not use our event handler.
2896 In the above example, the attribute set event
2897 :meth:`.AttributeEvents.set` as well as the related validation feature
2898 provided by :obj:`_orm.validates` is **not** invoked when we apply our
2899 value to the given ``dict_``. To have these events to invoke in
2900 response to our newly generated value, apply the value to the given
2901 object as a normal attribute set operation::
2903 SOME_CONSTANT = 3.1415926
2906 @event.listens_for(
2907 MyClass.some_attribute, "init_scalar", retval=True, propagate=True
2908 )
2909 def _init_some_attribute(target, dict_, value):
2910 # will also fire off attribute set events
2911 target.some_attribute = SOME_CONSTANT
2912 return SOME_CONSTANT
2914 When multiple listeners are set up, the generation of the value
2915 is "chained" from one listener to the next by passing the value
2916 returned by the previous listener that specifies ``retval=True``
2917 as the ``value`` argument of the next listener.
2919 :param target: the object instance receiving the event.
2920 If the listener is registered with ``raw=True``, this will
2921 be the :class:`.InstanceState` object.
2922 :param value: the value that is to be returned before this event
2923 listener were invoked. This value begins as the value ``None``,
2924 however will be the return value of the previous event handler
2925 function if multiple listeners are present.
2926 :param dict\_: the attribute dictionary of this mapped object.
2927 This is normally the ``__dict__`` of the object, but in all cases
2928 represents the destination that the attribute system uses to get
2929 at the actual value of this attribute. Placing the value in this
2930 dictionary has the effect that the value will be used in the
2931 INSERT statement generated by the unit of work.
2934 .. seealso::
2936 :meth:`.AttributeEvents.init_collection` - collection version
2937 of this event
2939 :class:`.AttributeEvents` - background on listener options such
2940 as propagation to subclasses.
2942 :ref:`examples_instrumentation` - see the
2943 ``active_column_defaults.py`` example.
2945 """ # noqa: E501
2947 def init_collection(
2948 self,
2949 target: _O,
2950 collection: Type[Collection[Any]],
2951 collection_adapter: CollectionAdapter,
2952 ) -> None:
2953 """Receive a 'collection init' event.
2955 This event is triggered for a collection-based attribute, when
2956 the initial "empty collection" is first generated for a blank
2957 attribute, as well as for when the collection is replaced with
2958 a new one, such as via a set event.
2960 E.g., given that ``User.addresses`` is a relationship-based
2961 collection, the event is triggered here::
2963 u1 = User()
2964 u1.addresses.append(a1) # <- new collection
2966 and also during replace operations::
2968 u1.addresses = [a2, a3] # <- new collection
2970 :param target: the object instance receiving the event.
2971 If the listener is registered with ``raw=True``, this will
2972 be the :class:`.InstanceState` object.
2973 :param collection: the new collection. This will always be generated
2974 from what was specified as
2975 :paramref:`_orm.relationship.collection_class`, and will always
2976 be empty.
2977 :param collection_adapter: the :class:`.CollectionAdapter` that will
2978 mediate internal access to the collection.
2980 .. seealso::
2982 :class:`.AttributeEvents` - background on listener options such
2983 as propagation to subclasses.
2985 :meth:`.AttributeEvents.init_scalar` - "scalar" version of this
2986 event.
2988 """
2990 def dispose_collection(
2991 self,
2992 target: _O,
2993 collection: Collection[Any],
2994 collection_adapter: CollectionAdapter,
2995 ) -> None:
2996 """Receive a 'collection dispose' event.
2998 This event is triggered for a collection-based attribute when
2999 a collection is replaced, that is::
3001 u1.addresses.append(a1)
3003 u1.addresses = [a2, a3] # <- old collection is disposed
3005 The old collection received will contain its previous contents.
3007 .. versionchanged:: 1.2 The collection passed to
3008 :meth:`.AttributeEvents.dispose_collection` will now have its
3009 contents before the dispose intact; previously, the collection
3010 would be empty.
3012 .. seealso::
3014 :class:`.AttributeEvents` - background on listener options such
3015 as propagation to subclasses.
3017 """
3019 def modified(self, target: _O, initiator: Event) -> None:
3020 """Receive a 'modified' event.
3022 This event is triggered when the :func:`.attributes.flag_modified`
3023 function is used to trigger a modify event on an attribute without
3024 any specific value being set.
3026 .. versionadded:: 1.2
3028 :param target: the object instance receiving the event.
3029 If the listener is registered with ``raw=True``, this will
3030 be the :class:`.InstanceState` object.
3032 :param initiator: An instance of :class:`.attributes.Event`
3033 representing the initiation of the event.
3035 .. seealso::
3037 :class:`.AttributeEvents` - background on listener options such
3038 as propagation to subclasses.
3040 """
3043class QueryEvents(event.Events[Query[Any]]):
3044 """Represent events within the construction of a :class:`_query.Query`
3045 object.
3047 .. legacy:: The :class:`_orm.QueryEvents` event methods are legacy
3048 as of SQLAlchemy 2.0, and only apply to direct use of the
3049 :class:`_orm.Query` object. They are not used for :term:`2.0 style`
3050 statements. For events to intercept and modify 2.0 style ORM use,
3051 use the :meth:`_orm.SessionEvents.do_orm_execute` hook.
3054 The :class:`_orm.QueryEvents` hooks are now superseded by the
3055 :meth:`_orm.SessionEvents.do_orm_execute` event hook.
3057 """
3059 _target_class_doc = "SomeQuery"
3060 _dispatch_target = Query
3062 def before_compile(self, query: Query[Any]) -> None:
3063 """Receive the :class:`_query.Query`
3064 object before it is composed into a
3065 core :class:`_expression.Select` object.
3067 .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile` event
3068 is superseded by the much more capable
3069 :meth:`_orm.SessionEvents.do_orm_execute` hook. In version 1.4,
3070 the :meth:`_orm.QueryEvents.before_compile` event is **no longer
3071 used** for ORM-level attribute loads, such as loads of deferred
3072 or expired attributes as well as relationship loaders. See the
3073 new examples in :ref:`examples_session_orm_events` which
3074 illustrate new ways of intercepting and modifying ORM queries
3075 for the most common purpose of adding arbitrary filter criteria.
3078 This event is intended to allow changes to the query given::
3080 @event.listens_for(Query, "before_compile", retval=True)
3081 def no_deleted(query):
3082 for desc in query.column_descriptions:
3083 if desc["type"] is User:
3084 entity = desc["entity"]
3085 query = query.filter(entity.deleted == False)
3086 return query
3088 The event should normally be listened with the ``retval=True``
3089 parameter set, so that the modified query may be returned.
3091 The :meth:`.QueryEvents.before_compile` event by default
3092 will disallow "baked" queries from caching a query, if the event
3093 hook returns a new :class:`_query.Query` object.
3094 This affects both direct
3095 use of the baked query extension as well as its operation within
3096 lazy loaders and eager loaders for relationships. In order to
3097 re-establish the query being cached, apply the event adding the
3098 ``bake_ok`` flag::
3100 @event.listens_for(Query, "before_compile", retval=True, bake_ok=True)
3101 def my_event(query):
3102 for desc in query.column_descriptions:
3103 if desc["type"] is User:
3104 entity = desc["entity"]
3105 query = query.filter(entity.deleted == False)
3106 return query
3108 When ``bake_ok`` is set to True, the event hook will only be invoked
3109 once, and not called for subsequent invocations of a particular query
3110 that is being cached.
3112 .. versionadded:: 1.3.11 - added the "bake_ok" flag to the
3113 :meth:`.QueryEvents.before_compile` event and disallowed caching via
3114 the "baked" extension from occurring for event handlers that
3115 return a new :class:`_query.Query` object if this flag is not set.
3117 .. seealso::
3119 :meth:`.QueryEvents.before_compile_update`
3121 :meth:`.QueryEvents.before_compile_delete`
3123 :ref:`baked_with_before_compile`
3125 """ # noqa: E501
3127 def before_compile_update(
3128 self, query: Query[Any], update_context: BulkUpdate
3129 ) -> None:
3130 """Allow modifications to the :class:`_query.Query` object within
3131 :meth:`_query.Query.update`.
3133 .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_update`
3134 event is superseded by the much more capable
3135 :meth:`_orm.SessionEvents.do_orm_execute` hook.
3137 Like the :meth:`.QueryEvents.before_compile` event, if the event
3138 is to be used to alter the :class:`_query.Query` object, it should
3139 be configured with ``retval=True``, and the modified
3140 :class:`_query.Query` object returned, as in ::
3142 @event.listens_for(Query, "before_compile_update", retval=True)
3143 def no_deleted(query, update_context):
3144 for desc in query.column_descriptions:
3145 if desc["type"] is User:
3146 entity = desc["entity"]
3147 query = query.filter(entity.deleted == False)
3149 update_context.values["timestamp"] = datetime.datetime.now(
3150 datetime.UTC
3151 )
3152 return query
3154 The ``.values`` dictionary of the "update context" object can also
3155 be modified in place as illustrated above.
3157 :param query: a :class:`_query.Query` instance; this is also
3158 the ``.query`` attribute of the given "update context"
3159 object.
3161 :param update_context: an "update context" object which is
3162 the same kind of object as described in
3163 :paramref:`.QueryEvents.after_bulk_update.update_context`.
3164 The object has a ``.values`` attribute in an UPDATE context which is
3165 the dictionary of parameters passed to :meth:`_query.Query.update`.
3166 This
3167 dictionary can be modified to alter the VALUES clause of the
3168 resulting UPDATE statement.
3170 .. versionadded:: 1.2.17
3172 .. seealso::
3174 :meth:`.QueryEvents.before_compile`
3176 :meth:`.QueryEvents.before_compile_delete`
3179 """ # noqa: E501
3181 def before_compile_delete(
3182 self, query: Query[Any], delete_context: BulkDelete
3183 ) -> None:
3184 """Allow modifications to the :class:`_query.Query` object within
3185 :meth:`_query.Query.delete`.
3187 .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_delete`
3188 event is superseded by the much more capable
3189 :meth:`_orm.SessionEvents.do_orm_execute` hook.
3191 Like the :meth:`.QueryEvents.before_compile` event, this event
3192 should be configured with ``retval=True``, and the modified
3193 :class:`_query.Query` object returned, as in ::
3195 @event.listens_for(Query, "before_compile_delete", retval=True)
3196 def no_deleted(query, delete_context):
3197 for desc in query.column_descriptions:
3198 if desc["type"] is User:
3199 entity = desc["entity"]
3200 query = query.filter(entity.deleted == False)
3201 return query
3203 :param query: a :class:`_query.Query` instance; this is also
3204 the ``.query`` attribute of the given "delete context"
3205 object.
3207 :param delete_context: a "delete context" object which is
3208 the same kind of object as described in
3209 :paramref:`.QueryEvents.after_bulk_delete.delete_context`.
3211 .. versionadded:: 1.2.17
3213 .. seealso::
3215 :meth:`.QueryEvents.before_compile`
3217 :meth:`.QueryEvents.before_compile_update`
3220 """
3222 @classmethod
3223 def _listen(
3224 cls,
3225 event_key: _EventKey[_ET],
3226 retval: bool = False,
3227 bake_ok: bool = False,
3228 **kw: Any,
3229 ) -> None:
3230 fn = event_key._listen_fn
3232 if not retval:
3234 def wrap(*arg: Any, **kw: Any) -> Any:
3235 if not retval:
3236 query = arg[0]
3237 fn(*arg, **kw)
3238 return query
3239 else:
3240 return fn(*arg, **kw)
3242 event_key = event_key.with_wrapper(wrap)
3243 else:
3244 # don't assume we can apply an attribute to the callable
3245 def wrap(*arg: Any, **kw: Any) -> Any:
3246 return fn(*arg, **kw)
3248 event_key = event_key.with_wrapper(wrap)
3250 wrap._bake_ok = bake_ok # type: ignore [attr-defined]
3252 event_key.base_listen(**kw)