Add Collector stanza handler class.

This style of handler is necessary for capturing result sets from
queries that use multiple messages to send the results instead of
in a single result stanza. Notably, XEP-0313 (MAM).

sleekxmpp/xmlstream/handler/__init__.py

@@ -7,6 +7,7 @@
 """
 
 from sleekxmpp.xmlstream.handler.callback import Callback
+from sleekxmpp.xmlstream.handler.collector import Collector
 from sleekxmpp.xmlstream.handler.waiter import Waiter
 from sleekxmpp.xmlstream.handler.xmlcallback import XMLCallback
 from sleekxmpp.xmlstream.handler.xmlwaiter import XMLWaiter

sleekxmpp/xmlstream/handler/collector.py

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+"""
+    sleekxmpp.xmlstream.handler.collector
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2012 Nathanael C. Fritz, Lance J.T. Stout
+    :license: MIT, see LICENSE for more details
+"""
+
+import logging
+
+from sleekxmpp.util import Queue, QueueEmpty
+from sleekxmpp.xmlstream.handler.base import BaseHandler
+
+
+log = logging.getLogger(__name__)
+
+
+class Collector(BaseHandler):
+
+    """
+    The Collector handler allows for collecting a set of stanzas
+    that match a given pattern. Unlike the Waiter handler, a
+    Collector does not block execution, and will continue to
+    accumulate matching stanzas until told to stop.
+
+    :param string name: The name of the handler.
+    :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+                    derived object for matching stanza objects.
+    :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+                   instance this handler should monitor.
+    """
+
+    def __init__(self, name, matcher, stream=None):
+        BaseHandler.__init__(self, name, matcher, stream=stream)
+        self._payload = Queue()
+
+    def prerun(self, payload):
+        """Store the matched stanza when received during processing.
+
+        :param payload: The matched
+            :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
+        """
+        self._payload.put(payload)
+
+    def run(self, payload):
+        """Do not process this handler during the main event loop."""
+        pass
+
+    def stop(self):
+        """
+        Stop collection of matching stanzas, and return the ones that
+        have been stored so far.
+        """
+        self._destroy = True
+        results = []
+        try:
+            while True:
+                results.append(self._payload.get(False))
+        except QueueEmpty:
+            pass
+
+        self.stream().remove_handler(self.name)
+        return results