Skip to content
Back to top
View this page

# Stanza Handlers

## The Basic Handler

class slixmpp.xmlstream.handler.base.BaseHandler(name, matcher, stream=None)

  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 (`XMLStream` | `None`) – The `XMLStream` instance that the handle will respond to.

  check_delete()

    Check if the handler should be removed from the list of stream handlers.

    Return type:

      `bool`

  match(xml)

    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)

    Prepare the handler for execution while the XML stream is being processed.

    Parameters:

      payload (`StanzaBase`) – A `StanzaBase` object.

    Return type:

      `None`

  run(payload)

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

    Parameters:

      payload (`StanzaBase`) – A `StanzaBase` object.

    Return type:

      `None`

  stream: `ReferenceType`[`XMLStream`] | `None`

    The XML stream this handler is assigned to

## Callback

class slixmpp.xmlstream.handler.Callback(name, matcher, pointer, once=False, instream=False, stream=None)

  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 (`XMLStream` | `None`) – The `XMLStream` instance this handler should monitor.

  prerun(payload)

    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)

    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)

  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 (`XMLStream` | `None`) – The `XMLStream` instance this handler should monitor.

  prerun(payload)

    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)

    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)

  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 (`XMLStream` | `None`) – The `XMLStream` instance this handler should monitor.

  check_delete()

    Always remove waiters after use.

    Return type:

      `bool`

  prerun(payload)

    Store the matched stanza when received during processing.

    Parameters:

      payload (`StanzaBase`) – The matched `StanzaBase` object.

    Return type:

      `None`

  run(payload)

    Do not process this handler during the main event loop.

    Return type:

      `None`

  async wait(timeout=None)

    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:

      `StanzaBase` | `None`