Update api docs for handlers and matchers

11 files changed, 228 insertions, 205 deletions

diff --git a/docs/api/xmlstream/handler.rst b/docs/api/xmlstream/handler.rst
new file mode 100644
index 00000000..33c0bf42
--- /dev/null
+++ b/docs/api/xmlstream/handler.rst
@@ -0,0 +1,24 @@
+Stanza Handlers
+===============
+
+The Basic Handler
+-----------------
+.. module:: sleekxmpp.xmlstream.handler.base
+
+.. autoclass:: BaseHandler
+    :members:
+
+Callback
+--------
+.. module:: sleekxmpp.xmlstream.handler.callback
+
+.. autoclass:: Callback
+    :members:
+
+
+Waiter
+------
+.. module:: sleekxmpp.xmlstream.handler.waiter
+
+.. autoclass:: Waiter
+    :members:
diff --git a/docs/api/jid.rst b/docs/api/xmlstream/jid.rst
index 22a2db45..22a2db45 100644
--- a/docs/api/jid.rst
+++ b/docs/api/xmlstream/jid.rst
diff --git a/docs/api/xmlstream/matcher.rst b/docs/api/xmlstream/matcher.rst
new file mode 100644
index 00000000..df3591bc
--- /dev/null
+++ b/docs/api/xmlstream/matcher.rst
@@ -0,0 +1,41 @@
+Stanza Matchers
+===============
+
+The Basic Matcher
+-----------------
+.. module:: sleekxmpp.xmlstream.matcher.base
+
+.. autoclass:: MatcherBase
+    :members:
+
+
+ID Matching
+-----------
+.. module:: sleekxmpp.xmlstream.matcher.id
+
+.. autoclass:: MatcherId
+    :members:
+
+
+Stanza Path Matching
+--------------------
+.. module:: sleekxmpp.xmlstream.matcher.stanzapath
+
+.. autoclass:: StanzaPath
+    :members:
+
+
+XPath
+-----
+.. module:: sleekxmpp.xmlstream.matcher.xpath
+
+.. autoclass:: MatchXPath
+    :members:
+
+
+XMLMask
+-------
+.. module:: sleekxmpp.xmlstream.matcher.xmlmask
+
+.. autoclass:: MatchXMLMask
+    :members:
diff --git a/docs/index.rst b/docs/index.rst
index 76c3741e..5d2577d2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -112,8 +112,10 @@ API Reference
     api/clientxmpp
     api/componentxmpp
     api/basexmpp
-    api/jid
+    api/xmlstream/jid
     api/xmlstream/stanzabase
+    api/xmlstream/handler
+    api/xmlstream/matcher
     api/xmlstream/tostring
     api/xmlstream/filesocket
 
diff --git a/sleekxmpp/xmlstream/handler/base.py b/sleekxmpp/xmlstream/handler/base.py
index 7f05c757..59dcb306 100644
--- a/sleekxmpp/xmlstream/handler/base.py
+++ b/sleekxmpp/xmlstream/handler/base.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.handler.base
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 import weakref
@@ -16,78 +19,62 @@ class BaseHandler(object):
     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.
-        check_delete -- Indicate if the handler may be removed from use.
+    Handler execution may take place in two phases: during the incoming
+    stream processing, and in the main event loop. The :meth:`prerun()`
+    method is executed in the first case, and :meth:`run()` is called
+    during the second.
+
+    :param string name: The name of the handler.
+    :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+                    derived object that will be used to determine if a
+                    stanza should be accepted by this handler.
+    :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+                    instance that the handle will respond to.
     """
 
     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.
-        """
+        #: The name of the handler
         self.name = name
+
+        #: The XML stream this handler is assigned to
+        self.stream = None
         if stream is not None:
             self.stream = weakref.ref(stream)
-        else:
-            self.stream = None
+            stream.register_handler(self)
+
         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.
+        """Compare a stanza or XML object with the handler's matcher.
 
-        Arguments
-            xml -- An XML or stanza object.
+        :param xml: An XML or 
+            :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object
         """
         return self._matcher.match(xml)
 
     def prerun(self, payload):
-        """
-        Prepare the handler for execution while the XML stream is being
-        processed.
+        """Prepare the handler for execution while the XML
+        stream is being processed.
 
-        Arguments:
-            payload -- A stanza object.
+        :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                        object.
         """
         self._payload = payload
 
     def run(self, payload):
-        """
-        Execute the handler after XML stream processing and during the
+        """Execute the handler after XML stream processing and during the
         main event loop.
 
-        Arguments:
-            payload -- A stanza object.
+        :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                        object.
         """
         self._payload = payload
 
     def check_delete(self):
