Watson - Events¶

Trigger and handle event flow with your application.

Build Status¶

Installation¶

pip install watson-events

Testing¶

Watson can be tested with py.test. Simply activate your virtualenv and run python setup.py test.

Contributing¶

If you would like to contribute to Watson, please feel free to issue a pull request via Github with the associated tests for your code. Your name will be added to the AUTHORS file under contributors.

Table of Contents¶

Usage¶

Using the event dispatcher is a three step process.

Create the event dispatcher
Add your event listener to the dispatcher
Trigger the dispatcher

from watson.events import dispatcher, types

dispatcher = dispatcher.EventDispatcher()  # create the dispatcher
dispatcher.add('MyEvent', lambda x: x.name)  # add your event listener
result = dispatcher.trigger(types.Event('SampleEvent'))  # trigger the event

print(result.first())  # 'SampleEvent'

Reference Library¶

watson.events.collections¶

class watson.events.collections.Listener[source]¶

A list of listeners to be used in an EventDispatcher.

A Listener Collection is a list of callbacks that are to be triggered by an event dispatcher. Each item in the list contains the callback, a priority, and whether or not the callback should only be triggered once.

add(callback, priority=1, only_once=False)[source]¶

Adds a new callback to the collection.

Parameters:	callback (callable) – the function to be triggered priority (int) – how important the callback is in relation to others only_once (bool) – the callback should only be fired once and then removed
Raises:	TypeError if non-callable is added. –

remove(callback)[source]¶

Removes all callbacks matching callback from the collection.

Parameters:	callback (callable) – the callback to be removed.

sort_priority()[source]¶: Sort the collection based on the priority of the callbacks.

watson.events.collections.ListenerDefinition¶: alias of Listener

class watson.events.collections.Result[source]¶

A list of responses from a EventDispatcher.trigger call.

A result collection contains all the resulting output from an event that has been triggered from an event dispatcher. It provides some convenience methods to deal with the results.

first(default=None)[source]¶

Return the first result from the list.

Parameters:	default (mixed) – The value to return if the index doesn’t exist
Returns:	The first result
Return type:	mixed

last(default=None)[source]¶

Return the last result from the list.

Parameters:	default (mixed) – The value to return if the index doesn’t exist
Returns:	The first result
Return type:	mixed

watson.events.dispatcher¶

class watson.events.dispatcher.EventDispatcher[source]¶

Register and trigger events that will be executed by callables.

The EventDispatcher allows user defined events to be specified. Any listener that is triggered will have the event that was triggered passed to it as the first argument. Attributes can be added to the event params (see watson.events.types.Event) which can then be accessed by the listener.

Example:

dispatcher = EventDispatcher()
dispatcher.add('MyEvent', lambda x: x.name)
result = dispatcher.trigger(Event('SampleEvent'))
result.first()  # 'SampleEvent'

add(event, callback, priority=1, only_once=False)[source]¶

Add an event listener to the dispatcher.

Adds an event listener to the relevant event listener collection. If a listener is set to once_only, it will be removed when the event is triggered on the EventDispatcher.

Parameters:	event (string) – The name of the event callback (callable) – A callable function to be triggered priority (int) – The priority of the listener (higher == more important) once_only (boolean) – When triggered, the listener will be removed
Returns:	A list of listeners attached to the event
Return type:	ListCollection

clear()[source]¶: Clears all registered events from the event dispatcher.

events[source]¶: Returns the events registered on the event dispatcher.

has(event, callback=None)[source]¶: Return whether or not a callback is found for a particular event.

remove(event, callback=None)[source]¶

Remove an event listener from the dispatcher.

Removes an event listener from the relevant Listener. If no callback is specified, all event listeners for that event are removed.

Parameters:	event (string) – The name of the event callback (callable) – A callable function to be triggered
Returns:	A list of listeners attached to the event
Return type:	Listener

trigger(event)[source]¶

Fire an event and return a list of results from all listeners.

Dispatches an event to all associated listeners and returns a list of results. If the event is stopped (Event.stopped) then the Result returned will only contain the response from the first listener in the stack.

Parameters:	event (watson.events.types.Event) – The event to trigger
Returns:	A list of all the responses
Return type:	Result

class watson.events.dispatcher.EventDispatcherAware[source]¶

Provides an interface for event dispatchers to be injected.

dispatcher[source]¶

Retrieve the event dispatcher. If no event dispatcher exists, create a default one.

Returns:	An EventDispatcher object

watson.events.types¶

class watson.events.types.Event(name, target=None, params=None)[source]¶

A base event that can be subclassed for use with an EventDispatcher.

Example:

def my_listener(event):
    print(event.params['config'])

dispatcher.add('MyEvent', my_listener)

event = Event('MyEvent')
event.params['config'] = {'some': 'config'}
dispatcher.trigger(event)

__init__(name, target=None, params=None)[source]¶

Initializes the event.

Initialize the Event based on an event name. The name will be used when the event is triggered from the event dispatcher.

Parameters:	name (string) – the name of the event target (mixed) – the originating target of the event params (dict) – the params associated with the event

stop_propagation()[source]¶

Prevents the event from triggering any more event listeners.

This should be used within an event listener when you wish to halt any further listeners from being triggered.

stopped[source]¶: Return whether or not the event has been stopped.