provided via the :func:`.event.remove` function.
[ticket:2268]
- reorganization of event.py module into a package; with the addition of the
docstring work as well as the new registry for removal, there's a lot more code now.
the package separates concerns and provides a top-level doc for each subsection
of functionality
- the remove feature works by providing the EventKey object which associates
the user-provided arguments to listen() with a global, weak-referencing registry.
This registry stores a collection of _ListenerCollection and _DispatchDescriptor
objects associated with each set of arguments, as well as the wrapped function
which was applied to that collection. The EventKey can then be recreated for
a removal, all the _ListenerCollection and _DispatchDescriptor objects are located,
and the correct wrapped function is removed from each one.
.. changelog::
:version: 0.9.0
+ .. change::
+ :tags: feature, orm
+ :tickets: 2268
+
+ Removal of event listeners is now implemented. The feature is
+ provided via the :func:`.event.remove` function.
+
+ .. seealso::
+
+ :ref:`feature_2268`
+
.. change::
:tags: feature, examples
New Features
============
+.. _feature_2268:
+
+Event Removal API
+-----------------
+
+Events established using :func:`.event.listen` or :func:`.event.listens_for`
+can now be removed using the new :func:`.event.remove` function. The ``target``,
+``identifier`` and ``fn`` arguments sent to :func:`.event.remove` need to match
+exactly those which were sent for listening, and the event will be removed
+from all locations in which it had been established::
+
+ @event.listens_for(MyClass, "before_insert", propagate=True)
+ def my_before_insert(mapper, connection, target):
+ """listen for before_insert"""
+ # ...
+
+ event.remove(MyClass, "before_insert", my_before_insert)
+
+In the example above, the ``propagate=True`` flag is set. This
+means ``my_before_insert()`` is established as a listener for ``MyClass``
+as well as all subclasses of ``MyClass``.
+The system tracks everywhere that the ``my_before_insert()``
+listener function had been placed as a result of this call and removes it as
+a result of calling :func:`.event.remove`.
+
+The removal system uses a registry to associate arguments passed to
+:func:`.event.listen` with collections of event listeners, which are in many
+cases wrapped versions of the original user-supplied function. This registry
+makes heavy use of weak references in order to allow all the contained contents,
+such as listener targets, to be garbage collected when they go out of scope.
+
+:ticket:`2268`
+
+
.. _feature_722:
INSERT from SELECT
.. autofunction:: sqlalchemy.event.listens_for
+.. autofunction:: sqlalchemy.event.remove
+
+++ /dev/null
-# sqlalchemy/event.py
-# Copyright (C) 2005-2013 the SQLAlchemy authors and contributors <see AUTHORS file>
-#
-# This module is part of SQLAlchemy and is released under
-# the MIT License: http://www.opensource.org/licenses/mit-license.php
-
-"""Base event API."""
-
-from __future__ import absolute_import
-
-from . import util, exc
-from itertools import chain
-import weakref
-
-CANCEL = util.symbol('CANCEL')
-NO_RETVAL = util.symbol('NO_RETVAL')
-
-
-def listen(target, identifier, fn, *args, **kw):
- """Register a listener function for the given target.
-
- e.g.::
-
- from sqlalchemy import event
- from sqlalchemy.schema import UniqueConstraint
-
- def unique_constraint_name(const, table):
- const.name = "uq_%s_%s" % (
- table.name,
- list(const.columns)[0].name
- )
- event.listen(
- UniqueConstraint,
- "after_parent_attach",
- unique_constraint_name)
-
- """
-
- for evt_cls in _registrars[identifier]:
- tgt = evt_cls._accept_with(target)
- if tgt is not None:
- tgt.dispatch._listen(tgt, identifier, fn, *args, **kw)
- return
- raise exc.InvalidRequestError("No such event '%s' for target '%s'" %
- (identifier, target))
-
-
-def listens_for(target, identifier, *args, **kw):
- """Decorate a function as a listener for the given target + identifier.
-
- e.g.::
-
- from sqlalchemy import event
- from sqlalchemy.schema import UniqueConstraint
-
- @event.listens_for(UniqueConstraint, "after_parent_attach")
- def unique_constraint_name(const, table):
- const.name = "uq_%s_%s" % (
- table.name,
- list(const.columns)[0].name
- )
- """
- def decorate(fn):
- listen(target, identifier, fn, *args, **kw)
- return fn
- return decorate
-
-
-def remove(target, identifier, fn):
- """Remove an event listener.
-
- Note that some event removals, particularly for those event dispatchers
- which create wrapper functions and secondary even listeners, may not yet
- be supported.
-
- """
- for evt_cls in _registrars[identifier]:
- for tgt in evt_cls._accept_with(target):
- tgt.dispatch._remove(identifier, tgt, fn)
- return
-
-def _legacy_signature(since, argnames, converter=None):
- def leg(fn):
- if not hasattr(fn, '_legacy_signatures'):
- fn._legacy_signatures = []
- fn._legacy_signatures.append((since, argnames, converter))
- return fn
- return leg
-
-
-_registrars = util.defaultdict(list)
-
-
-def _is_event_name(name):
- return not name.startswith('_') and name != 'dispatch'
-
-
-class _UnpickleDispatch(object):
- """Serializable callable that re-generates an instance of
- :class:`_Dispatch` given a particular :class:`.Events` subclass.
-
- """
- def __call__(self, _parent_cls):
- for cls in _parent_cls.__mro__:
- if 'dispatch' in cls.__dict__:
- return cls.__dict__['dispatch'].dispatch_cls(_parent_cls)
- else:
- raise AttributeError("No class with a 'dispatch' member present.")
-
-
-class _Dispatch(object):
- """Mirror the event listening definitions of an Events class with
- listener collections.
-
- Classes which define a "dispatch" member will return a
- non-instantiated :class:`._Dispatch` subclass when the member
- is accessed at the class level. When the "dispatch" member is
- accessed at the instance level of its owner, an instance
- of the :class:`._Dispatch` class is returned.
-
- A :class:`._Dispatch` class is generated for each :class:`.Events`
- class defined, by the :func:`._create_dispatcher_class` function.
- The original :class:`.Events` classes remain untouched.
- This decouples the construction of :class:`.Events` subclasses from
- the implementation used by the event internals, and allows
- inspecting tools like Sphinx to work in an unsurprising
- way against the public API.
-
- """
-
- def __init__(self, _parent_cls):
- self._parent_cls = _parent_cls
-
- def _join(self, other):
- """Create a 'join' of this :class:`._Dispatch` and another.
-
- This new dispatcher will dispatch events to both
- :class:`._Dispatch` objects.
-
- Once constructed, the joined dispatch will respond to new events
- added to this dispatcher, but may not be aware of events
- added to the other dispatcher after creation of the join. This is
- currently for performance reasons so that both dispatchers need
- not be "evaluated" fully on each call.
-
- """
- if '_joined_dispatch_cls' not in self.__class__.__dict__:
- cls = type(
- "Joined%s" % self.__class__.__name__,
- (_JoinedDispatcher, self.__class__), {}
- )
- for ls in _event_descriptors(self):
- setattr(cls, ls.name, _JoinedDispatchDescriptor(ls.name))
-
- self.__class__._joined_dispatch_cls = cls
- return self._joined_dispatch_cls(self, other)
-
- def __reduce__(self):
- return _UnpickleDispatch(), (self._parent_cls, )
-
- def _update(self, other, only_propagate=True):
- """Populate from the listeners in another :class:`_Dispatch`
- object."""
-
- for ls in _event_descriptors(other):
- getattr(self, ls.name).\
- for_modify(self)._update(ls, only_propagate=only_propagate)
-
- @util.hybridmethod
- def _clear(self):
- for attr in dir(self):
- if _is_event_name(attr):
- getattr(self, attr).for_modify(self).clear()
-
-
-def _event_descriptors(target):
- return [getattr(target, k) for k in dir(target) if _is_event_name(k)]
-
-
-class _EventMeta(type):
- """Intercept new Event subclasses and create
- associated _Dispatch classes."""
-
- def __init__(cls, classname, bases, dict_):
- _create_dispatcher_class(cls, classname, bases, dict_)
- return type.__init__(cls, classname, bases, dict_)
-
-
-def _create_dispatcher_class(cls, classname, bases, dict_):
- """Create a :class:`._Dispatch` class corresponding to an
- :class:`.Events` class."""
-
- # there's all kinds of ways to do this,
- # i.e. make a Dispatch class that shares the '_listen' method
- # of the Event class, this is the straight monkeypatch.
- dispatch_base = getattr(cls, 'dispatch', _Dispatch)
- cls.dispatch = dispatch_cls = type("%sDispatch" % classname,
- (dispatch_base, ), {})
- dispatch_cls._listen = cls._listen
-
- for k in dict_:
- if _is_event_name(k):
- setattr(dispatch_cls, k, _DispatchDescriptor(cls, dict_[k]))
- _registrars[k].append(cls)
-
-
-def _remove_dispatcher(cls):
- for k in dir(cls):
- if _is_event_name(k):
- _registrars[k].remove(cls)
- if not _registrars[k]:
- del _registrars[k]
-
-class Events(util.with_metaclass(_EventMeta, object)):
- """Define event listening functions for a particular target type."""
-
- @classmethod
- def _accept_with(cls, target):
- # Mapper, ClassManager, Session override this to
- # also accept classes, scoped_sessions, sessionmakers, etc.
- if hasattr(target, 'dispatch') and (
- isinstance(target.dispatch, cls.dispatch) or \
- isinstance(target.dispatch, type) and \
- issubclass(target.dispatch, cls.dispatch)
- ):
- return target
- else:
- return None
-
- @classmethod
- def _listen(cls, target, identifier, fn, propagate=False, insert=False,
- named=False):
- dispatch_descriptor = getattr(target.dispatch, identifier)
- fn = dispatch_descriptor._adjust_fn_spec(fn, named)
-
- if insert:
- dispatch_descriptor.\
- for_modify(target.dispatch).insert(fn, target, propagate)
- else:
- dispatch_descriptor.\
- for_modify(target.dispatch).append(fn, target, propagate)
-
- @classmethod
- def _remove(cls, target, identifier, fn):
- getattr(target.dispatch, identifier).remove(fn, target)
-
- @classmethod
- def _clear(cls):
- cls.dispatch._clear()
-
-
-class _DispatchDescriptor(object):
- """Class-level attributes on :class:`._Dispatch` classes."""
-
- def __init__(self, parent_dispatch_cls, fn):
- self.__name__ = fn.__name__
- argspec = util.inspect_getargspec(fn)
- self.arg_names = argspec.args[1:]
- self.has_kw = bool(argspec.keywords)
- self.legacy_signatures = list(reversed(
- sorted(
- getattr(fn, '_legacy_signatures', []),
- key=lambda s: s[0]
- )
- ))
- self.__doc__ = fn.__doc__ = self._augment_fn_docs(parent_dispatch_cls, fn)
-
- self._clslevel = weakref.WeakKeyDictionary()
- self._empty_listeners = weakref.WeakKeyDictionary()
-
- def _adjust_fn_spec(self, fn, named):
- argspec = util.get_callable_argspec(fn, no_self=True)
- if named:
- fn = self._wrap_fn_for_kw(fn)
- fn = self._wrap_fn_for_legacy(fn, argspec)
- return fn
-
- def _wrap_fn_for_kw(self, fn):
- def wrap_kw(*args, **kw):
- argdict = dict(zip(self.arg_names, args))
- argdict.update(kw)
- return fn(**argdict)
- return wrap_kw
-
- def _wrap_fn_for_legacy(self, fn, argspec):
- for since, argnames, conv in self.legacy_signatures:
- if argnames[-1] == "**kw":
- has_kw = True
- argnames = argnames[0:-1]
- else:
- has_kw = False
-
- if len(argnames) == len(argspec.args) \
- and has_kw is bool(argspec.keywords):
-
- if conv:
- assert not has_kw
- def wrap_leg(*args):
- return fn(*conv(*args))
- else:
- def wrap_leg(*args, **kw):
- argdict = dict(zip(self.arg_names, args))
- args = [argdict[name] for name in argnames]
- if has_kw:
- return fn(*args, **kw)
- else:
- return fn(*args)
- return wrap_leg
- else:
- return fn
-
- def _indent(self, text, indent):
- return "\n".join(
- indent + line
- for line in text.split("\n")
- )
-
- def _standard_listen_example(self, sample_target, fn):
- example_kw_arg = self._indent(
- "\n".join(
- "%(arg)s = kw['%(arg)s']" % {"arg": arg}
- for arg in self.arg_names[0:2]
- ),
- " ")
- if self.legacy_signatures:
- current_since = max(since for since, args, conv in self.legacy_signatures)
- else:
- current_since = None
- text = (
- "from sqlalchemy import event\n\n"
- "# standard decorator style%(current_since)s\n"
- "@event.listens_for(%(sample_target)s, '%(event_name)s')\n"
- "def receive_%(event_name)s(%(named_event_arguments)s%(has_kw_arguments)s):\n"
- " \"listen for the '%(event_name)s' event\"\n"
- "\n # ... (event handling logic) ...\n"
- )
-
- if len(self.arg_names) > 2:
- text += (
-
- "\n# named argument style (new in 0.9)\n"
- "@event.listens_for(%(sample_target)s, '%(event_name)s', named=True)\n"
- "def receive_%(event_name)s(**kw):\n"
- " \"listen for the '%(event_name)s' event\"\n"
- "%(example_kw_arg)s\n"
- "\n # ... (event handling logic) ...\n"
- )
-
- text %= {
- "current_since": " (arguments as of %s)" %
- current_since if current_since else "",
- "event_name": fn.__name__,
- "has_kw_arguments": " **kw" if self.has_kw else "",
- "named_event_arguments": ", ".join(self.arg_names),
- "example_kw_arg": example_kw_arg,
- "sample_target": sample_target
- }
- return text
-
- def _legacy_listen_examples(self, sample_target, fn):
- text = ""
- for since, args, conv in self.legacy_signatures:
- text += (
- "\n# legacy calling style (pre-%(since)s)\n"
- "@event.listens_for(%(sample_target)s, '%(event_name)s')\n"
- "def receive_%(event_name)s(%(named_event_arguments)s%(has_kw_arguments)s):\n"
- " \"listen for the '%(event_name)s' event\"\n"
- "\n # ... (event handling logic) ...\n" % {
- "since": since,
- "event_name": fn.__name__,
- "has_kw_arguments": " **kw" if self.has_kw else "",
- "named_event_arguments": ", ".join(args),
- "sample_target": sample_target
- }
- )
- return text
-
- def _version_signature_changes(self):
- since, args, conv = self.legacy_signatures[0]
- return (
- "\n.. versionchanged:: %(since)s\n"
- " The ``%(event_name)s`` event now accepts the \n"
- " arguments ``%(named_event_arguments)s%(has_kw_arguments)s``.\n"
- " Listener functions which accept the previous argument \n"
- " signature(s) listed above will be automatically \n"
- " adapted to the new signature." % {
- "since": since,
- "event_name": self.__name__,
- "named_event_arguments": ", ".join(self.arg_names),
- "has_kw_arguments": ", **kw" if self.has_kw else ""
- }
- )
-
- def _augment_fn_docs(self, parent_dispatch_cls, fn):
- header = ".. container:: event_signatures\n\n"\
- " Example argument forms::\n"\
- "\n"
-
- sample_target = getattr(parent_dispatch_cls, "_target_class_doc", "obj")
- text = (
- header +
- self._indent(
- self._standard_listen_example(sample_target, fn),
- " " * 8)
- )
- if self.legacy_signatures:
- text += self._indent(
- self._legacy_listen_examples(sample_target, fn),
- " " * 8)
-
- text += self._version_signature_changes()
-
- return util.inject_docstring_text(fn.__doc__,
- text,
- 1
- )
-
- def _contains(self, cls, evt):
- return cls in self._clslevel and \
- evt in self._clslevel[cls]
-
- def insert(self, obj, target, propagate):
- assert isinstance(target, type), \
- "Class-level Event targets must be classes."
- stack = [target]
- while stack:
- cls = stack.pop(0)
- stack.extend(cls.__subclasses__())
- if cls is not target and cls not in self._clslevel:
- self.update_subclass(cls)
- else:
- if cls not in self._clslevel:
- self._clslevel[cls] = []
- self._clslevel[cls].insert(0, obj)
-
- def append(self, obj, target, propagate):
- assert isinstance(target, type), \
- "Class-level Event targets must be classes."
-
- stack = [target]
- while stack:
- cls = stack.pop(0)
- stack.extend(cls.__subclasses__())
- if cls is not target and cls not in self._clslevel:
- self.update_subclass(cls)
- else:
- if cls not in self._clslevel:
- self._clslevel[cls] = []
- self._clslevel[cls].append(obj)
-
- def update_subclass(self, target):
- if target not in self._clslevel:
- self._clslevel[target] = []
- clslevel = self._clslevel[target]
- for cls in target.__mro__[1:]:
- if cls in self._clslevel:
- clslevel.extend([
- fn for fn
- in self._clslevel[cls]
- if fn not in clslevel
- ])
-
- def remove(self, obj, target):
- stack = [target]
- while stack:
- cls = stack.pop(0)
- stack.extend(cls.__subclasses__())
- if cls in self._clslevel:
- self._clslevel[cls].remove(obj)
-
- def clear(self):
- """Clear all class level listeners"""
-
- for dispatcher in self._clslevel.values():
- dispatcher[:] = []
-
- def for_modify(self, obj):
- """Return an event collection which can be modified.
-
- For _DispatchDescriptor at the class level of
- a dispatcher, this returns self.
-
- """
- return self
-
- def __get__(self, obj, cls):
- if obj is None:
- return self
- elif obj._parent_cls in self._empty_listeners:
- ret = self._empty_listeners[obj._parent_cls]
- else:
- self._empty_listeners[obj._parent_cls] = ret = \
- _EmptyListener(self, obj._parent_cls)
- # assigning it to __dict__ means
- # memoized for fast re-access. but more memory.
- obj.__dict__[self.__name__] = ret
- return ret
-
-class _HasParentDispatchDescriptor(object):
- def _adjust_fn_spec(self, fn, named):
- return self.parent._adjust_fn_spec(fn, named)
-
-class _EmptyListener(_HasParentDispatchDescriptor):
- """Serves as a class-level interface to the events
- served by a _DispatchDescriptor, when there are no
- instance-level events present.
-
- Is replaced by _ListenerCollection when instance-level
- events are added.
-
- """
- def __init__(self, parent, target_cls):
- if target_cls not in parent._clslevel:
- parent.update_subclass(target_cls)
- self.parent = parent # _DispatchDescriptor
- self.parent_listeners = parent._clslevel[target_cls]
- self.name = parent.__name__
- self.propagate = frozenset()
- self.listeners = ()
-
-
- def for_modify(self, obj):
- """Return an event collection which can be modified.
-
- For _EmptyListener at the instance level of
- a dispatcher, this generates a new
- _ListenerCollection, applies it to the instance,
- and returns it.
-
- """
- result = _ListenerCollection(self.parent, obj._parent_cls)
- if obj.__dict__[self.name] is self:
- obj.__dict__[self.name] = result
- return result
-
- def _needs_modify(self, *args, **kw):
- raise NotImplementedError("need to call for_modify()")
-
- exec_once = insert = append = remove = clear = _needs_modify
-
- def __call__(self, *args, **kw):
- """Execute this event."""
-
- for fn in self.parent_listeners:
- fn(*args, **kw)
-
- def __len__(self):
- return len(self.parent_listeners)
-
- def __iter__(self):
- return iter(self.parent_listeners)
-
- def __bool__(self):
- return bool(self.parent_listeners)
-
- __nonzero__ = __bool__
-
-
-class _CompoundListener(_HasParentDispatchDescriptor):
- _exec_once = False
-
- def exec_once(self, *args, **kw):
- """Execute this event, but only if it has not been
- executed already for this collection."""
-
- if not self._exec_once:
- self(*args, **kw)
- self._exec_once = True
-
- # I'm not entirely thrilled about the overhead here,
- # but this allows class-level listeners to be added
- # at any point.
- #
- # In the absense of instance-level listeners,
- # we stay with the _EmptyListener object when called
- # at the instance level.
-
- def __call__(self, *args, **kw):
- """Execute this event."""
-
- for fn in self.parent_listeners:
- fn(*args, **kw)
- for fn in self.listeners:
- fn(*args, **kw)
-
- def __len__(self):
- return len(self.parent_listeners) + len(self.listeners)
-
- def __iter__(self):
- return chain(self.parent_listeners, self.listeners)
-
- def __bool__(self):
- return bool(self.listeners or self.parent_listeners)
-
- __nonzero__ = __bool__
-
-class _ListenerCollection(_CompoundListener):
- """Instance-level attributes on instances of :class:`._Dispatch`.
-
- Represents a collection of listeners.
-
- As of 0.7.9, _ListenerCollection is only first
- created via the _EmptyListener.for_modify() method.
-
- """
-
- def __init__(self, parent, target_cls):
- if target_cls not in parent._clslevel:
- parent.update_subclass(target_cls)
- self.parent_listeners = parent._clslevel[target_cls]
- self.parent = parent
- self.name = parent.__name__
- self.listeners = []
- self.propagate = set()
-
- def for_modify(self, obj):
- """Return an event collection which can be modified.
-
- For _ListenerCollection at the instance level of
- a dispatcher, this returns self.
-
- """
- return self
-
- def _update(self, other, only_propagate=True):
- """Populate from the listeners in another :class:`_Dispatch`
- object."""
-
- existing_listeners = self.listeners
- existing_listener_set = set(existing_listeners)
- self.propagate.update(other.propagate)
- existing_listeners.extend([l for l
- in other.listeners
- if l not in existing_listener_set
- and not only_propagate or l in self.propagate
- ])
-
- def insert(self, obj, target, propagate):
- if obj not in self.listeners:
- self.listeners.insert(0, obj)
- if propagate:
- self.propagate.add(obj)
-
- def append(self, obj, target, propagate):
- if obj not in self.listeners:
- self.listeners.append(obj)
- if propagate:
- self.propagate.add(obj)
-
- def remove(self, obj, target):
- if obj in self.listeners:
- self.listeners.remove(obj)
- self.propagate.discard(obj)
-
- def clear(self):
- self.listeners[:] = []
- self.propagate.clear()
-
-
-class _JoinedDispatcher(object):
- """Represent a connection between two _Dispatch objects."""
-
- def __init__(self, local, parent):
- self.local = local
- self.parent = parent
- self._parent_cls = local._parent_cls
-
-
-class _JoinedDispatchDescriptor(object):
- def __init__(self, name):
- self.name = name
-
- def __get__(self, obj, cls):
- if obj is None:
- return self
- else:
- obj.__dict__[self.name] = ret = _JoinedListener(
- obj.parent, self.name,
- getattr(obj.local, self.name)
- )
- return ret
-
-
-class _JoinedListener(_CompoundListener):
- _exec_once = False
-
- def __init__(self, parent, name, local):
- self.parent = parent
- self.name = name
- self.local = local
- self.parent_listeners = self.local
-
- # fix .listeners for the parent. This means
- # new events added to the parent won't be picked
- # up here. Alternatively, the listeners can
- # be via @property to just return getattr(self.parent, self.name)
- # each time. less performant.
- self.listeners = list(getattr(self.parent, self.name))
-
- def _adjust_fn_spec(self, fn, named):
- return self.local._adjust_fn_spec(fn, named)
-
- def for_modify(self, obj):
- self.local = self.parent_listeners = self.local.for_modify(obj)
- return self
-
- def insert(self, obj, target, propagate):
- self.local.insert(obj, target, propagate)
-
- def append(self, obj, target, propagate):
- self.local.append(obj, target, propagate)
-
- def remove(self, obj, target):
- self.local.remove(obj, target)
-
- def clear(self):
- raise NotImplementedError()
-
-
-class dispatcher(object):
- """Descriptor used by target classes to
- deliver the _Dispatch class at the class level
- and produce new _Dispatch instances for target
- instances.
-
- """
- def __init__(self, events):
- self.dispatch_cls = events.dispatch
- self.events = events
-
- def __get__(self, obj, cls):
- if obj is None:
- return self.dispatch_cls
- obj.__dict__['dispatch'] = disp = self.dispatch_cls(cls)
- return disp
--- /dev/null
+# sqlalchemy/event.py
+# Copyright (C) 2005-2013 the SQLAlchemy authors and contributors <see AUTHORS file>
+#
+# This module is part of SQLAlchemy and is released under
+# the MIT License: http://www.opensource.org/licenses/mit-license.php
+
+from .api import CANCEL, NO_RETVAL, listen, listens_for, remove
+from .base import Events
+from .attr import dispatcher, RefCollection
+from .legacy import _legacy_signature
--- /dev/null
+"""Public API functions for the event system.
+
+"""
+from __future__ import absolute_import
+
+from .. import util, exc
+from .base import _registrars
+from .registry import _EventKey
+
+CANCEL = util.symbol('CANCEL')
+NO_RETVAL = util.symbol('NO_RETVAL')
+
+
+def listen(target, identifier, fn, *args, **kw):
+ """Register a listener function for the given target.
+
+ e.g.::
+
+ from sqlalchemy import event
+ from sqlalchemy.schema import UniqueConstraint
+
+ def unique_constraint_name(const, table):
+ const.name = "uq_%s_%s" % (
+ table.name,
+ list(const.columns)[0].name
+ )
+ event.listen(
+ UniqueConstraint,
+ "after_parent_attach",
+ unique_constraint_name)
+
+ """
+
+ for evt_cls in _registrars[identifier]:
+ tgt = evt_cls._accept_with(target)
+ if tgt is not None:
+ _EventKey(target, identifier, fn, tgt).listen(*args, **kw)
+ break
+ else:
+ raise exc.InvalidRequestError("No such event '%s' for target '%s'" %
+ (identifier, target))
+
+
+def listens_for(target, identifier, *args, **kw):
+ """Decorate a function as a listener for the given target + identifier.
+
+ e.g.::
+
+ from sqlalchemy import event
+ from sqlalchemy.schema import UniqueConstraint
+
+ @event.listens_for(UniqueConstraint, "after_parent_attach")
+ def unique_constraint_name(const, table):
+ const.name = "uq_%s_%s" % (
+ table.name,
+ list(const.columns)[0].name
+ )
+ """
+ def decorate(fn):
+ listen(target, identifier, fn, *args, **kw)
+ return fn
+ return decorate
+
+
+def remove(target, identifier, fn):
+ """Remove an event listener.
+
+ The arguments here should match exactly those which were sent to
+ :func:`.listen`; all the event registration which proceeded as a result
+ of this call will be reverted by calling :func:`.remove` with the same
+ arguments.
+
+ e.g.::
+
+ # if a function was registered like this...
+ @event.listens_for(SomeMappedClass, "before_insert", propagate=True)
+ def my_listener_function(*arg):
+ pass
+
+ # ... it's removed like this
+ event.remove(SomeMappedClass, "before_insert", my_listener_function)
+
+ Above, the listener function associated with ``SomeMappedClass`` was also
+ propagated to subclasses of ``SomeMappedClass``; the :func:`.remove` function
+ will revert all of these operations.
+
+ .. versionadded:: 0.9.0
+
+ """
+ for evt_cls in _registrars[identifier]:
+ tgt = evt_cls._accept_with(target)
+ if tgt is not None:
+ _EventKey(target, identifier, fn, tgt).remove()
+ break
+ else:
+ raise exc.InvalidRequestError("No such event '%s' for target '%s'" %
+ (identifier, target))
+
+
--- /dev/null
+"""Attribute implementation for _Dispatch classes.
+
+The various listener targets for a particular event class are represented
+as attributes, which refer to collections of listeners to be fired off.
+These collections can exist at the class level as well as at the instance
+level. An event is fired off using code like this::
+
+ some_object.dispatch.first_connect(arg1, arg2)
+
+Above, ``some_object.dispatch`` would be an instance of ``_Dispatch`` and
+``first_connect`` is typically an instance of ``_ListenerCollection``
+if event listeners are present, or ``_EmptyListener`` if none are present.
+
+The attribute mechanics here spend effort trying to ensure listener functions
+are available with a minimum of function call overhead, that unnecessary
+objects aren't created (i.e. many empty per-instance listener collections),
+as well as that everything is garbage collectable when owning references are
+lost. Other features such as "propagation" of listener functions across
+many ``_Dispatch`` instances, "joining" of multiple ``_Dispatch`` instances,
+as well as support for subclass propagation (e.g. events assigned to
+``Pool`` vs. ``QueuePool``) are all implemented here.
+
+"""
+
+from __future__ import absolute_import
+
+from .. import util
+from . import registry
+from . import legacy
+from itertools import chain
+import weakref
+
+class RefCollection(object):
+ @util.memoized_property
+ def ref(self):
+ return weakref.ref(self, registry._collection_gced)
+
+class _DispatchDescriptor(RefCollection):
+ """Class-level attributes on :class:`._Dispatch` classes."""
+
+ def __init__(self, parent_dispatch_cls, fn):
+ self.__name__ = fn.__name__
+ argspec = util.inspect_getargspec(fn)
+ self.arg_names = argspec.args[1:]
+ self.has_kw = bool(argspec.keywords)
+ self.legacy_signatures = list(reversed(
+ sorted(
+ getattr(fn, '_legacy_signatures', []),
+ key=lambda s: s[0]
+ )
+ ))
+ self.__doc__ = fn.__doc__ = legacy._augment_fn_docs(
+ self, parent_dispatch_cls, fn)
+
+ self._clslevel = weakref.WeakKeyDictionary()
+ self._empty_listeners = weakref.WeakKeyDictionary()
+
+ def _adjust_fn_spec(self, fn, named):
+ argspec = util.get_callable_argspec(fn, no_self=True)
+ if named:
+ fn = self._wrap_fn_for_kw(fn)
+ fn = legacy._wrap_fn_for_legacy(self, fn, argspec)
+ return fn
+
+ def _wrap_fn_for_kw(self, fn):
+ def wrap_kw(*args, **kw):
+ argdict = dict(zip(self.arg_names, args))
+ argdict.update(kw)
+ return fn(**argdict)
+ return wrap_kw
+
+
+ def insert(self, event_key, propagate):
+ target = event_key.dispatch_target
+ assert isinstance(target, type), \
+ "Class-level Event targets must be classes."
+ stack = [target]
+ while stack:
+ cls = stack.pop(0)
+ stack.extend(cls.__subclasses__())
+ if cls is not target and cls not in self._clslevel:
+ self.update_subclass(cls)
+ else:
+ if cls not in self._clslevel:
+ self._clslevel[cls] = []
+ self._clslevel[cls].insert(0, event_key._listen_fn)
+ registry._stored_in_collection(event_key, self)
+
+ def append(self, event_key, propagate):
+ target = event_key.dispatch_target
+ assert isinstance(target, type), \
+ "Class-level Event targets must be classes."
+
+ stack = [target]
+ while stack:
+ cls = stack.pop(0)
+ stack.extend(cls.__subclasses__())
+ if cls is not target and cls not in self._clslevel:
+ self.update_subclass(cls)
+ else:
+ if cls not in self._clslevel:
+ self._clslevel[cls] = []
+ self._clslevel[cls].append(event_key._listen_fn)
+ registry._stored_in_collection(event_key, self)
+
+ def update_subclass(self, target):
+ if target not in self._clslevel:
+ self._clslevel[target] = []
+ clslevel = self._clslevel[target]
+ for cls in target.__mro__[1:]:
+ if cls in self._clslevel:
+ clslevel.extend([
+ fn for fn
+ in self._clslevel[cls]
+ if fn not in clslevel
+ ])
+
+ def remove(self, event_key):
+ target = event_key.dispatch_target
+ stack = [target]
+ while stack:
+ cls = stack.pop(0)
+ stack.extend(cls.__subclasses__())
+ if cls in self._clslevel:
+ self._clslevel[cls].remove(event_key.fn)
+ registry._removed_from_collection(event_key, self)
+
+ def clear(self):
+ """Clear all class level listeners"""
+
+ to_clear = set()
+ for dispatcher in self._clslevel.values():
+ to_clear.update(dispatcher)
+ dispatcher[:] = []
+ registry._clear(self, to_clear)
+
+ def for_modify(self, obj):
+ """Return an event collection which can be modified.
+
+ For _DispatchDescriptor at the class level of
+ a dispatcher, this returns self.
+
+ """
+ return self
+
+ def __get__(self, obj, cls):
+ if obj is None:
+ return self
+ elif obj._parent_cls in self._empty_listeners:
+ ret = self._empty_listeners[obj._parent_cls]
+ else:
+ self._empty_listeners[obj._parent_cls] = ret = \
+ _EmptyListener(self, obj._parent_cls)
+ # assigning it to __dict__ means
+ # memoized for fast re-access. but more memory.
+ obj.__dict__[self.__name__] = ret
+ return ret
+
+class _HasParentDispatchDescriptor(object):
+ def _adjust_fn_spec(self, fn, named):
+ return self.parent._adjust_fn_spec(fn, named)
+
+class _EmptyListener(_HasParentDispatchDescriptor):
+ """Serves as a class-level interface to the events
+ served by a _DispatchDescriptor, when there are no
+ instance-level events present.
+
+ Is replaced by _ListenerCollection when instance-level
+ events are added.
+
+ """
+ def __init__(self, parent, target_cls):
+ if target_cls not in parent._clslevel:
+ parent.update_subclass(target_cls)
+ self.parent = parent # _DispatchDescriptor
+ self.parent_listeners = parent._clslevel[target_cls]
+ self.name = parent.__name__
+ self.propagate = frozenset()
+ self.listeners = ()
+
+
+ def for_modify(self, obj):
+ """Return an event collection which can be modified.
+
+ For _EmptyListener at the instance level of
+ a dispatcher, this generates a new
+ _ListenerCollection, applies it to the instance,
+ and returns it.
+
+ """
+ result = _ListenerCollection(self.parent, obj._parent_cls)
+ if obj.__dict__[self.name] is self:
+ obj.__dict__[self.name] = result
+ return result
+
+ def _needs_modify(self, *args, **kw):
+ raise NotImplementedError("need to call for_modify()")
+
+ exec_once = insert = append = remove = clear = _needs_modify
+
+ def __call__(self, *args, **kw):
+ """Execute this event."""
+
+ for fn in self.parent_listeners:
+ fn(*args, **kw)
+
+ def __len__(self):
+ return len(self.parent_listeners)
+
+ def __iter__(self):
+ return iter(self.parent_listeners)
+
+ def __bool__(self):
+ return bool(self.parent_listeners)
+
+ __nonzero__ = __bool__
+
+
+class _CompoundListener(_HasParentDispatchDescriptor):
+ _exec_once = False
+
+ def exec_once(self, *args, **kw):
+ """Execute this event, but only if it has not been
+ executed already for this collection."""
+
+ if not self._exec_once:
+ self(*args, **kw)
+ self._exec_once = True
+
+ def __call__(self, *args, **kw):
+ """Execute this event."""
+
+ for fn in self.parent_listeners:
+ fn(*args, **kw)
+ for fn in self.listeners:
+ fn(*args, **kw)
+
+ def __len__(self):
+ return len(self.parent_listeners) + len(self.listeners)
+
+ def __iter__(self):
+ return chain(self.parent_listeners, self.listeners)
+
+ def __bool__(self):
+ return bool(self.listeners or self.parent_listeners)
+
+ __nonzero__ = __bool__
+
+class _ListenerCollection(RefCollection, _CompoundListener):
+ """Instance-level attributes on instances of :class:`._Dispatch`.
+
+ Represents a collection of listeners.
+
+ As of 0.7.9, _ListenerCollection is only first
+ created via the _EmptyListener.for_modify() method.
+
+ """
+
+ def __init__(self, parent, target_cls):
+ if target_cls not in parent._clslevel:
+ parent.update_subclass(target_cls)
+ self.parent_listeners = parent._clslevel[target_cls]
+ self.parent = parent
+ self.name = parent.__name__
+ self.listeners = []
+ self.propagate = set()
+
+ def for_modify(self, obj):
+ """Return an event collection which can be modified.
+
+ For _ListenerCollection at the instance level of
+ a dispatcher, this returns self.
+
+ """
+ return self
+
+ def _update(self, other, only_propagate=True):
+ """Populate from the listeners in another :class:`_Dispatch`
+ object."""
+
+ existing_listeners = self.listeners
+ existing_listener_set = set(existing_listeners)
+ self.propagate.update(other.propagate)
+ other_listeners = [l for l
+ in other.listeners
+ if l not in existing_listener_set
+ and not only_propagate or l in self.propagate
+ ]
+
+ existing_listeners.extend(other_listeners)
+
+ to_associate = other.propagate.union(other_listeners)
+ registry._stored_in_collection_multi(self, other, to_associate)
+
+ def insert(self, event_key, propagate):
+ if event_key._listen_fn not in self.listeners:
+ event_key.prepend_to_list(self, self.listeners)
+ if propagate:
+ self.propagate.add(event_key._listen_fn)
+
+ def append(self, event_key, propagate):
+ if event_key._listen_fn not in self.listeners:
+ event_key.append_to_list(self, self.listeners)
+ if propagate:
+ self.propagate.add(event_key._listen_fn)
+
+ def remove(self, event_key):
+ self.listeners.remove(event_key._listen_fn)
+ self.propagate.discard(event_key._listen_fn)
+ registry._removed_from_collection(event_key, self)
+
+ def clear(self):
+ registry._clear(self, self.listeners)
+ self.propagate.clear()
+ self.listeners[:] = []
+
+
+class _JoinedDispatchDescriptor(object):
+ def __init__(self, name):
+ self.name = name
+
+ def __get__(self, obj, cls):
+ if obj is None:
+ return self
+ else:
+ obj.__dict__[self.name] = ret = _JoinedListener(
+ obj.parent, self.name,
+ getattr(obj.local, self.name)
+ )
+ return ret
+
+
+class _JoinedListener(_CompoundListener):
+ _exec_once = False
+
+ def __init__(self, parent, name, local):
+ self.parent = parent
+ self.name = name
+ self.local = local
+ self.parent_listeners = self.local
+
+ @property
+ def listeners(self):
+ return getattr(self.parent, self.name)
+
+ def _adjust_fn_spec(self, fn, named):
+ return self.local._adjust_fn_spec(fn, named)
+
+ def for_modify(self, obj):
+ self.local = self.parent_listeners = self.local.for_modify(obj)
+ return self
+
+ def insert(self, event_key, propagate):
+ self.local.insert(event_key, propagate)
+
+ def append(self, event_key, propagate):
+ self.local.append(event_key, propagate)
+
+ def remove(self, event_key):
+ self.local.remove(event_key)
+
+ def clear(self):
+ raise NotImplementedError()
+
+
+class dispatcher(object):
+ """Descriptor used by target classes to
+ deliver the _Dispatch class at the class level
+ and produce new _Dispatch instances for target
+ instances.
+
+ """
+ def __init__(self, events):
+ self.dispatch_cls = events.dispatch
+ self.events = events
+
+ def __get__(self, obj, cls):
+ if obj is None:
+ return self.dispatch_cls
+ obj.__dict__['dispatch'] = disp = self.dispatch_cls(cls)
+ return disp
+
--- /dev/null
+"""Base implementation classes.
+
+The public-facing ``Events`` serves as the base class for an event interface;
+it's public attributes represent different kinds of events. These attributes
+are mirrored onto a ``_Dispatch`` class, which serves as a container for
+collections of listener functions. These collections are represented both
+at the class level of a particular ``_Dispatch`` class as well as within
+instances of ``_Dispatch``.
+
+"""
+from __future__ import absolute_import
+
+from .. import util
+from .attr import _JoinedDispatchDescriptor, _EmptyListener, _DispatchDescriptor
+
+_registrars = util.defaultdict(list)
+
+
+def _is_event_name(name):
+ return not name.startswith('_') and name != 'dispatch'
+
+
+class _UnpickleDispatch(object):
+ """Serializable callable that re-generates an instance of
+ :class:`_Dispatch` given a particular :class:`.Events` subclass.
+
+ """
+ def __call__(self, _parent_cls):
+ for cls in _parent_cls.__mro__:
+ if 'dispatch' in cls.__dict__:
+ return cls.__dict__['dispatch'].dispatch_cls(_parent_cls)
+ else:
+ raise AttributeError("No class with a 'dispatch' member present.")
+
+
+class _Dispatch(object):
+ """Mirror the event listening definitions of an Events class with
+ listener collections.
+
+ Classes which define a "dispatch" member will return a
+ non-instantiated :class:`._Dispatch` subclass when the member
+ is accessed at the class level. When the "dispatch" member is
+ accessed at the instance level of its owner, an instance
+ of the :class:`._Dispatch` class is returned.
+
+ A :class:`._Dispatch` class is generated for each :class:`.Events`
+ class defined, by the :func:`._create_dispatcher_class` function.
+ The original :class:`.Events` classes remain untouched.
+ This decouples the construction of :class:`.Events` subclasses from
+ the implementation used by the event internals, and allows
+ inspecting tools like Sphinx to work in an unsurprising
+ way against the public API.
+
+ """
+
+ def __init__(self, _parent_cls):
+ self._parent_cls = _parent_cls
+
+ def _join(self, other):
+ """Create a 'join' of this :class:`._Dispatch` and another.
+
+ This new dispatcher will dispatch events to both
+ :class:`._Dispatch` objects.
+
+ """
+ if '_joined_dispatch_cls' not in self.__class__.__dict__:
+ cls = type(
+ "Joined%s" % self.__class__.__name__,
+ (_JoinedDispatcher, self.__class__), {}
+ )
+ for ls in _event_descriptors(self):
+ setattr(cls, ls.name, _JoinedDispatchDescriptor(ls.name))
+
+ self.__class__._joined_dispatch_cls = cls
+ return self._joined_dispatch_cls(self, other)
+
+ def __reduce__(self):
+ return _UnpickleDispatch(), (self._parent_cls, )
+
+ def _update(self, other, only_propagate=True):
+ """Populate from the listeners in another :class:`_Dispatch`
+ object."""
+
+ for ls in _event_descriptors(other):
+ if isinstance(ls, _EmptyListener):
+ continue
+ getattr(self, ls.name).\
+ for_modify(self)._update(ls, only_propagate=only_propagate)
+
+ @util.hybridmethod
+ def _clear(self):
+ for attr in dir(self):
+ if _is_event_name(attr):
+ getattr(self, attr).for_modify(self).clear()
+
+
+def _event_descriptors(target):
+ return [getattr(target, k) for k in dir(target) if _is_event_name(k)]
+
+
+class _EventMeta(type):
+ """Intercept new Event subclasses and create
+ associated _Dispatch classes."""
+
+ def __init__(cls, classname, bases, dict_):
+ _create_dispatcher_class(cls, classname, bases, dict_)
+ return type.__init__(cls, classname, bases, dict_)
+
+
+def _create_dispatcher_class(cls, classname, bases, dict_):
+ """Create a :class:`._Dispatch` class corresponding to an
+ :class:`.Events` class."""
+
+ # there's all kinds of ways to do this,
+ # i.e. make a Dispatch class that shares the '_listen' method
+ # of the Event class, this is the straight monkeypatch.
+ dispatch_base = getattr(cls, 'dispatch', _Dispatch)
+ cls.dispatch = dispatch_cls = type("%sDispatch" % classname,
+ (dispatch_base, ), {})
+ dispatch_cls._listen = cls._listen
+
+ for k in dict_:
+ if _is_event_name(k):
+ setattr(dispatch_cls, k, _DispatchDescriptor(cls, dict_[k]))
+ _registrars[k].append(cls)
+
+
+def _remove_dispatcher(cls):
+ for k in dir(cls):
+ if _is_event_name(k):
+ _registrars[k].remove(cls)
+ if not _registrars[k]:
+ del _registrars[k]
+
+class Events(util.with_metaclass(_EventMeta, object)):
+ """Define event listening functions for a particular target type."""
+
+ @classmethod
+ def _accept_with(cls, target):
+ # Mapper, ClassManager, Session override this to
+ # also accept classes, scoped_sessions, sessionmakers, etc.
+ if hasattr(target, 'dispatch') and (
+ isinstance(target.dispatch, cls.dispatch) or \
+ isinstance(target.dispatch, type) and \
+ issubclass(target.dispatch, cls.dispatch)
+ ):
+ return target
+ else:
+ return None
+
+ @classmethod
+ def _listen(cls, event_key, propagate=False, insert=False, named=False):
+ event_key.base_listen(propagate=propagate, insert=insert, named=named)
+
+ @classmethod
+ def _remove(cls, event_key):
+ event_key.remove()
+
+ @classmethod
+ def _clear(cls):
+ cls.dispatch._clear()
+
+
+class _JoinedDispatcher(object):
+ """Represent a connection between two _Dispatch objects."""
+
+ def __init__(self, local, parent):
+ self.local = local
+ self.parent = parent
+ self._parent_cls = local._parent_cls
+
--- /dev/null
+"""Routines to handle adaption of legacy call signatures,
+generation of deprecation notes and docstrings.
+
+"""
+
+from .. import util
+
+def _legacy_signature(since, argnames, converter=None):
+ def leg(fn):
+ if not hasattr(fn, '_legacy_signatures'):
+ fn._legacy_signatures = []
+ fn._legacy_signatures.append((since, argnames, converter))
+ return fn
+ return leg
+
+def _wrap_fn_for_legacy(dispatch_descriptor, fn, argspec):
+ for since, argnames, conv in dispatch_descriptor.legacy_signatures:
+ if argnames[-1] == "**kw":
+ has_kw = True
+ argnames = argnames[0:-1]
+ else:
+ has_kw = False
+
+ if len(argnames) == len(argspec.args) \
+ and has_kw is bool(argspec.keywords):
+
+ if conv:
+ assert not has_kw
+ def wrap_leg(*args):
+ return fn(*conv(*args))
+ else:
+ def wrap_leg(*args, **kw):
+ argdict = dict(zip(dispatch_descriptor.arg_names, args))
+ args = [argdict[name] for name in argnames]
+ if has_kw:
+ return fn(*args, **kw)
+ else:
+ return fn(*args)
+ return wrap_leg
+ else:
+ return fn
+
+def _indent(text, indent):
+ return "\n".join(
+ indent + line
+ for line in text.split("\n")
+ )
+
+def _standard_listen_example(dispatch_descriptor, sample_target, fn):
+ example_kw_arg = _indent(
+ "\n".join(
+ "%(arg)s = kw['%(arg)s']" % {"arg": arg}
+ for arg in dispatch_descriptor.arg_names[0:2]
+ ),
+ " ")
+ if dispatch_descriptor.legacy_signatures:
+ current_since = max(since for since, args, conv
+ in dispatch_descriptor.legacy_signatures)
+ else:
+ current_since = None
+ text = (
+ "from sqlalchemy import event\n\n"
+ "# standard decorator style%(current_since)s\n"
+ "@event.listens_for(%(sample_target)s, '%(event_name)s')\n"
+ "def receive_%(event_name)s(%(named_event_arguments)s%(has_kw_arguments)s):\n"
+ " \"listen for the '%(event_name)s' event\"\n"
+ "\n # ... (event handling logic) ...\n"
+ )
+
+ if len(dispatch_descriptor.arg_names) > 2:
+ text += (
+
+ "\n# named argument style (new in 0.9)\n"
+ "@event.listens_for(%(sample_target)s, '%(event_name)s', named=True)\n"
+ "def receive_%(event_name)s(**kw):\n"
+ " \"listen for the '%(event_name)s' event\"\n"
+ "%(example_kw_arg)s\n"
+ "\n # ... (event handling logic) ...\n"
+ )
+
+ text %= {
+ "current_since": " (arguments as of %s)" %
+ current_since if current_since else "",
+ "event_name": fn.__name__,
+ "has_kw_arguments": " **kw" if dispatch_descriptor.has_kw else "",
+ "named_event_arguments": ", ".join(dispatch_descriptor.arg_names),
+ "example_kw_arg": example_kw_arg,
+ "sample_target": sample_target
+ }
+ return text
+
+def _legacy_listen_examples(dispatch_descriptor, sample_target, fn):
+ text = ""
+ for since, args, conv in dispatch_descriptor.legacy_signatures:
+ text += (
+ "\n# legacy calling style (pre-%(since)s)\n"
+ "@event.listens_for(%(sample_target)s, '%(event_name)s')\n"
+ "def receive_%(event_name)s(%(named_event_arguments)s%(has_kw_arguments)s):\n"
+ " \"listen for the '%(event_name)s' event\"\n"
+ "\n # ... (event handling logic) ...\n" % {
+ "since": since,
+ "event_name": fn.__name__,
+ "has_kw_arguments": " **kw" if dispatch_descriptor.has_kw else "",
+ "named_event_arguments": ", ".join(args),
+ "sample_target": sample_target
+ }
+ )
+ return text
+
+def _version_signature_changes(dispatch_descriptor):
+ since, args, conv = dispatch_descriptor.legacy_signatures[0]
+ return (
+ "\n.. versionchanged:: %(since)s\n"
+ " The ``%(event_name)s`` event now accepts the \n"
+ " arguments ``%(named_event_arguments)s%(has_kw_arguments)s``.\n"
+ " Listener functions which accept the previous argument \n"
+ " signature(s) listed above will be automatically \n"
+ " adapted to the new signature." % {
+ "since": since,
+ "event_name": dispatch_descriptor.__name__,
+ "named_event_arguments": ", ".join(dispatch_descriptor.arg_names),
+ "has_kw_arguments": ", **kw" if dispatch_descriptor.has_kw else ""
+ }
+ )
+
+def _augment_fn_docs(dispatch_descriptor, parent_dispatch_cls, fn):
+ header = ".. container:: event_signatures\n\n"\
+ " Example argument forms::\n"\
+ "\n"
+
+ sample_target = getattr(parent_dispatch_cls, "_target_class_doc", "obj")
+ text = (
+ header +
+ _indent(
+ _standard_listen_example(
+ dispatch_descriptor, sample_target, fn),
+ " " * 8)
+ )
+ if dispatch_descriptor.legacy_signatures:
+ text += _indent(
+ _legacy_listen_examples(
+ dispatch_descriptor, sample_target, fn),
+ " " * 8)
+
+ text += _version_signature_changes(dispatch_descriptor)
+
+ return util.inject_docstring_text(fn.__doc__,
+ text,
+ 1
+ )
--- /dev/null
+"""Provides managed registration services on behalf of :func:`.listen`
+arguments.
+
+By "managed registration", we mean that event listening functions and
+other objects can be added to various collections in such a way that their
+membership in all those collections can be revoked at once, based on
+an equivalent :class:`._EventKey`.
+
+"""
+
+from __future__ import absolute_import
+
+import weakref
+import collections
+from .. import exc
+
+
+_key_to_collection = collections.defaultdict(dict)
+"""
+Given an original listen() argument, can locate all
+listener collections and the listener fn contained
+
+(target, identifier, fn) -> {
+ ref(listenercollection) -> ref(listener_fn)
+ ref(listenercollection) -> ref(listener_fn)
+ ref(listenercollection) -> ref(listener_fn)
+ }
+"""
+
+_collection_to_key = collections.defaultdict(dict)
+"""
+Given a _ListenerCollection or _DispatchDescriptor, can locate
+all the original listen() arguments and the listener fn contained
+
+ref(listenercollection) -> {
+ ref(listener_fn) -> (target, identifier, fn),
+ ref(listener_fn) -> (target, identifier, fn),
+ ref(listener_fn) -> (target, identifier, fn),
+ }
+"""
+
+def _collection_gced(ref):
+ # defaultdict, so can't get a KeyError
+ if ref not in _collection_to_key:
+ return
+ listener_to_key = _collection_to_key.pop(ref)
+ for key in listener_to_key.values():
+ if key in _key_to_collection:
+ # defaultdict, so can't get a KeyError
+ dispatch_reg = _key_to_collection[key]
+ dispatch_reg.pop(ref)
+ if not dispatch_reg:
+ _key_to_collection.pop(key)
+
+def _stored_in_collection(event_key, owner):
+ key = event_key._key
+
+ dispatch_reg = _key_to_collection[key]
+
+ owner_ref = owner.ref
+ listen_ref = weakref.ref(event_key._listen_fn)
+
+ if owner_ref in dispatch_reg:
+ assert dispatch_reg[owner_ref] == listen_ref
+ else:
+ dispatch_reg[owner_ref] = listen_ref
+
+ listener_to_key = _collection_to_key[owner_ref]
+ listener_to_key[listen_ref] = key
+
+def _removed_from_collection(event_key, owner):
+ key = event_key._key
+
+ dispatch_reg = _key_to_collection[key]
+
+ listen_ref = weakref.ref(event_key._listen_fn)
+
+ owner_ref = owner.ref
+ dispatch_reg.pop(owner_ref, None)
+ if not dispatch_reg:
+ del _key_to_collection[key]
+
+ if owner_ref in _collection_to_key:
+ listener_to_key = _collection_to_key[owner_ref]
+ listener_to_key.pop(listen_ref)
+
+def _stored_in_collection_multi(newowner, oldowner, elements):
+ if not elements:
+ return
+
+ oldowner = oldowner.ref
+ newowner = newowner.ref
+
+ old_listener_to_key = _collection_to_key[oldowner]
+ new_listener_to_key = _collection_to_key[newowner]
+
+ for listen_fn in elements:
+ listen_ref = weakref.ref(listen_fn)
+ key = old_listener_to_key[listen_ref]
+ dispatch_reg = _key_to_collection[key]
+ if newowner in dispatch_reg:
+ assert dispatch_reg[newowner] == listen_ref
+ else:
+ dispatch_reg[newowner] = listen_ref
+
+ new_listener_to_key[listen_ref] = key
+
+def _clear(owner, elements):
+ if not elements:
+ return
+
+ owner = owner.ref
+ listener_to_key = _collection_to_key[owner]
+ for listen_fn in elements:
+ listen_ref = weakref.ref(listen_fn)
+ key = listener_to_key[listen_ref]
+ dispatch_reg = _key_to_collection[key]
+ dispatch_reg.pop(owner, None)
+
+ if not dispatch_reg:
+ del _key_to_collection[key]
+
+
+class _EventKey(object):
+ """Represent :func:`.listen` arguments.
+ """
+
+
+ def __init__(self, target, identifier, fn, dispatch_target, _fn_wrap=None):
+ self.target = target
+ self.identifier = identifier
+ self.fn = fn
+ self.fn_wrap = _fn_wrap
+ self.dispatch_target = dispatch_target
+
+ @property
+ def _key(self):
+ return (id(self.target), self.identifier, id(self.fn))
+
+
+ def with_wrapper(self, fn_wrap):
+ if fn_wrap is self._listen_fn:
+ return self
+ else:
+ return _EventKey(
+ self.target,
+ self.identifier,
+ self.fn,
+ self.dispatch_target,
+ _fn_wrap=fn_wrap
+ )
+
+ def with_dispatch_target(self, dispatch_target):
+ if dispatch_target is self.dispatch_target:
+ return self
+ else:
+ return _EventKey(
+ self.target,
+ self.identifier,
+ self.fn,
+ dispatch_target,
+ _fn_wrap=self.fn_wrap
+ )
+
+ def listen(self, *args, **kw):
+ self.dispatch_target.dispatch._listen(self, *args, **kw)
+
+ def remove(self):
+ key = self._key
+
+ if key not in _key_to_collection:
+ raise exc.InvalidRequestError(
+ "No listeners found for event %s / %r / %s " %
+ (self.target, self.identifier, self.fn)
+ )
+ dispatch_reg = _key_to_collection.pop(key)
+
+ for collection_ref, listener_ref in dispatch_reg.items():
+ collection = collection_ref()
+ listener_fn = listener_ref()
+ if collection is not None and listener_fn is not None:
+ collection.remove(self.with_wrapper(listener_fn))
+
+
+ def base_listen(self, propagate=False, insert=False,
+ named=False):
+
+ target, identifier, fn = \
+ self.dispatch_target, self.identifier, self._listen_fn
+
+ dispatch_descriptor = getattr(target.dispatch, identifier)
+
+ fn = dispatch_descriptor._adjust_fn_spec(fn, named)
+ self = self.with_wrapper(fn)
+
+ if insert:
+ dispatch_descriptor.\
+ for_modify(target.dispatch).insert(self, propagate)
+ else:
+ dispatch_descriptor.\
+ for_modify(target.dispatch).append(self, propagate)
+
+ @property
+ def _listen_fn(self):
+ return self.fn_wrap or self.fn
+
+ def append_value_to_list(self, owner, list_, value):
+ _stored_in_collection(self, owner)
+ list_.append(value)
+
+ def append_to_list(self, owner, list_):
+ _stored_in_collection(self, owner)
+ list_.append(self._listen_fn)
+
+ def remove_from_list(self, owner, list_):
+ _removed_from_collection(self, owner)
+ list_.remove(self._listen_fn)
+
+ def prepend_to_list(self, owner, list_):
+ _stored_in_collection(self, owner)
+ list_.insert(0, self._listen_fn)
+
_target_class_doc = "SomeEngine"
@classmethod
- def _listen(cls, target, identifier, fn, retval=False):
+ def _listen(cls, event_key, retval=False):
+ target, identifier, fn = \
+ event_key.dispatch_target, event_key.identifier, event_key.fn
+
target._has_events = True
if not retval:
"'before_cursor_execute' engine "
"event listeners accept the 'retval=True' "
"argument.")
- event.Events._listen(target, identifier, fn)
+ event_key.with_wrapper(fn).base_listen()
def before_execute(self, conn, clauseelement, multiparams, params):
"""Intercept high level execute() events, receiving uncompiled
@classmethod
def _accept_with(cls, target):
- # TODO: there's no coverage for this
if isinstance(target, type):
return _InstrumentationEventsHold(target)
else:
return None
@classmethod
- def _listen(cls, target, identifier, fn, propagate=True):
+ def _listen(cls, event_key, propagate=True):
+ target, identifier, fn = \
+ event_key.dispatch_target, event_key.identifier, event_key.fn
def listen(target_cls, *arg):
listen_cls = target()
return fn(target_cls, *arg)
def remove(ref):
- event.Events._remove(orm.instrumentation._instrumentation_factory,
- identifier, listen)
+ key = event.registry._EventKey(None, identifier, listen,
+ orm.instrumentation._instrumentation_factory)
+ getattr(orm.instrumentation._instrumentation_factory.dispatch,
+ identifier).remove(key)
target = weakref.ref(target.class_, remove)
- event.Events._listen(orm.instrumentation._instrumentation_factory,
- identifier, listen)
- @classmethod
- def _remove(cls, identifier, target, fn):
- raise NotImplementedError("Removal of instrumentation events "
- "not yet implemented")
+ event_key.\
+ with_dispatch_target(orm.instrumentation._instrumentation_factory).\
+ with_wrapper(listen).base_listen()
@classmethod
def _clear(cls):
return None
@classmethod
- def _listen(cls, target, identifier, fn, raw=False, propagate=False):
+ def _listen(cls, event_key, raw=False, propagate=False):
+ target, identifier, fn = \
+ event_key.dispatch_target, event_key.identifier, event_key.fn
+
if not raw:
orig_fn = fn
def wrap(state, *arg, **kw):
return orig_fn(state.obj(), *arg, **kw)
fn = wrap
+ event_key = event_key.with_wrapper(fn)
+
+ event_key.base_listen(propagate=propagate)
- event.Events._listen(target, identifier, fn, propagate=propagate)
if propagate:
for mgr in target.subclass_managers(True):
- event.Events._listen(mgr, identifier, fn, True)
-
- @classmethod
- def _remove(cls, identifier, target, fn):
- msg = "Removal of instance events not yet implemented"
- raise NotImplementedError(msg)
+ event_key.with_dispatch_target(mgr).base_listen(propagate=True)
@classmethod
def _clear(cls):
"""
-
-class _EventsHold(object):
+class _EventsHold(event.RefCollection):
"""Hold onto listeners against unmapped, uninstrumented classes.
Establish _listen() for that class' mapper/instrumentation when
class HoldEvents(object):
@classmethod
- def _listen(cls, target, identifier, fn, raw=False, propagate=False):
+ def _listen(cls, event_key, raw=False, propagate=False):
+ target, identifier, fn = \
+ event_key.dispatch_target, event_key.identifier, event_key.fn
+
if target.class_ in target.all_holds:
collection = target.all_holds[target.class_]
else:
- collection = target.all_holds[target.class_] = []
+ collection = target.all_holds[target.class_] = {}
- collection.append((identifier, fn, raw, propagate))
+ event.registry._stored_in_collection(event_key, target)
+ collection[event_key._key] = (event_key, raw, propagate)
if propagate:
stack = list(target.class_.__subclasses__())
stack.extend(subclass.__subclasses__())
subject = target.resolve(subclass)
if subject is not None:
- subject.dispatch._listen(subject, identifier, fn,
- raw=raw, propagate=propagate)
+ event_key.with_dispatch_target(subject).\
+ listen(raw=raw, propagate=propagate)
+
+ def remove(self, event_key):
+ target, identifier, fn = \
+ event_key.dispatch_target, event_key.identifier, event_key.fn
+
+ collection = target.all_holds[target.class_]
+ del collection[event_key._key]
@classmethod
def populate(cls, class_, subject):
for subclass in class_.__mro__:
if subclass in cls.all_holds:
collection = cls.all_holds[subclass]
- for ident, fn, raw, propagate in collection:
+ for event_key, raw, propagate in collection.values():
if propagate or subclass is class_:
# since we can't be sure in what order different classes
# in a hierarchy are triggered with populate(),
# we rely upon _EventsHold for all event
# assignment, instead of using the generic propagate
# flag.
- subject.dispatch._listen(subject, ident,
- fn, raw=raw,
- propagate=False)
+ event_key.with_dispatch_target(subject).\
+ listen(raw=raw, propagate=False)
class _InstanceEventsHold(_EventsHold):
return target
@classmethod
- def _listen(cls, target, identifier, fn,
+ def _listen(cls, event_key,
raw=False, retval=False, propagate=False):
+ target, identifier, fn = \
+ event_key.dispatch_target, event_key.identifier, event_key.fn
if not raw or not retval:
if not raw:
else:
return wrapped_fn(*arg, **kw)
fn = wrap
+ event_key = event_key.with_wrapper(wrap)
if propagate:
for mapper in target.self_and_descendants:
- event.Events._listen(mapper, identifier, fn, propagate=True)
+ event_key.with_dispatch_target(mapper).base_listen(propagate=True)
else:
- event.Events._listen(target, identifier, fn)
+ event_key.base_listen()
@classmethod
def _clear(cls):
"""
- @classmethod
- def _remove(cls, identifier, target, fn):
- "Removal of mapper events not yet implemented"
- raise NotImplementedError(msg)
-
class _MapperEventsHold(_EventsHold):
all_holds = weakref.WeakKeyDictionary()
else:
return None
- @classmethod
- def _remove(cls, identifier, target, fn):
- msg = "Removal of session events not yet implemented"
- raise NotImplementedError(msg)
-
def after_transaction_create(self, session, transaction):
"""Execute when a new :class:`.SessionTransaction` is created.
return target
@classmethod
- def _listen(cls, target, identifier, fn, active_history=False,
+ def _listen(cls, event_key, active_history=False,
raw=False, retval=False,
propagate=False):
+
+ target, identifier, fn = \
+ event_key.dispatch_target, event_key.identifier, event_key.fn
+
if active_history:
target.dispatch._active_history = True
- # TODO: for removal, need to package the identity
- # of the wrapper with the original function.
-
if not raw or not retval:
orig_fn = fn
else:
return orig_fn(target, value, *arg)
fn = wrap
+ event_key = event_key.with_wrapper(wrap)
- event.Events._listen(target, identifier, fn, propagate)
+ event_key.base_listen(propagate=propagate)
if propagate:
manager = orm.instrumentation.manager_of_class(target.class_)
for mgr in manager.subclass_managers(True):
- event.Events._listen(mgr[target.key], identifier, fn, True)
-
- @classmethod
- def _remove(cls, identifier, target, fn):
- msg = "Removal of attribute events not yet implemented"
- raise NotImplementedError(msg)
+ event_key.with_dispatch_target(mgr[target.key]).base_listen(propagate=True)
def append(self, target, value, initiator):
"""Receive a collection append event.
dispatch = event.dispatcher(events.InstanceEvents)
+ def __hash__(self):
+ return id(self)
+
+ def __eq__(self, other):
+ return other is self
+
@property
def is_mapped(self):
return 'mapper' in self.__dict__
gc_collect()
samples[x] = len(get_objects_skipping_sqlite_issue())
+
print("sample gc sizes:", samples)
assert len(_sessions) == 0
from sqlalchemy.testing import fixtures
from sqlalchemy.testing.util import gc_collect
from sqlalchemy.testing.mock import Mock, call
-
+from sqlalchemy import testing
class EventsTest(fixtures.TestBase):
"""Test class- and instance-level event registration."""
def setUp(self):
- assert 'event_one' not in event._registrars
- assert 'event_two' not in event._registrars
-
class TargetEvents(event.Events):
def event_one(self, x, y):
pass
self.Target = Target
def tearDown(self):
- event._remove_dispatcher(self.Target.__dict__['dispatch'].events)
+ event.base._remove_dispatcher(self.Target.__dict__['dispatch'].events)
def test_register_class(self):
def listen(x, y):
eq_(len(self.Target().dispatch.event_one), 2)
eq_(len(t1.dispatch.event_one), 3)
- def test_append_vs_insert(self):
+ def test_append_vs_insert_cls(self):
def listen_one(x, y):
pass
[listen_three, listen_one, listen_two]
)
+ def test_append_vs_insert_instance(self):
+ def listen_one(x, y):
+ pass
+
+ def listen_two(x, y):
+ pass
+
+ def listen_three(x, y):
+ pass
+
+ target = self.Target()
+ event.listen(target, "event_one", listen_one)
+ event.listen(target, "event_one", listen_two)
+ event.listen(target, "event_one", listen_three, insert=True)
+
+ eq_(
+ list(target.dispatch.event_one),
+ [listen_three, listen_one, listen_two]
+ )
+
def test_decorator(self):
@event.listens_for(self.Target, "event_one")
def listen_one(x, y):
self.TargetOne = TargetOne
def tearDown(self):
- event._remove_dispatcher(self.TargetOne.__dict__['dispatch'].events)
+ event.base._remove_dispatcher(self.TargetOne.__dict__['dispatch'].events)
def test_kw_accept(self):
self.TargetOne = TargetOne
def tearDown(self):
- event._remove_dispatcher(self.TargetOne.__dict__['dispatch'].events)
+ event.base._remove_dispatcher(self.TargetOne.__dict__['dispatch'].events)
def test_legacy_accept(self):
canary = Mock()
def tearDown(self):
- event._remove_dispatcher(self.TargetOne.__dict__['dispatch'].events)
+ event.base._remove_dispatcher(self.TargetOne.__dict__['dispatch'].events)
def setUp(self):
class TargetEventsOne(event.Events):
self.TargetOne = TargetOne
def tearDown(self):
- event._remove_dispatcher(
+ event.base._remove_dispatcher(
self.TargetOne.__dict__['dispatch'].events)
def test_lis_subcalss_lis(self):
self.TargetTwo = TargetTwo
def tearDown(self):
- event._remove_dispatcher(self.TargetOne.__dict__['dispatch'].events)
- event._remove_dispatcher(self.TargetTwo.__dict__['dispatch'].events)
+ event.base._remove_dispatcher(self.TargetOne.__dict__['dispatch'].events)
+ event.base._remove_dispatcher(self.TargetTwo.__dict__['dispatch'].events)
def test_target_accept(self):
"""Test that events of the same name are routed to the correct
self.Target = Target
def tearDown(self):
- event._remove_dispatcher(self.Target.__dict__['dispatch'].events)
+ event.base._remove_dispatcher(self.Target.__dict__['dispatch'].events)
def test_indirect(self):
def listen(x, y):
def setUp(self):
class TargetEvents(event.Events):
@classmethod
- def _listen(cls, target, identifier, fn, add=False):
+ def _listen(cls, event_key, add=False):
+ fn = event_key.fn
if add:
def adapt(x, y):
fn(x + y)
- else:
- adapt = fn
+ event_key = event_key.with_wrapper(adapt)
- event.Events._listen(target, identifier, adapt)
+ event_key.base_listen()
def event_one(self, x, y):
pass
self.Target = Target
def tearDown(self):
- event._remove_dispatcher(self.Target.__dict__['dispatch'].events)
+ event.base._remove_dispatcher(self.Target.__dict__['dispatch'].events)
def test_listen_override(self):
listen_one = Mock()
for cls in (self.TargetElement,
self.TargetFactory, self.BaseTarget):
if 'dispatch' in cls.__dict__:
- event._remove_dispatcher(cls.__dict__['dispatch'].events)
+ event.base._remove_dispatcher(cls.__dict__['dispatch'].events)
def test_neither(self):
element = self.TargetFactory().create()
element.run_event(2)
element.run_event(3)
- # c1 gets no events due to _JoinedListener
- # fixing the "parent" at construction time.
- # this can be changed to be "live" at the cost
- # of performance.
+ # if _JoinedListener fixes .listeners
+ # at construction time, then we don't get
+ # the new listeners.
+ #eq_(l1.mock_calls, [])
+
+ # alternatively, if _JoinedListener shares the list
+ # using a @property, then we get them, at the arguable
+ # expense of the extra method call to access the .listeners
+ # collection
eq_(
- l1.mock_calls, []
+ l1.mock_calls, [call(element, 2), call(element, 3)]
)
+
eq_(
l2.mock_calls,
[call(element, 1), call(element, 2), call(element, 3)]
l1.mock_calls,
[call(element, 1), call(element, 2), call(element, 3)]
)
+
+class RemovalTest(fixtures.TestBase):
+ def _fixture(self):
+ class TargetEvents(event.Events):
+ def event_one(self, x, y):
+ pass
+
+ def event_two(self, x):
+ pass
+
+ def event_three(self, x):
+ pass
+
+ class Target(object):
+ dispatch = event.dispatcher(TargetEvents)
+ return Target
+
+ def test_clslevel(self):
+ Target = self._fixture()
+
+ m1 = Mock()
+
+ event.listen(Target, "event_two", m1)
+
+ t1 = Target()
+ t1.dispatch.event_two("x")
+
+ event.remove(Target, "event_two", m1)
+
+ t1.dispatch.event_two("y")
+
+ eq_(m1.mock_calls, [call("x")])
+
+ def test_clslevel_subclass(self):
+ Target = self._fixture()
+ class SubTarget(Target):
+ pass
+
+ m1 = Mock()
+
+ event.listen(Target, "event_two", m1)
+
+ t1 = SubTarget()
+ t1.dispatch.event_two("x")
+
+ event.remove(Target, "event_two", m1)
+
+ t1.dispatch.event_two("y")
+
+ eq_(m1.mock_calls, [call("x")])
+
+ def test_propagate(self):
+ Target = self._fixture()
+
+ m1 = Mock()
+
+ t1 = Target()
+ t2 = Target()
+
+ event.listen(t1, "event_one", m1, propagate=True)
+ event.listen(t1, "event_two", m1, propagate=False)
+
+ t2.dispatch._update(t1.dispatch)
+
+ t1.dispatch.event_one("t1e1x")
+ t1.dispatch.event_two("t1e2x")
+ t2.dispatch.event_one("t2e1x")
+ t2.dispatch.event_two("t2e2x")
+
+ event.remove(t1, "event_one", m1)
+ event.remove(t1, "event_two", m1)
+
+ t1.dispatch.event_one("t1e1y")
+ t1.dispatch.event_two("t1e2y")
+ t2.dispatch.event_one("t2e1y")
+ t2.dispatch.event_two("t2e2y")
+
+ eq_(m1.mock_calls,
+ [call('t1e1x'), call('t1e2x'),
+ call('t2e1x')])
+
+ @testing.requires.predictable_gc
+ def test_listener_collection_removed_cleanup(self):
+ from sqlalchemy.event import registry
+
+ Target = self._fixture()
+
+ m1 = Mock()
+
+ t1 = Target()
+
+ event.listen(t1, "event_one", m1)
+
+ key = (id(t1), "event_one", id(m1))
+
+ assert key in registry._key_to_collection
+ collection_ref = list(registry._key_to_collection[key])[0]
+ assert collection_ref in registry._collection_to_key
+
+ t1.dispatch.event_one("t1")
+
+ del t1
+
+ gc_collect()
+
+ assert key not in registry._key_to_collection
+ assert collection_ref not in registry._collection_to_key
+
+ def test_remove_not_listened(self):
+ Target = self._fixture()
+
+ m1 = Mock()
+
+ t1 = Target()
+
+ event.listen(t1, "event_one", m1, propagate=True)
+ event.listen(t1, "event_three", m1)
+
+ event.remove(t1, "event_one", m1)
+ assert_raises_message(
+ exc.InvalidRequestError,
+ r"No listeners found for event <.*Target.*> / 'event_two' / <Mock.*> ",
+ event.remove, t1, "event_two", m1
+ )
+
+ event.remove(t1, "event_three", m1)
+
+
+
+
+
class _RemoveListeners(object):
def teardown(self):
- # TODO: need to get remove() functionality
- # going
events.MapperEvents._clear()
events.InstanceEvents._clear()
events.SessionEvents._clear()
class Bar(object):
pass
- listeners = instrumentation._instrumentation_factory.dispatch.\
- attribute_instrument.listeners
- assert not listeners
+ dispatch = instrumentation._instrumentation_factory.dispatch
+ assert not dispatch.attribute_instrument
- canary = []
- def evt(x):
- canary.append(x)
- event.listen(Bar, "attribute_instrument", evt)
+ event.listen(Bar, "attribute_instrument", lambda: None)
- eq_(len(listeners), 1)
+ eq_(len(dispatch.attribute_instrument), 1)
del Bar
gc_collect()
- assert not listeners
+ assert not dispatch.attribute_instrument
def test_deferred_instrument_event_subclass_propagate(self):
eq_(canary, ['load'])
+class RemovalTest(_fixtures.FixtureTest):
+ run_inserts = None
+
+
+ def test_attr_propagated(self):
+ User = self.classes.User
+
+ users, addresses, User = (self.tables.users,
+ self.tables.addresses,
+ self.classes.User)
+
+ class AdminUser(User):
+ pass
+
+ mapper(User, users)
+ mapper(AdminUser, addresses, inherits=User)
+
+ fn = Mock()
+ event.listen(User.name, "set", fn, propagate=True)
+
+ au = AdminUser()
+ au.name = 'ed'
+
+ eq_(fn.call_count, 1)
+
+ event.remove(User.name, "set", fn)
+
+ au.name = 'jack'
+
+ eq_(fn.call_count, 1)
+
+ def test_unmapped_listen(self):
+ users = self.tables.users
+
+ class Foo(object):
+ pass
+
+ fn = Mock()
+
+ event.listen(Foo, "before_insert", fn, propagate=True)
+
+ class User(Foo):
+ pass
+
+ m = mapper(User, users)
+
+ u1 = User()
+ m.dispatch.before_insert(m, None, attributes.instance_state(u1))
+ eq_(fn.call_count, 1)
+
+ event.remove(Foo, "before_insert", fn)
+
+ # existing event is removed
+ m.dispatch.before_insert(m, None, attributes.instance_state(u1))
+ eq_(fn.call_count, 1)
+
+ # the _HoldEvents is also cleaned out
+ class Bar(Foo):
+ pass
+ m = mapper(Bar, users)
+ b1 = Bar()
+ m.dispatch.before_insert(m, None, attributes.instance_state(b1))
+ eq_(fn.call_count, 1)
+
class RefreshTest(_fixtures.FixtureTest):
run_inserts = None
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