-        """
-        Check if the handler should be removed from the list of stream
-        handlers.
+        """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 7fadab43..37f53335 100644
--- a/sleekxmpp/xmlstream/handler/callback.py
+++ b/sleekxmpp/xmlstream/handler/callback.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.handler.callback
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 from sleekxmpp.xmlstream.handler.base import BaseHandler
@@ -18,48 +21,42 @@ class Callback(BaseHandler):
     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
+    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 :meth:`~sleekxmpp.xmlstream.xmlstream.XMLStream.event()`
+    method to pass the stanza off to a threaded event handler for further
+    processing.
+
+
+    :param string name: The name of the handler.
+    :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+                    derived object for matching stanza objects.
+    :param pointer: The function to execute during callback.
+    :param bool thread: **DEPRECATED.** Remains only for 
+                        backwards compatibility.
+    :param bool once: Indicates if the handler should be used only
+                      once. Defaults to False.
+    :param bool instream: Indicates if the callback should be executed
+                          during stream processing instead of in the
+                          main event loop.
+    :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+                   instance this handler should monitor.
     """
 
     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
+        """Execute the callback during stream processing, if
+        the callback was created with ``instream=True``.
 
-        Arguments:
-            payload -- The matched stanza object.
+        :param payload: The matched
+            :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
         """
         if self._once:
             self._destroy = True
@@ -67,16 +64,13 @@ class Callback(BaseHandler):
             self.run(payload, True)
 
     def run(self, payload, instream=False):
-        """
-        Execute the callback function with the matched stanza payload.
-
-        Overrides BaseHandler.run
+        """Execute the callback function with the matched stanza payload.
 
-        Arguments:
-            payload  -- The matched stanza object.
-            instream -- Force the handler to execute during
-                        stream processing. Used only by prerun.
-                        Defaults to False.
+        :param payload: The matched
+            :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
+        :param bool instream: Force the handler to execute during stream
+                              processing. This should only be used by
+                              :meth:`prerun()`. Defaults to ``False``.
         """
         if not self._instream or instream:
             self._pointer(payload)
diff --git a/sleekxmpp/xmlstream/handler/waiter.py b/sleekxmpp/xmlstream/handler/waiter.py
index a64b6a9b..01ff5d67 100644
--- a/sleekxmpp/xmlstream/handler/waiter.py
+++ b/sleekxmpp/xmlstream/handler/waiter.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.handler.waiter
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 import logging
@@ -22,67 +25,46 @@ log = logging.getLogger(__name__)
 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:
-        check_delete -- Overrides BaseHandler.check_delete
-        prerun       -- Overrides BaseHandler.prerun
-        run          -- Overrides BaseHandler.run
-        wait         -- Wait for a stanza to arrive and return it to
-                        an event handler.
+    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.
+
+    :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):
-        """
-        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
+        """Store the matched stanza when received during processing.
 
-        Arguments:
-            payload -- The matched stanza object.
+        :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.
-
-        Overrides BaseHandler.run
-
-        Arguments:
-            payload -- The matched stanza object.
-        """
+        """Do not process this handler during the main event loop."""
         pass
 
     def wait(self, timeout=None):
-        """
-        Block an event handler while waiting for a stanza to arrive.
+        """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.
+        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.
+        :param int timeout: The number of seconds to wait for the stanza
+            to arrive. Defaults to the the stream's
+            :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream.response_timeout`
+            value.
         """
         if timeout is None:
             timeout = self.stream().response_timeout
@@ -101,9 +83,5 @@ class Waiter(BaseHandler):
         return stanza
 
     def check_delete(self):
-        """
-        Always remove waiters after use.
-
-        Overrides BaseHandler.check_delete
-        """
+        """Always remove waiters after use."""
         return True
diff --git a/sleekxmpp/xmlstream/matcher/base.py b/sleekxmpp/xmlstream/matcher/base.py
index 701ab32f..83c26688 100644
--- a/sleekxmpp/xmlstream/matcher/base.py
+++ b/sleekxmpp/xmlstream/matcher/base.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.matcher.base
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 
@@ -13,21 +16,15 @@ class MatcherBase(object):
     Base class for stanza matchers. Stanza matchers are used to pick
     stanzas out of the XML stream and pass them to the appropriate
     stream handlers.
+
+    :param criteria: Object to compare some aspect of a stanza against.
     """
 
     def __init__(self, criteria):
-        """
-        Create a new stanza matcher.
-
-        Arguments:
-            criteria -- Object to compare some aspect of a stanza
-                        against.
-        """
         self._criteria = criteria
 
     def match(self, xml):
-        """
-        Check if a stanza matches the stored criteria.
+        """Check if a stanza matches the stored criteria.
 
         Meant to be overridden.
         """
