From 89fb15e8962640a34e24418216e156188032bfa8 Mon Sep 17 00:00:00 2001
From: Lance Stout <lancestout@gmail.com>
Date: Fri, 27 Aug 2010 16:42:26 -0400
Subject: Updated the suite of handler classes with documentation.

Updated XMLStream to return True or False from removeHandler to indicate if the handler
existed and was removed.

Waiter handlers now unregister themselves after timing out.
---
 sleekxmpp/xmlstream/handler/callback.py | 104 +++++++++++++++++++++++---------
 1 file changed, 77 insertions(+), 27 deletions(-)

(limited to 'sleekxmpp/xmlstream/handler/callback.py')

diff --git a/sleekxmpp/xmlstream/handler/callback.py b/sleekxmpp/xmlstream/handler/callback.py
index 889b0aa7..04a4eeda 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.
+            threaded -- 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
-- 
cgit v1.2.3


From f5ae27da4f542670560a4ecc0373d7001366b496 Mon Sep 17 00:00:00 2001
From: Lance Stout <lancestout@gmail.com>
Date: Fri, 27 Aug 2010 18:16:09 -0400
Subject: Fix some documentation typos.

---
 sleekxmpp/xmlstream/handler/callback.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'sleekxmpp/xmlstream/handler/callback.py')

diff --git a/sleekxmpp/xmlstream/handler/callback.py b/sleekxmpp/xmlstream/handler/callback.py
index 04a4eeda..f0a72853 100644
--- a/sleekxmpp/xmlstream/handler/callback.py
+++ b/sleekxmpp/xmlstream/handler/callback.py
@@ -38,7 +38,7 @@ class Callback(BaseHandler):
             name     -- The name of the handler.
             matcher  -- A matcher object for matching stanza objects.
             pointer  -- The function to execute during callback.
-            threaded -- DEPRECATED. Remains only for backwards compatibility.
+            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
-- 
cgit v1.2.3