summaryrefslogtreecommitdiff
path: root/sleekxmpp/plugins
diff options
context:
space:
mode:
authorLance Stout <lancestout@gmail.com>2011-06-08 10:24:25 -0700
committerLance Stout <lancestout@gmail.com>2011-06-08 10:24:25 -0700
commite219c0f9765e195770a7a0d2cdc7a1de7bb27f58 (patch)
tree3d396a8d5e068bfbbe194da80d167cd710171fd0 /sleekxmpp/plugins
parent4266ee0fa4b2520ed930047ea73d6ac82d9b1f83 (diff)
downloadslixmpp-e219c0f9765e195770a7a0d2cdc7a1de7bb27f58.tar.gz
slixmpp-e219c0f9765e195770a7a0d2cdc7a1de7bb27f58.tar.bz2
slixmpp-e219c0f9765e195770a7a0d2cdc7a1de7bb27f58.tar.xz
slixmpp-e219c0f9765e195770a7a0d2cdc7a1de7bb27f58.zip
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.
Diffstat (limited to 'sleekxmpp/plugins')
-rw-r--r--sleekxmpp/plugins/base.py66
1 files changed, 65 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