sleekxmpp/xmlstream/handler/callback.py

   1 # -*- coding: utf-8 -*-
   2 """
   3     sleekxmpp.xmlstream.handler.callback
   4     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   5
   6     Part of SleekXMPP: The Sleek XMPP Library
   7
   8     :copyright: (c) 2011 Nathanael C. Fritz
   9     :license: MIT, see LICENSE for more details
  10 """
  11
  12 from sleekxmpp.xmlstream.handler.base import BaseHandler
  13
  14
  15 class Callback(BaseHandler):
  16
  17     """
  18     The Callback handler will execute a callback function with
  19     matched stanzas.
  20
  21     The handler may execute the callback either during stream
  22     processing or during the main event loop.
  23
  24     Callback functions are all executed in the same thread, so be aware if
  25     you are executing functions that will block for extended periods of
  26     time. Typically, you should signal your own events using the SleekXMPP
  27     object's :meth:`~sleekxmpp.xmlstream.xmlstream.XMLStream.event()`
  28     method to pass the stanza off to a threaded event handler for further
  29     processing.
  30
  31
  32     :param string name: The name of the handler.
  33     :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
  34                     derived object for matching stanza objects.
  35     :param pointer: The function to execute during callback.
  36     :param bool thread: **DEPRECATED.** Remains only for
  37                         backwards compatibility.
  38     :param bool once: Indicates if the handler should be used only
  39                       once. Defaults to False.
  40     :param bool instream: Indicates if the callback should be executed
  41                           during stream processing instead of in the
  42                           main event loop.
  43     :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
  44                    instance this handler should monitor.
  45     """
  46
  47     def __init__(self, name, matcher, pointer, thread=False,
  48                  once=False, instream=False, stream=None):
  49         BaseHandler.__init__(self, name, matcher, stream)
  50         self._pointer = pointer
  51         self._once = once
  52         self._instream = instream
  53
  54     def prerun(self, payload):
  55         """Execute the callback during stream processing, if
  56         the callback was created with ``instream=True``.
  57
  58         :param payload: The matched
  59             :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
  60         """
  61         if self._once:
  62             self._destroy = True
  63         if self._instream:
  64             self.run(payload, True)
  65
  66     def run(self, payload, instream=False):
  67         """Execute the callback function with the matched stanza payload.
  68
  69         :param payload: The matched
  70             :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
  71         :param bool instream: Force the handler to execute during stream
  72                               processing. This should only be used by
  73                               :meth:`prerun()`. Defaults to ``False``.
  74         """
  75         if not self._instream or instream:
  76             self._pointer(payload)
  77             if self._once:
  78                 self._destroy = True
  79                 del self._pointer