From 2586fdffda9dac5ee56664c74e71bd54ae47ee18 Mon Sep 17 00:00:00 2001
From: Lance Stout <lancestout@gmail.com>
Date: Sun, 4 Dec 2011 16:26:14 -0800
Subject: Update api docs for handlers and matchers

---
 sleekxmpp/xmlstream/handler/base.py | 85 ++++++++++++++++---------------------
 1 file changed, 36 insertions(+), 49 deletions(-)

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

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
 
-- 
cgit v1.2.3