Dispatcher

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

Usage

>>> 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:

emitter.bind(on_state=listener.on_emitter_state,
             new_data=listener.on_new_data)

Events can also be created after object creation:

emitter.register_event('need_data')

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

Stop listening by calling unbind:

emitter.unbind(listener.on_emitter_state)

# Or to unbind all events, just supply the instance object:
emitter.unbind(listener)

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().