diff --git a/sleekxmpp/xmlstream/matcher/id.py b/sleekxmpp/xmlstream/matcher/id.py
index 0c8ce2d8..11ab70bb 100644
--- a/sleekxmpp/xmlstream/matcher/id.py
+++ b/sleekxmpp/xmlstream/matcher/id.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.matcher.id
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 from sleekxmpp.xmlstream.matcher.base import MatcherBase
@@ -14,19 +17,13 @@ class MatcherId(MatcherBase):
     """
     The ID matcher selects stanzas that have the same stanza 'id'
     interface value as the desired ID.
-
-    Methods:
-        match -- Overrides MatcherBase.match.
     """
 
     def match(self, xml):
-        """
-        Compare the given stanza's 'id' attribute to the stored
-        id value.
-
-        Overrides MatcherBase.match.
+        """Compare the given stanza's ``'id'`` attribute to the stored
+        ``id`` value.
 
-        Arguments:
-            xml -- The stanza to compare against.
+        :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                    stanza to compare against.
         """
         return xml['id'] == self._criteria
diff --git a/sleekxmpp/xmlstream/matcher/stanzapath.py b/sleekxmpp/xmlstream/matcher/stanzapath.py
index f8ff283d..61c5332c 100644
--- a/sleekxmpp/xmlstream/matcher/stanzapath.py
+++ b/sleekxmpp/xmlstream/matcher/stanzapath.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.matcher.stanzapath
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 from sleekxmpp.xmlstream.matcher.base import MatcherBase
@@ -15,24 +18,17 @@ class StanzaPath(MatcherBase):
     The StanzaPath matcher selects stanzas that match a given "stanza path",
     which is similar to a normal XPath except that it uses the interfaces and
     plugins of the stanza instead of the actual, underlying XML.
-
-    In most cases, the stanza path and XPath should be identical, but be
-    aware that differences may occur.
-
-    Methods:
-        match -- Overrides MatcherBase.match.
     """
 
     def match(self, stanza):
         """
         Compare a stanza against a "stanza path". A stanza path is similar to
         an XPath expression, but uses the stanza's interfaces and plugins
-        instead of the underlying XML. For most cases, the stanza path and
-        XPath should be identical, but be aware that differences may occur.
-
-        Overrides MatcherBase.match.
+        instead of the underlying XML. See the documentation for the stanza
+        :meth:`~sleekxmpp.xmlstream.stanzabase.ElementBase.match()` method
+        for more information.
 
-        Arguments:
-            stanza -- The stanza object to compare against.
+        :param stanza: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                       stanza to compare against.
         """
         return stanza.match(self._criteria)
diff --git a/sleekxmpp/xmlstream/matcher/xpath.py b/sleekxmpp/xmlstream/matcher/xpath.py
index 669c9f16..b6af0609 100644
--- a/sleekxmpp/xmlstream/matcher/xpath.py
+++ b/sleekxmpp/xmlstream/matcher/xpath.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.matcher.xpath
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 from sleekxmpp.xmlstream.stanzabase import ET
@@ -22,30 +25,34 @@ class MatchXPath(MatcherBase):
     The XPath matcher selects stanzas whose XML contents matches a given
     XPath expression.
 
-    Note that using this matcher may not produce expected behavior when using
-    attribute selectors. For Python 2.6 and 3.1, the ElementTree find method
-    does not support the use of attribute selectors. If you need to support
-    Python 2.6 or 3.1, it might be more useful to use a StanzaPath matcher.
+    .. warning::
 
-    If the value of IGNORE_NS is set to true, then XPath expressions will
-    be matched without using namespaces.
+        Using this matcher may not produce expected behavior when using
+        attribute selectors. For Python 2.6 and 3.1, the ElementTree
+        :meth:`~xml.etree.ElementTree.Element.find()` method does
+        not support the use of attribute selectors. If you need to
+        support Python 2.6 or 3.1, it might be more useful to use a
+        :class:`~sleekxmpp.xmlstream.matcher.stanzapath.StanzaPath` matcher.
 
-    Methods:
-        match -- Overrides MatcherBase.match.
+    If the value of :data:`IGNORE_NS` is set to ``True``, then XPath
+    expressions will be matched without using namespaces.
     """
 
     def match(self, xml):
         """
         Compare a stanza's XML contents to an XPath expression.
 
-        If the value of IGNORE_NS is set to true, then XPath expressions
-        will be matched without using namespaces.
+        If the value of :data:`IGNORE_NS` is set to ``True``, then XPath
+        expressions will be matched without using namespaces.
+
+        .. warning::
 
-        Note that in Python 2.6 and 3.1 the ElementTree find method does
-        not support attribute selectors in the XPath expression.
+            In Python 2.6 and 3.1 the ElementTree
+            :meth:`~xml.etree.ElementTree.Element.find()` method does not
+            support attribute selectors in the XPath expression.
 
-        Arguments:
-            xml -- The stanza object to compare against.
+        :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                    stanza to compare against.
         """
         if hasattr(xml, 'xml'):
             xml = xml.xml