An efficient and minimalistic signaling/hook module.
 
To use this in a class, subclass SignalDispatcher and call
SignalDispatcher.__init__(self) in the __init__ function.  Now you can bind
functions to a signal name (string) by using signal_bind or remove it with
signal_unbind.  Now whenever signal_emit is called with that signal name,
the bound functions are executed in order of priority.
 
This module supports weak referencing.  This means that if you bind a function
which is later deleted everywhere except in this binding, Python's garbage
collector will remove it from memory.  Activate it with
signal_bind(..., weak=True).  The handlers for such functions are automatically
deleted when trying to call them (in signal_emit), but if they are never
called, they accumulate and should be manually deleted with
signal_garbage_collect().
 
>>> def test_function(signal):
...     if 'display' in signal:
...         print(signal.display)
...     else:
...         signal.stop()
>>> def temporary_function():
...     print("A temporary function")
 
>>> sig = SignalDispatcher()
 
>>> # Test binding and unbinding
>>> handler1 = sig.signal_bind('test', test_function, priority=2)
>>> handler2 = sig.signal_bind('test', temporary_function, priority=1)
>>> sig.signal_emit('test', display="It works!")
It works!
A temporary function
True
>>> # Note that test_function stops the signal when there's no display keyword
>>> sig.signal_emit('test')
False
>>> sig.signal_unbind(handler1)
>>> sig.signal_emit('test')
A temporary function
True
>>> sig.signal_clear()
>>> sig.signal_emit('test')
True
 
>>> # Bind temporary_function with a weak reference
>>> handler = sig.signal_bind('test', temporary_function, weak=True)
>>> sig.signal_emit('test')
A temporary function
True
>>> # Delete temporary_function.  Its handler is removed too, since it
>>> # was weakly referenced.
>>> del temporary_function
>>> sig.signal_emit('test')
True

Modules
		weakref

Classes
		builtins.dict(builtins.object) Signal builtins.object SignalDispatcher SignalHandler   class Signal(builtins.dict)     Signals are passed to the bound functions as an argument.   They contain the attributes "origin", which is a reference to the signal dispatcher, and "name", the name of the signal that was emitted. You can call signal_emit with any keyword arguments, which will be turned into attributes of this object as well.   To delete a signal handler from inside a signal, raise a ReferenceError.     Method resolution order: Signal builtins.dict builtins.object Methods defined here: __init__(self, **keywords) stop(self) Stop the propagation of the signal to the next handlers. Data descriptors defined here: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined) Data and other attributes defined here: stopped = False Methods inherited from builtins.dict: __contains__(self, key, /) True if D has a key k, else False. __delitem__(self, key, /) Delete self[key]. __eq__(self, value, /) Return self==value. __ge__(...) __ge__=($self, value, /) --   Return self>=value. __getattribute__(self, name, /) Return getattr(self, name). __getitem__(...) x.__getitem__(y) <==> x[y] __gt__(self, value, /) Return self>value. __iter__(self, /) Implement iter(self). __le__(self, value, /) Return self<=value. __len__(self, /) Return len(self). __lt__(self, value, /) Return self<value. __ne__(self, value, /) Return self!=value. __new__(*args, **kwargs) from builtins.type Create and return a new object.  See help(type) for accurate signature. __repr__(self, /) Return repr(self). __setitem__(self, key, value, /) Set self[key] to value. __sizeof__(...) D.__sizeof__() -> size of D in memory, in bytes clear(...) D.clear() -> None.  Remove all items from D. copy(...) D.copy() -> a shallow copy of D fromkeys(iterable, value=None, /) from builtins.type Returns a new dict with keys from iterable and values equal to value. get(...) D.get(k[,d]) -> D[k] if k in D, else d.  d defaults to None. items(...) D.items() -> a set-like object providing a view on D's items keys(...) D.keys() -> a set-like object providing a view on D's keys pop(...) D.pop(k[,d]) -> v, remove specified key and return the corresponding value. If key is not found, d is returned if given, otherwise KeyError is raised popitem(...) D.popitem() -> (k, v), remove and return some (key, value) pair as a 2-tuple; but raise KeyError if D is empty. setdefault(...) D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D update(...) D.update([E, ]**F) -> None.  Update D from dict/iterable E and F. If E is present and has a .keys() method, then does:  for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does:  for k, v in E: D[k] = v In either case, this is followed by: for k in F:  D[k] = F[k] values(...) D.values() -> an object providing a view on D's values Data and other attributes inherited from builtins.dict: __hash__ = None   class SignalDispatcher(builtins.object)     This abstract class handles the binding and emitting of signals.     Methods defined here: __init__(self) signal_bind(self, signal_name, function, priority=0.5, weak=False, autosort=True) Bind a function to the signal.   signal_name:  Any string to name the signal function:  Any function with either one or zero arguments which will be     called when the signal is emitted.  If it takes one argument, a     Signal object will be passed to it. priority:  Optional, any number.  When signals are emitted, handlers will     be called in order of priority.  (highest priority first) weak:  Use a weak reference of "function" so it can be garbage collected     properly when it's deleted.   Returns a SignalHandler which can be used to remove this binding by passing it to signal_unbind(). signal_clear(self) Remove all signals. signal_emit(self, signal_name, **kw) Emits a signal and call every function that was bound to that signal.   You can call this method with any key words.  They will be turned into attributes of the Signal object that is passed to the functions. If a function calls signal.stop(), no further functions will be called. If a function raises a ReferenceError, the handler will be deleted.   Returns False if signal.stop() was called and True otherwise. signal_force_sort(self, signal_name=None) Forces a sorting of signal handlers by priority.   This is only necessary if you used signal_bind with autosort=False after finishing to bind many signals at once. signal_garbage_collect(self) Remove all handlers with deleted weak references.   Usually this is not needed; every time you emit a signal, its handlers are automatically checked in this way.  However, if you can't be sure that a signal is ever emitted AND you keep binding weakly referenced functions to the signal, this method should be regularly called to avoid memory leaks in self._signals.   >>> sig = SignalDispatcher()   >>> # lambda:None is an anonymous function which has no references >>> # so it should get deleted immediately >>> handler = sig.signal_bind('test', lambda: None, weak=True) >>> len(sig._signals['test']) 1 >>> # need to call garbage collect so that it's removed from the list. >>> sig.signal_garbage_collect() >>> len(sig._signals['test']) 0 >>> # This demonstrates that garbage collecting is not necessary >>> # when using signal_emit(). >>> handler = sig.signal_bind('test', lambda: None, weak=True) >>> sig.signal_emit('another_signal') True >>> len(sig._signals['test']) 1 >>> sig.signal_emit('test') True >>> len(sig._signals['test']) 0 signal_unbind(self, signal_handler) Removes a signal binding.   This requires the SignalHandler that has been originally returned by signal_bind(). Data descriptors defined here: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined)   class SignalHandler(builtins.object)     Signal Handlers contain information about a signal binding.   They are returned by signal_bind() and have to be passed to signal_unbind() in order to remove the handler again.   You can disable a handler without removing it by setting the attribute "active" to False.     Methods defined here: __init__(self, signal_name, function, priority, pass_signal) Data descriptors defined here: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined) Data and other attributes defined here: active = True