Merge branch 'develop' of git@github.com:fritzy/SleekXMPP into develop

5 files changed, 293 insertions, 80 deletions

diff --git a/sleekxmpp/xmlstream/handler/base.py b/sleekxmpp/xmlstream/handler/base.py
index 720846d6..3ae82a89 100644
--- a/sleekxmpp/xmlstream/handler/base.py
+++ b/sleekxmpp/xmlstream/handler/base.py
@@ -6,23 +6,82 @@
     See the file LICENSE for copying permission.
 """
 
+
 class BaseHandler(object):
 
+    """
+    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. The first is during
+    the stream processing itself. The second is after stream processing
+    and during SleekXMPP's main event loop. The prerun method is used
+    for execution during stream processing, and the run method is used
+    during the main event loop.
+
+    Attributes:
+        name   -- The name of the handler.
+        stream -- The stream this handler is assigned to.
+
+    Methods:
+        match       -- Compare a stanza with the handler's matcher.
+        prerun      -- Handler execution during stream processing.
+        run         -- Handler execution during the main event loop.
+        checkDelete -- Indicate if the handler may be removed from use.
+    """
+
+    def __init__(self, name, matcher, stream=None):
+        """
+        Create a new stream handler.
+
+        Arguments:
+            name    -- The name of the handler.
+            matcher -- A matcher object from xmlstream.matcher that will be
+                       used to determine if a stanza should be accepted by
+                       this handler.
+            stream  -- The XMLStream instance the handler should monitor.
+        """
+        self.name = name
+        self.stream = stream
+        self._destroy = False
+        self._payload = None
+        self._matcher = matcher
+        if stream is not None:
+            stream.registerHandler(self)
+
+    def match(self, xml):
+        """
+        Compare a stanza or XML object with the handler's matcher.
+
+        Arguments
+            xml -- An XML or stanza object.
+        """
+        return self._matcher.match(xml)
+
+    def prerun(self, payload):
+        """
+        Prepare the handler for execution while the XML stream is being
+        processed.
+
+        Arguments:
+            payload -- A stanza object.
+        """
+        self._payload = payload
+
+    def run(self, payload):
+        """
+        Execute the handler after XML stream processing and during the
+        main event loop.
+
+        Arguments:
+            payload -- A stanza object.
+        """
+        self._payload = payload
 
-	def __init__(self, name, matcher):
-		self.name = name
-		self._destroy = False
-		self._payload = None
-		self._matcher = matcher
-	
-	def match(self, xml):
-		return self._matcher.match(xml)
-	
-	def prerun(self, payload):
-		self._payload = payload
-
-	def run(self, payload):
-		self._payload = payload
-	
-	def checkDelete(self):
-		return self._destroy
+    def checkDelete(self):
+        """
+        Check if the handler should be removed from the list of stream
+        handlers.
+        """
+        return self._destroy
diff --git a/sleekxmpp/xmlstream/handler/callback.py b/sleekxmpp/xmlstream/handler/callback.py
index 889b0aa7..f0a72853 100644
--- a/sleekxmpp/xmlstream/handler/callback.py
+++ b/sleekxmpp/xmlstream/handler/callback.py
@@ -5,30 +5,80 @@
 
     See the file LICENSE for copying permission.
 """
