t.w.x.u.EventDispatcher : class documentation

Part of twisted.words.xish.utility View Source View In Hierarchy

Known subclasses: twisted.words.xish.xmlstream.XmlStream

Event dispatching service.

The EventDispatcher allows observers to be registered for certain events that are dispatched. There are two types of events: XPath events and Named events.

Every dispatch is triggered by calling dispatch with a data object and, for named events, the name of the event.

When an XPath type event is dispatched, the associated object is assumed to be an Element instance, which is matched against all registered XPath queries. For every match, the respective observer will be called with the data object.

A named event will simply call each registered observer for that particular event name, with the data object. Unlike XPath type events, the data object is not restricted to Element, but can be anything.

When registering observers, the event that is to be observed is specified using an xpath.XPathQuery instance or a string. In the latter case, the string can also contain the string representation of an XPath expression. To distinguish these from named events, each named event should start with a special prefix that is stored in self.prefix. It defaults to //event/.

Observers registered using addObserver are persistent: after the observer has been triggered by a dispatch, it remains registered for a possible next dispatch. If instead addOnetimeObserver was used to observe an event, the observer is removed from the list of observers after the first observed event.

Observers can also be prioritized, by providing an optional priority parameter to the addObserver and addOnetimeObserver methods. Higher priority observers are then called before lower priority observers.

Finally, observers can be unregistered by using removeObserver.

Method __init__ Undocumented
Method addOnetimeObserver Register a one-time observer for an event.
Method addObserver Register an observer for an event.
Method removeObserver Remove callable as observer for an event.
Method dispatch Dispatch an event.
Method _getEventAndObservers Undocumented
Method _addObserver Undocumented
def __init__(self, eventprefix='//event/'): (source)
Undocumented
def _getEventAndObservers(self, event): (source)
Undocumented
def addOnetimeObserver(self, event, observerfn, *args, priority=0, **kwargs): (source)
Register a one-time observer for an event.

Like addObserver, but is only triggered at most once. See there for a description of the parameters.

def addObserver(self, event, observerfn, *args, priority=0, **kwargs): (source)
Register an observer for an event.

Each observer will be registered with a certain priority. Higher priority observers get called before lower priority observers.

ParameterseventName or XPath query for the event to be monitored. (type: str or xpath.XPathQuery.)
observerfnFunction to be called when the specified event has been triggered. This callable takes one parameter: the data object that triggered the event. When specified, the *args and **kwargs parameters to addObserver are being used as additional parameters to the registered observer callable.
priority(Optional) priority of this observer in relation to other observer that match the same event. Defaults to 0. (type: int)
def _addObserver(self, onetime, event, observerfn, priority, *args, **kwargs): (source)
Undocumented
def removeObserver(self, event, observerfn): (source)
Remove callable as observer for an event.

The observer callable is removed for all priority levels for the specified event.

ParameterseventEvent for which the observer callable was registered. (type: str or xpath.XPathQuery)
observerfnObserver callable to be unregistered.
def dispatch(self, obj, event=None): (source)
Dispatch an event.

When event is None, an XPath type event is triggered, and obj is assumed to be an instance of Element. Otherwise, event holds the name of the named event being triggered. In the latter case, obj can be anything.

ParametersobjThe object to be dispatched.
eventOptional event name. (type: str)
API Documentation for Twisted, generated by pydoctor at 2012-09-01 11:44:56.