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 (
MatcherBase
) – AMatcherBase
derived object that will be used to determine if a stanza should be accepted by this handler.stream (
Optional
[XMLStream
]) – TheXMLStream
instance that the handle will respond to.
- check_delete()[source]#
Check if the handler should be removed from the list of stream handlers.
- Return type
bool
- match(xml)[source]#
Compare a stanza or XML object with the handler’s matcher.
- Parameters
xml (
StanzaBase
) – An XML orStanzaBase
object- Return type
bool
- name: str#
The name of the handler
- prerun(payload)[source]#
Prepare the handler for execution while the XML stream is being processed.
- Parameters
payload (
StanzaBase
) – AStanzaBase
object.- Return type
- run(payload)[source]#
Execute the handler after XML stream processing and during the main event loop.
- Parameters
payload (
StanzaBase
) – AStanzaBase
object.- Return type
Callback#
- class slixmpp.xmlstream.handler.Callback(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.
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 (
MatcherBase
) – AMatcherBase
derived object for matching stanza objects.pointer (
Callable
[[StanzaBase
],Any
]) – The function to execute during callback.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 (
Optional
[XMLStream
]) – TheXMLStream
instance this handler should monitor.
- prerun(payload)[source]#
Execute the callback during stream processing, if the callback was created with
instream=True
.- Parameters
payload (
StanzaBase
) – The matchedStanzaBase
object.- Return type
- run(payload, instream=False)[source]#
Execute the callback function with the matched stanza payload.
- Parameters
payload (
StanzaBase
) – The matchedStanzaBase
object.instream (bool) – Force the handler to execute during stream processing. This should only be used by
prerun()
. Defaults toFalse
.
- Return type
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 (
MatcherBase
) – AMatcherBase
derived object for matching stanza objects.pointer (
Callable
[[StanzaBase
],Awaitable
[None
]]) – The function to execute during callback. Ifpointer
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 (
Optional
[XMLStream
]) – TheXMLStream
instance this handler should monitor.
- prerun(payload)[source]#
Execute the callback during stream processing, if the callback was created with
instream=True
.- Parameters
payload (
StanzaBase
) – The matchedStanzaBase
object.- Return type
- run(payload, instream=False)[source]#
Execute the callback function with the matched stanza payload.
- Parameters
payload (
StanzaBase
) – The matchedStanzaBase
object.instream (bool) – Force the handler to execute during stream processing. This should only be used by
prerun()
. Defaults toFalse
.
- Return type
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 (
MatcherBase
) – AMatcherBase
derived object for matching stanza objects.stream (
Optional
[XMLStream
]) – TheXMLStream
instance this handler should monitor.
- prerun(payload)[source]#
Store the matched stanza when received during processing.
- Parameters
payload (
StanzaBase
) – The matchedStanzaBase
object.- Return type
- async 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.- Return type
Optional
[StanzaBase
]