Watson - Events. Release 1.0.3

Transcription

1 Watson - Events Release Jan 15, 2018

2

3 Contents 1 Build Status 3 2 Installation 5 3 Testing 7 4 Contributing 9 5 Table of Contents Usage Reference Library Python Module Index 15 i

4 ii

5 Watson - Events, Release Trigger and handle event flow with your application. Contents 1

6 Watson - Events, Release Contents

7 CHAPTER 1 Build Status 3

8 Watson - Events, Release Chapter 1. Build Status

9 CHAPTER 2 Installation pip install watson-events 5

10 Watson - Events, Release Chapter 2. Installation

11 CHAPTER 3 Testing Watson can be tested with py.test. Simply activate your virtualenv and run python setup.py test. 7

12 Watson - Events, Release Chapter 3. Testing

13 CHAPTER 4 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. 9

14 Watson - Events, Release Chapter 4. Contributing

15 CHAPTER 5 Table of Contents 5.1 Usage Using the event dispatcher is a three step process. 1. Create the event dispatcher 2. Add your event listener to the dispatcher 3. 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' 5.2 Reference Library watson.events.collections class watson.events.collections.listener 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) Adds a new callback to the collection. Parameters 11

16 Watson - Events, Release 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) Removes all callbacks matching callback from the collection. Parameters callback (callable) the callback to be removed. sort_priority() Sort the collection based on the priority of the callbacks. watson.events.collections.listenerdefinition alias of Listener class watson.events.collections.result 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) 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) 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 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) 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. 12 Chapter 5. Table of Contents

17 Watson - Events, Release 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() Clears all registered events from the event dispatcher. events Returns the events registered on the event dispatcher. has(event, callback=none) Return whether or not a callback is found for a particular event. remove(event, callback=none) 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) 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 Provides an interface for event dispatchers to be injected. dispatcher 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) A base event that can be subclassed for use with an EventDispatcher. Example: 5.2. Reference Library 13

18 Watson - Events, Release 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) 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() 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 Return whether or not the event has been stopped. 14 Chapter 5. Table of Contents

19 Python Module Index w watson.events.collections, 11 watson.events.dispatcher, 12 watson.events.types, 13 15

20 Watson - Events, Release Python Module Index

21 Index Symbols init () (watson.events.types.event method), 14 A add() (watson.events.collections.listener method), 11 add() (watson.events.dispatcher.eventdispatcher method), 12 C clear() (watson.events.dispatcher.eventdispatcher method), 13 D dispatcher (watson.events.dispatcher.eventdispatcheraware attribute), 13 E Event (class in watson.events.types), 13 EventDispatcher (class in watson.events.dispatcher), 12 EventDispatcherAware (class in watson.events.dispatcher), 13 events (watson.events.dispatcher.eventdispatcher attribute), 13 F first() (watson.events.collections.result method), 12 H has() (watson.events.dispatcher.eventdispatcher method), 13 L last() (watson.events.collections.result method), 12 Listener (class in watson.events.collections), 11 ListenerDefinition (in module watson.events.collections), 12 R remove() (watson.events.collections.listener method), 12 remove() (watson.events.dispatcher.eventdispatcher method), 13 Result (class in watson.events.collections), 12 S sort_priority() (watson.events.collections.listener method), 12 stop_propagation() (watson.events.types.event method), 14 stopped (watson.events.types.event attribute), 14 T trigger() (watson.events.dispatcher.eventdispatcher method), 13 W watson.events.collections (module), 11 watson.events.dispatcher (module), 12 watson.events.types (module), 13 17