Dispatcher is the core component of the framework. Subclassing this enables all of the event functionality.


>>> from pydispatch import Dispatcher

>>> class MyEmitter(Dispatcher):
...     _events_ = ['on_state', 'new_data']

>>> # An observer - could inherit from Dispatcher or any other class
>>> class MyListener(object):
...     def on_new_data(self, *args, **kwargs):
...         data = kwargs.get('data')
...         print('I got data: {}'.format(data))
...     def on_emitter_state(self, *args, **kwargs):
...         print('emitter state changed')

>>> emitter = MyEmitter()
>>> listener = MyListener()

>>> # Bind to the "on_state" and "new_data" events of emitter
>>> emitter.bind(on_state=listener.on_emitter_state)
>>> emitter.bind(new_data=listener.on_new_data)

>>> emitter.emit('new_data', data='foo')
I got data: foo

>>> emitter.emit('on_state')
emitter state changed

The bind method above could also be combined:


Events can also be created after object creation:


# Multiple events can also be created:
emitter.register_event('value_changed', 'something_happened')

Stop listening by calling unbind:


# Or to unbind all events, just supply the instance object:

Callback Return Values#

Event propagation will stop if any callback returns False. Any other return value is ignored.

Event Names#

There are no restrictions on event names. The idea is to keep things as simple and non-restrictive as possible. When calling emit, and positional or keyword arguments supplied will be passed along to listeners.

Subclasses and __init__()#

The Dispatcher class does not use __init__() for any of its functionality. This is again to keep things simple and get the framework out of your way. Direct subclasses do not need to include a call to super() within their __init__() method.

Instead, the __init_subclass__() method is used to gather the Event and Property definitions from each class. If __init_subclass__() is defined by your subclasses (which is rare), a call to super() is required.

Likewise, the __new__() method is used to handle instance attributes. If __new__() is defined by a subclass (again this is rare), it must also include a call to super().