diff options
Diffstat (limited to 'sleekxmpp/plugins')
| -rw-r--r-- | sleekxmpp/plugins/base.py | 66 |
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 |