spreadflow_core.eventdispatcher module

Event Dispatcher

Implements an priority queue based event dispatcher.

class spreadflow_core.eventdispatcher.Entry(key, handler)

Bases: tuple

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__getstate__()

Exclude the OrderedDict from pickling

__repr__()

Return a nicely formatted representation string

handler

Alias for field number 1

key

Alias for field number 0

class spreadflow_core.eventdispatcher.EventDispatcher

Bases: object

Event dispatcher.

An event dispatcher specifically designed for twisted deferreds.

Event handlers can be registered for user defined event types. An event handler may return a deferred causing the dispatcher to wait on it. When dispatching an event, the handlers are called according to their priority. The dispatcher only advances to the next priority when all handlers with a lower priority have completed.

Additional positional and keyword arguments provided while registering the event handler are passed to the callback upon invocation.

Example

The following example illustrates how to register event handlers and dispatch events:

from __future__ import print_function
from spreadflow_core.eventdispatcher import EventDispatcher

class GreetEvent(object):
    def __init__(self, message='hello'):
        self.message = message

def simple_greeter(event):
    print(event.message)

def complex_greeter(event, prefix, suffix):
    print(prefix + event.message + suffix)

dispatcher = EventDispatcher()

dispatcher.add_listener(GreetEvent, 99, simple_greeter)
dispatcher.add_listener(GreetEvent, 0, complex_greeter,
    'oh, ', suffix=' world!')

dispatcher.dispatch(GreetEvent())

This example will generate the following output:

oh, hello world!
hello

Any exception raised by a handler will immediately stop any callbacks in progress unless fail_mode=FailMode.RETURN is specified. The utility method log_failures provides an easy way to log any exceptions.

event = GreetEvent() deferred = dispatcher.dispatch(event) deferred.addCallback(dispatcher.log_failures, event)
add_listener(event_type, priority, callback, *args, **kwds)

Register a callback function for events of the given type.

Parameters:
  • event_type – Type of the event. Pass the class in here for events based on classes.
  • priority (int) – Priority of this handler.
  • callback (callable) – The function to call when an event of the given type is dispatched.
  • *args – Positional parameters passed to the function upon invocation.
  • **kwds – Keyword parameters passed to the function upon invocation.
Returns:

A reference to the registered listener. This can be used to subsequently remove it again.
Return type:

spreadflow_core.eventdispatcher.Key
dispatch(*args, **kwargs)

Dispatch an event, calling all the registered listeners in turn.

Parameters:
  • event – An event instance.
  • fail_mode – One of FailMode.RAISE (default) and FailMode.RESULT.
Returns:

A list of tuples (priority, list-of-results) where each entry in the nested list is of the form (success, result).

When a handler fails and FailMode.RAISE is specified, errbacks with a spreadflow_core.eventdispatcher.HandlerError. When FailMode.RETURN is specified, the failures are returned as part of the result.
get_listeners(event_type)

Returns an iterator over listeners for the given event type.

Parameters:
  • event_type – Type of the event. Pass the class in here for events
  • on classes. (based) –
Returns:

An iterator over the listeners for the given event type.
get_listeners_grouped(event_type)

Returns a group iterator over listeners for the given event type.

Parameters:
  • event_type – Type of the event. Pass the class in here for events
  • on classes. (based) –
Returns:

An iterator over the listeners grouped by priority.
log

A L{Logger} emits log messages to an observer. You should instantiate it as a class or module attribute, as documented in L{this module’s documentation <twisted.logger>}.

log_failures(result, event)

Inspects the result returned by dispatch and logs any failures.

Parameters:
  • result – The result as returned by dispatch.
  • event – An event instance.
Returns:

The result as passed into the method. Thus this method also can be used in the callback chain of the deferred returned by dispatch.
remove_listener(event_type, key)

Removes an event handler from the list of listeners for the given type.

Parameters:
  • event_type – Type of the event. Pass the class in here for events based on classes.
  • key – A key as returned by add_listeners.
Returns:

A reference to the removed callback, positional parameters and keyword arguments.
Return type:

spreadflow_core.eventdispatcher.Handler
class spreadflow_core.eventdispatcher.FailMode

Bases: object

Failure modes enumeration

RAISE

int

Raise an exception if a handler fails.

RETURN

int

Include failures into the result returned by the dispatch method.

RAISE = 0
RETURN = 1
class spreadflow_core.eventdispatcher.Handler(callback, args, kwds)

Bases: tuple

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__getstate__()

Exclude the OrderedDict from pickling

__repr__()

Return a nicely formatted representation string

args

Alias for field number 1

callback

Alias for field number 0

kwds

Alias for field number 2

exception spreadflow_core.eventdispatcher.HandlerError(handler, wrapped_failure)

Bases: exceptions.Exception

An exception wrapping an error generated by an event handler.

handler

The handler record responsible for the error.

wrapped_failure

A failure instance.

class spreadflow_core.eventdispatcher.Key(priority, serial)

Bases: tuple

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__getstate__()

Exclude the OrderedDict from pickling

__repr__()

Return a nicely formatted representation string

priority

Alias for field number 0

serial

Alias for field number 1