-from . import base
-import logging
-
-class Callback(base.BaseHandler):
-	
-	def __init__(self, name, matcher, pointer, thread=False, once=False, instream=False):
-		base.BaseHandler.__init__(self, name, matcher)
-		self._pointer = pointer
-		self._thread = thread
-		self._once = once
-		self._instream = instream
-
-	def prerun(self, payload):
-		base.BaseHandler.prerun(self, payload)
-		if self._instream:
-			self.run(payload, True)
-	
-	def run(self, payload, instream=False):
-		if not self._instream or instream:
-			base.BaseHandler.run(self, payload)
-			#if self._thread:
-			#	x = threading.Thread(name="Callback_%s" % self.name, target=self._pointer, args=(payload,))
-			#	x.start()
-			#else:
-			self._pointer(payload)
-			if self._once:
-				self._destroy = True
+
+from sleekxmpp.xmlstream.handler.base import BaseHandler
+
+
+class Callback(BaseHandler):
+
+    """
+    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
+    SleekXMPP object's event() method to pass the stanza off to a threaded
+    event handler for further processing.
+
+    Methods:
+        prerun -- Overrides BaseHandler.prerun
+        run    -- Overrides BaseHandler.run
+    """
+
+    def __init__(self, name, matcher, pointer, thread=False,
+                 once=False, instream=False, stream=None):
+        """
+        Create a new callback handler.
+
+        Arguments:
+            name     -- The name of the handler.
+            matcher  -- A matcher object for matching stanza objects.
+            pointer  -- The function to execute during callback.
+            thread   -- DEPRECATED. Remains only for backwards compatibility.
+            once     -- Indicates if the handler should be used only
+                        once. Defaults to False.
+            instream -- 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.
+        """
+        BaseHandler.__init__(self, name, matcher, stream)
+        self._pointer = pointer
+        self._once = once
+        self._instream = instream
+
+    def prerun(self, payload):
+        """
+        Execute the callback during stream processing, if
+        the callback was created with instream=True.
+
+        Overrides BaseHandler.prerun
+
+        Arguments:
+            payload -- The matched stanza object.
+        """
+        BaseHandler.prerun(self, payload)
+        if self._instream:
+            self.run(payload, True)
+
+    def run(self, payload, instream=False):
+        """
+        Execute the callback function with the matched stanza payload.
+
+        Overrides BaseHandler.run
+
+        Arguments:
+            payload  -- The matched stanza object.
+            instream -- Force the handler to execute during
+                        stream processing. Used only by prerun.
+                        Defaults to False.
+        """
+        if not self._instream or instream:
+            BaseHandler.run(self, payload)
+            self._pointer(payload)
+            if self._once:
+                self._destroy = True
diff --git a/sleekxmpp/xmlstream/handler/waiter.py b/sleekxmpp/xmlstream/handler/waiter.py
index 7c4330a4..1e101ed3 100644
--- a/sleekxmpp/xmlstream/handler/waiter.py
+++ b/sleekxmpp/xmlstream/handler/waiter.py
@@ -5,32 +5,94 @@
 
     See the file LICENSE for copying permission.
 """
-from . import base
+
+import logging
 try:
-	import queue
+    import queue
 except ImportError:
-	import Queue as queue
-import logging
-from .. stanzabase import StanzaBase
-
-class Waiter(base.BaseHandler):
-	
-	def __init__(self, name, matcher):
-		base.BaseHandler.__init__(self, name, matcher)
-		self._payload = queue.Queue()
-	
-	def prerun(self, payload):
-		self._payload.put(payload)
-	
-	def run(self, payload):
-		pass
-
-	def wait(self, timeout=60):
-		try:
-			return self._payload.get(True, timeout)
-		except queue.Empty:
-			logging.warning("Timed out waiting for %s" % self.name)
-			return False
-	
-	def checkDelete(self):
-		return True
+    import Queue as queue
+
+from sleekxmpp.xmlstream import StanzaBase, RESPONSE_TIMEOUT
+from sleekxmpp.xmlstream.handler.base import BaseHandler
+
+
+class Waiter(BaseHandler):
+
+    """
+    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.
+
+    Methods:
+        checkDelete -- Overrides BaseHandler.checkDelete
+        prerun      -- Overrides BaseHandler.prerun
+        run         -- Overrides BaseHandler.run
+        wait        -- Wait for a stanza to arrive and return it to
+                       an event handler.
+    """
+
+    def __init__(self, name, matcher, stream=None):
+        """
+        Create a new Waiter.
+
+        Arguments:
+            name    -- The name of the waiter.
+            matcher -- A matcher object to detect the desired stanza.
+            stream  -- Optional XMLStream instance to monitor.
+        """
+        BaseHandler.__init__(self, name, matcher, stream=stream)
+        self._payload = queue.Queue()
+
+    def prerun(self, payload):
+        """
+        Store the matched stanza.
+
+        Overrides BaseHandler.prerun
+
+        Arguments:
+            payload -- The matched stanza object.
+        """
+        self._payload.put(payload)
+
+    def run(self, payload):
+        """
+        Do not process this handler during the main event loop.
+
+        Overrides BaseHandler.run
+
+        Arguments:
+            payload -- The matched stanza object.
+        """
+        pass
+
+    def wait(self, timeout=RESPONSE_TIMEOUT):
+        """
+        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.
+
+        Arguments:
+            timeout -- The number of seconds to wait for the stanza to
+                       arrive. Defaults to the global default timeout
+                       value sleekxmpp.xmlstream.RESPONSE_TIMEOUT.
+        """
+        try:
+            stanza = self._payload.get(True, timeout)
+        except queue.Empty:
+            stanza = False
+            logging.warning("Timed out waiting for %s" % self.name)
+        self.stream.removeHandler(self.name)
+        return stanza
+
+    def checkDelete(self):
+        """
+        Always remove waiters after use.
+
+        Overrides BaseHandler.checkDelete
+        """
+        return True
diff --git a/sleekxmpp/xmlstream/handler/xmlcallback.py b/sleekxmpp/xmlstream/handler/xmlcallback.py
index 67879dfe..11607ffb 100644
--- a/sleekxmpp/xmlstream/handler/xmlcallback.py
+++ b/sleekxmpp/xmlstream/handler/xmlcallback.py
@@ -5,10 +5,32 @@
 
     See the file LICENSE for copying permission.
 """
