Global Dispatcher

New in version 0.2.2.

At the module-level, most of the functionality of Dispatcher can be used directly as a singleton instance. Note that this interface only supports event dispatching (not Properties).

When used this way, the concept is similar to the Signals Framework found in Django.

Basic Usage

Events can be registered using register_event(), connected to callbacks using bind() and dispatched with the emit() function.

>>> import pydispatch

>>> def my_callback(message, **kwargs):
...     print(f'my_callback: "{message}"')

>>> # register 'event_a' as an event and bind it to my_callback
>>> pydispatch.register_event('event_a')
>>> pydispatch.bind(event_a=my_callback)

>>> # emit the event
>>> pydispatch.emit('event_a', 'hello')
my_callback: "hello"

>>> # unbind the callback
>>> pydispatch.unbind(my_callback)
>>> pydispatch.emit('event_a', 'still there?')

>>> # (Nothing printed)

The @receiver Decorator

To simplify binding callbacks to events, the receiver() decorator may be used.

>>> from pydispatch import receiver

>>> @receiver('event_a')
... def my_callback(message, **kwargs):
...     print(f'my_callback: "{message}"')

>>> pydispatch.emit('event_a', 'hello again!')
my_callback: "hello again!"

Note that there is currently no way to unbind() a callback defined in this way.

Arguments

If the event name has not been registered beforehand, the cache and auto_register arguments to receiver() may be used

cache

The cache argument stores the callback and will bind it to the event once it is registered.

>>> # No event named 'foo' exists yet
>>> @receiver('foo', cache=True)
... def on_foo(message, **kwargs):
...     print(f'on_foo: "{message}"')

>>> # on_foo will be connected after the call to register_event
>>> pydispatch.register_event('foo')
>>> pydispatch.emit('foo', 'bar')
on_foo: "bar"

auto_register

The auto_register argument will immediately register the event if it does not exist

>>> @receiver('bar', auto_register=True)
... def on_bar(message, **kwargs):
...     print(f'on_bar: "{message}"')

>>> pydispatch.emit('bar', 'baz')
on_bar: "baz"

Async Support

If the decorated callback is a coroutine function or method, the EventLoop returned by asyncio.get_event_loop() will be used as the loop argument to bind_async().

This will in most cases be the desired behavior unless multiple event loops (in separate threads) are being used.