Added session_end event and some docs.

For now, session_end is the same as disconnected, but once support is
added later for stream management, the two events will become distinct.

Plugins should add handlers for session_end for cleaning any session
state.

2 files changed, 66 insertions, 1 deletions

diff --git a/sleekxmpp/plugins/base.py b/sleekxmpp/plugins/base.py
index 254397e8..2dd68c8d 100644
--- a/sleekxmpp/plugins/base.py
+++ b/sleekxmpp/plugins/base.py
@@ -9,7 +9,63 @@
 
 class base_plugin(object):
 
-    def __init__(self, xmpp, config):
+    """
+    The base_plugin class serves as a base for user created plugins
+    that provide support for existing or experimental XEPS.
+
+    Each plugin has a dictionary for configuration options, as well
+    as a name and description.
+
+    The lifecycle of a plugin is:
+        1. The plugin is instantiated during registration.
+        2. Once the XML stream begins processing, the method
+           plugin_init() is called (if the plugin is configured
+           as enabled with {'enable': True}).
+        3. After all plugins have been initialized, the
+           method post_init() is called.
+
+    Recommended event handlers:
+        session_start -- Plugins which require the use of the current
+                         bound JID SHOULD wait for the session_start
+                         event to perform any initialization (or
+                         resetting). This is a transitive recommendation,
+                         plugins that use other plugins which use the
+                         bound JID should also wait for session_start
+                         before making such calls.
+        session_end   -- If the plugin keeps any per-session state,
+                         such as joined MUC rooms, such state SHOULD
+                         be cleared when the session_end event is raised.
+
+    Attributes:
+        xep          -- The XEP number the plugin implements, if any.
+        description  -- A short description of the plugin, typically
+                        the long name of the implemented XEP.
+        xmpp         -- The main SleekXMPP instance.
+        config       -- A dictionary of custom configuration values.
+                        The value 'enable' is special and controls
+                        whether or not the plugin is initialized
+                        after registration.
+        post_initted -- Executed after all plugins have been initialized
+                        to handle any cross-plugin interactions, such as
+                        registering service discovery items.
+        enable       -- Indicates that the plugin is enabled for use and
+                        will be initialized after registration.
+
+    Methods:
+        plugin_init  -- Initialize the plugin state.
+        post_init    -- Handle any cross-plugin concerns.
+    """
+
+    def __init__(self, xmpp, config=None):
+        """
+        Instantiate a new plugin and store the given configuration.
+
+        Arguments:
+            xmpp   -- The main SleekXMPP instance.
+            config -- A dictionary of configuration values.
+        """
+        if config is None:
+            config = {}
         self.xep = 'base'
         self.description = 'Base Plugin'
         self.xmpp = xmpp
@@ -20,7 +76,15 @@ class base_plugin(object):
             self.plugin_init()
 
     def plugin_init(self):
+        """
+        Initialize plugin state, such as registering any stream or
+        event handlers, or new stanza types.
+        """
         pass
 
     def post_init(self):
+        """
+        Perform any cross-plugin interactions, such as registering
+        service discovery identities or items.
+        """
         self.post_inited = True
diff --git a/sleekxmpp/xmlstream/xmlstream.py b/sleekxmpp/xmlstream/xmlstream.py
index fd313536..5bc71f04 100644
--- a/sleekxmpp/xmlstream/xmlstream.py
+++ b/sleekxmpp/xmlstream/xmlstream.py
@@ -389,6 +389,7 @@ class XMLStream(object):
             self.event('socket_error', serr)
         finally:
             #clear your application state
+            self.event('session_end', direct=True)
             self.event("disconnected", direct=True)
             return True