pydispatch.dispatch#

Dispatcher class#

class Dispatcher(*args, **kwargs)[source]#

Core class used to enable all functionality in the library

Interfaces with Event and Property objects upon instance creation.

Events can be created by calling register_event() or by the subclass definition:

class Foo(Dispatcher):
    _events_ = ['awesome_event', 'on_less_awesome_event']

Once defined, an event can be dispatched to listeners by calling emit().

bind(**kwargs)[source]#

Subscribes to events or to Property updates

Keyword arguments are used with the Event or Property names as keys and the callbacks as values:

class Foo(Dispatcher):
    name = Property()

foo = Foo()

foo.bind(name=my_listener.on_foo_name_changed)
foo.bind(name=other_listener.on_name,
         value=other_listener.on_value)

The callbacks are stored as weak references and their order is not maintained relative to the order of binding.

Async Callbacks:

Callbacks may be coroutine functions (defined using async def or decorated with @asyncio.coroutine), but an event loop must be explicitly provided with the keyword argument "__aio_loop__" (an instance of asyncio.BaseEventLoop)

>>> import asyncio

>>> class Foo(Dispatcher):
...     _events_ = ['test_event']

>>> class Bar(object):
...     def __init__(self):
...         self.got_foo_event = asyncio.Event()
...     async def wait_for_foo(self):
...         await self.got_foo_event.wait()
...         print('got foo!')
...     async def on_foo_test_event(self, *args, **kwargs):
...         self.got_foo_event.set()

>>> loop = asyncio.get_event_loop()
>>> foo = Foo()
>>> bar = Bar()
>>> foo.bind(test_event=bar.on_foo_test_event, __aio_loop__=loop)
>>> fut = asyncio.ensure_future(bar.wait_for_foo())

>>> foo.emit('test_event')
>>> loop.run_until_complete(fut)
got foo!

This can also be done using bind_async().

Raises:
DoesNotExistError: If attempting to bind to an event or

property that has not been registered

Changed in version 0.2.2: DoesNotExistError is now raised when binding to non-existent events or properties

New in version 0.1.0.

bind_async(loop, **kwargs)[source]#

Subscribes to events with async callbacks

Functionality is matches the bind() method, except the provided callbacks should be coroutine functions. When the event is dispatched, callbacks will be placed on the given event loop.

For keyword arguments, see bind().

Parameters

loop – The EventLoop to use when events are dispatched

Availability:

Python>=3.5

New in version 0.1.0.

emission_lock(name)[source]#

Holds emission of events and dispatches the last event on release

The context manager returned will store the last event data called by emit() and prevent callbacks until it exits. On exit, it will dispatch the last event captured (if any)

>>> class Foo(Dispatcher):
...     _events_ = ['my_event']

>>> def on_my_event(value):
...     print(value)

>>> foo = Foo()
>>> foo.bind(my_event=on_my_event)
>>> with foo.emission_lock('my_event'):
...     foo.emit('my_event', 1)
...     foo.emit('my_event', 2)
2
Parameters

name (str) – The name of the Event or Property

Returns

A context manager to be used by the with statement.

If available, this will also be an async context manager to be used with the async with statement (see PEP 492).

Note

The context manager is re-entrant, meaning that multiple calls to this method within nested context scopes are possible.

Raises

DoesNotExistError – If no event or property with the given name exists

Changed in version 0.2.2: DoesNotExistError is now raised if the event or property does not exist

emit(name, *args, **kwargs)[source]#

Dispatches an event to any subscribed listeners

Note

If a listener returns False, the event will stop dispatching to other listeners. Any other return value is ignored.

Parameters

  • name (str) – The name of the Event to dispatch

  • *args (Optional) – Positional arguments to be sent to listeners

  • **kwargs (Optional) – Keyword arguments to be sent to listeners

Raises

DoesNotExistError – If attempting to emit an event or property that has not been registered

Changed in version 0.2.2: DoesNotExistError is now raised if the event or property does not exist

get_dispatcher_event(name)[source]#

Retrieves an Event object by name

Parameters

name (str) – The name of the Event or Property object to retrieve

Returns

The Event instance for the event or property definition

Raises

DoesNotExistError – If no event or property with the given name exists

Changed in version 0.2.2: DoesNotExistError is now raised if the event or property does not exist

New in version 0.1.0.

register_event(*names)[source]#

Registers new events after instance creation

Parameters

*names (str) – Name or names of the events to register

Raises

Changed in version 0.2.2: ExistsError exceptions are raised when attempting to register an event or property that already exists

unbind(*args)[source]#

Unsubscribes from events or Property updates

Multiple arguments can be given. Each of which can be either the method that was used for the original call to bind() or an instance object.

If an instance of an object is supplied, any previously bound Events and Properties will be ‘unbound’.

Event class#

class Event(name)[source]#

Holds references to event names and subscribed listeners

This is used internally by Dispatcher.

__call__(*args, **kwargs)[source]#

Dispatches the event to listeners

Called by emit()

Exceptions#

class DoesNotExistError(name)[source]#

Raised when binding to an Event or Property that does not exist

New in version 0.2.2.

class ExistsError(name)[source]#

Raised when registering an event name that already exists as either a normal Event or Property

New in version 0.2.2.

class EventExistsError(name)[source]#

Raised when registering an event name that already exists as an Event

New in version 0.2.2.

class PropertyExistsError(name)[source]#

Raised when registering an event name that already exists as a Property

New in version 0.2.2.