Stanza Handlers¶
The Basic Handler¶
-
class
slixmpp.xmlstream.handler.base.
BaseHandler
(name, matcher, stream=None)[source]¶ Base class for stream handlers. Stream handlers are matched with incoming stanzas so that the stanza may be processed in some way. Stanzas may be matched with multiple handlers.
Handler execution may take place in two phases: during the incoming stream processing, and in the main event loop. The
prerun()
method is executed in the first case, andrun()
is called during the second.Parameters: - name (string) – The name of the handler.
- matcher – A
MatcherBase
derived object that will be used to determine if a stanza should be accepted by this handler. - stream – The
XMLStream
instance that the handle will respond to.
-
match
(xml)[source]¶ Compare a stanza or XML object with the handler’s matcher.
Parameters: xml – An XML or ElementBase
object
-
name
= None¶ The name of the handler
-
prerun
(payload)[source]¶ Prepare the handler for execution while the XML stream is being processed.
Parameters: payload – A ElementBase
object.
-
run
(payload)[source]¶ Execute the handler after XML stream processing and during the main event loop.
Parameters: payload – A ElementBase
object.
-
stream
= None¶ The XML stream this handler is assigned to
Callback¶
-
class
slixmpp.xmlstream.handler.
Callback
(name, matcher, pointer, thread=False, once=False, instream=False, stream=None)[source]¶ The Callback handler will execute a callback function with matched stanzas.
The handler may execute the callback either during stream processing or during the main event loop.
Callback functions are all executed in the same thread, so be aware if you are executing functions that will block for extended periods of time. Typically, you should signal your own events using the Slixmpp object’s
event()
method to pass the stanza off to a threaded event handler for further processing.Parameters: - name (string) – The name of the handler.
- matcher – A
MatcherBase
derived object for matching stanza objects. - pointer – The function to execute during callback.
- thread (bool) – DEPRECATED. Remains only for backwards compatibility.
- once (bool) – Indicates if the handler should be used only once. Defaults to False.
- instream (bool) – Indicates if the callback should be executed during stream processing instead of in the main event loop.
- stream – The
XMLStream
instance this handler should monitor.
-
prerun
(payload)[source]¶ Execute the callback during stream processing, if the callback was created with
instream=True
.Parameters: payload – The matched ElementBase
object.
-
run
(payload, instream=False)[source]¶ Execute the callback function with the matched stanza payload.
Parameters: - payload – The matched
ElementBase
object. - instream (bool) – Force the handler to execute during stream
processing. This should only be used by
prerun()
. Defaults toFalse
.
- payload – The matched
CoroutineCallback¶
-
class
slixmpp.xmlstream.handler.
CoroutineCallback
(name, matcher, pointer, once=False, instream=False, stream=None)[source]¶ The Callback handler will execute a callback function with matched stanzas.
The handler may execute the callback either during stream processing or during the main event loop.
The event will be scheduled to be run soon in the event loop instead of immediately.
Parameters: - name (string) – The name of the handler.
- matcher – A
MatcherBase
derived object for matching stanza objects. - pointer – The function to execute during callback. If
pointer
is not a coroutine, this function will raise a ValueError. - once (bool) – Indicates if the handler should be used only once. Defaults to False.
- instream (bool) – Indicates if the callback should be executed during stream processing instead of in the main event loop.
- stream – The
XMLStream
instance this handler should monitor.
-
prerun
(payload)[source]¶ Execute the callback during stream processing, if the callback was created with
instream=True
.Parameters: payload – The matched ElementBase
object.
-
run
(payload, instream=False)[source]¶ Execute the callback function with the matched stanza payload.
Parameters: - payload – The matched
ElementBase
object. - instream (bool) – Force the handler to execute during stream
processing. This should only be used by
prerun()
. Defaults toFalse
.
- payload – The matched
Waiter¶
-
class
slixmpp.xmlstream.handler.
Waiter
(name, matcher, stream=None)[source]¶ The Waiter handler allows an event handler to block until a particular stanza has been received. The handler will either be given the matched stanza, or
False
if the waiter has timed out.Parameters: - name (string) – The name of the handler.
- matcher – A
MatcherBase
derived object for matching stanza objects. - stream – The
XMLStream
instance this handler should monitor.
-
prerun
(payload)[source]¶ Store the matched stanza when received during processing.
Parameters: payload – The matched ElementBase
object.
-
wait
(timeout=None)[source]¶ Block an event handler while waiting for a stanza to arrive.
Be aware that this will impact performance if called from a non-threaded event handler.
Will return either the received stanza, or
False
if the waiter timed out.Parameters: timeout (int) – The number of seconds to wait for the stanza to arrive. Defaults to the the stream’s response_timeout
value.