Stanza Handlers

1.5 Documentation

«  Stanza Objects   ::   Contents   ::   Stanza Matchers  »

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 – 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.
check_delete()[source]

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

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 to False.

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 to False.

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.
check_delete()[source]

Always remove waiters after use.

prerun(payload)[source]

Store the matched stanza when received during processing.

Parameters:payload – The matched ElementBase object.
run(payload)[source]

Do not process this handler during the main event loop.

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.

«  Stanza Objects   ::   Contents   ::   Stanza Matchers  »