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, and run() is called during the second.

Parameters
  • name (string) – The name of the handler.

  • matcher (MatcherBase) – A MatcherBase derived object that will be used to determine if a stanza should be accepted by this handler.

  • stream (Optional[XMLStream]) – The XMLStream 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 or StanzaBase 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) – A StanzaBase object.

Return type

None

run(payload)[source]#

Execute the handler after XML stream processing and during the main event loop.

Parameters

payload (StanzaBase) – A StanzaBase object.

Return type

None

stream: Optional[ReferenceType[XMLStream]]#

The XML stream this handler is assigned to

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) – A MatcherBase 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]) – 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 (StanzaBase) – The matched StanzaBase object.

Return type

None

run(payload, instream=False)[source]#

Execute the callback function with the matched stanza payload.

Parameters
  • payload (StanzaBase) – The matched StanzaBase object.

  • instream (bool) – Force the handler to execute during stream processing. This should only be used by prerun(). Defaults to False.

Return type

None

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) – A MatcherBase derived object for matching stanza objects.

  • pointer (Callable[[StanzaBase], Awaitable[None]]) – 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 (Optional[XMLStream]) – 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 (StanzaBase) – The matched StanzaBase object.

Return type

None

run(payload, instream=False)[source]#

Execute the callback function with the matched stanza payload.

Parameters
  • payload (StanzaBase) – The matched StanzaBase object.

  • instream (bool) – Force the handler to execute during stream processing. This should only be used by prerun(). Defaults to False.

Return type

None

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) – A MatcherBase derived object for matching stanza objects.

  • stream (Optional[XMLStream]) – The XMLStream instance this handler should monitor.

check_delete()[source]#

Always remove waiters after use.

Return type

bool

prerun(payload)[source]#

Store the matched stanza when received during processing.

Parameters

payload (StanzaBase) – The matched StanzaBase object.

Return type

None

run(payload)[source]#

Do not process this handler during the main event loop.

Return type

None

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]