summaryrefslogtreecommitdiff
path: root/sleekxmpp/xmlstream/handler
diff options
context:
space:
mode:
authorfritzy <fritzy@ip-10-251-242-239.ec2.internal>2010-09-02 20:01:28 +0000
committerfritzy <fritzy@ip-10-251-242-239.ec2.internal>2010-09-02 20:01:28 +0000
commitd576e32f7aa28332848cdd6e39893266eded64fd (patch)
treee36a1b85dc0692b6be223f2259c3c2df9cdb5e53 /sleekxmpp/xmlstream/handler
parent6dfea828be54d9048779d06b4b31be98b58a2343 (diff)
parent4a2e7c5393da945359edc2648a2ec124481acf7d (diff)
downloadslixmpp-d576e32f7aa28332848cdd6e39893266eded64fd.tar.gz
slixmpp-d576e32f7aa28332848cdd6e39893266eded64fd.tar.bz2
slixmpp-d576e32f7aa28332848cdd6e39893266eded64fd.tar.xz
slixmpp-d576e32f7aa28332848cdd6e39893266eded64fd.zip
Merge branch 'develop' of git@github.com:fritzy/SleekXMPP into develop
Diffstat (limited to 'sleekxmpp/xmlstream/handler')
-rw-r--r--sleekxmpp/xmlstream/handler/base.py93
-rw-r--r--sleekxmpp/xmlstream/handler/callback.py104
-rw-r--r--sleekxmpp/xmlstream/handler/waiter.py116
-rw-r--r--sleekxmpp/xmlstream/handler/xmlcallback.py32
-rw-r--r--sleekxmpp/xmlstream/handler/xmlwaiter.py28
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)