-import threading
-from . callback import Callback
+
+from sleekxmpp.xmlstream.handler import Callback
+
 
 class XMLCallback(Callback):
-	
-	def run(self, payload, instream=False):
-		Callback.run(self, payload.xml, instream)
+
+    """
+    The XMLCallback class is identical to the normal Callback class,
+    except that XML contents of matched stanzas will be processed instead
+    of the stanza objects themselves.
+
+    Methods:
+        run -- Overrides Callback.run
+    """
+
+    def run(self, payload, instream=False):
+        """
+        Execute the callback function with the matched stanza's
+        XML contents, instead of the stanza itself.
+
+        Overrides BaseHandler.run
+
+        Arguments:
+            payload  -- The matched stanza object.
+            instream -- Force the handler to execute during
+                        stream processing. Used only by prerun.
+                        Defaults to False.
+        """
+        Callback.run(self, payload.xml, instream)
diff --git a/sleekxmpp/xmlstream/handler/xmlwaiter.py b/sleekxmpp/xmlstream/handler/xmlwaiter.py
index cf90751d..5201caf3 100644
--- a/sleekxmpp/xmlstream/handler/xmlwaiter.py
+++ b/sleekxmpp/xmlstream/handler/xmlwaiter.py
@@ -5,9 +5,29 @@
 
     See the file LICENSE for copying permission.
 """
-from . waiter import Waiter
+
+from sleekxmpp.xmlstream.handler import Waiter
+
 
 class XMLWaiter(Waiter):
-	
-	def prerun(self, payload):
-		Waiter.prerun(self, payload.xml)
+
+    """
+    The XMLWaiter class is identical to the normal Waiter class
+    except that it returns the XML contents of the stanza instead
+    of the full stanza object itself.
+
+    Methods:
+        prerun -- Overrides Waiter.prerun
+    """
+
+    def prerun(self, payload):
+        """
+        Store the XML contents of the stanza to return to the
+        waiting event handler.
+
+        Overrides Waiter.prerun
+
+        Arguments:
+            payload -- The matched stanza object.
+        """
+        Waiter.prerun(self, payload.xml)