summaryrefslogtreecommitdiff
path: root/sleekxmpp/plugins/base.py
diff options
context:
space:
mode:
authorFlorent Le Coz <louiz@louiz.org>2014-07-17 14:19:04 +0200
committerFlorent Le Coz <louiz@louiz.org>2014-07-17 14:19:04 +0200
commit5ab77c745270d7d5c016c1dc7ef2a82533a4b16e (patch)
tree259377cc666f8b9c7954fc4e7b8f7a912bcfe101 /sleekxmpp/plugins/base.py
parente5582694c07236e6830c20361840360a1dde37f3 (diff)
downloadslixmpp-5ab77c745270d7d5c016c1dc7ef2a82533a4b16e.tar.gz
slixmpp-5ab77c745270d7d5c016c1dc7ef2a82533a4b16e.tar.bz2
slixmpp-5ab77c745270d7d5c016c1dc7ef2a82533a4b16e.tar.xz
slixmpp-5ab77c745270d7d5c016c1dc7ef2a82533a4b16e.zip
Rename to slixmpp
Diffstat (limited to 'sleekxmpp/plugins/base.py')
-rw-r--r--sleekxmpp/plugins/base.py360
1 files changed, 0 insertions, 360 deletions
diff --git a/sleekxmpp/plugins/base.py b/sleekxmpp/plugins/base.py
deleted file mode 100644
index 67675908..00000000
--- a/sleekxmpp/plugins/base.py
+++ /dev/null
@@ -1,360 +0,0 @@
-# -*- encoding: utf-8 -*-
-
-"""
- sleekxmpp.plugins.base
- ~~~~~~~~~~~~~~~~~~~~~~
-
- This module provides XMPP functionality that
- is specific to client connections.
-
- Part of SleekXMPP: The Sleek XMPP Library
-
- :copyright: (c) 2012 Nathanael C. Fritz
- :license: MIT, see LICENSE for more details
-"""
-
-import sys
-import copy
-import logging
-import threading
-
-
-if sys.version_info >= (3, 0):
- unicode = str
-
-
-log = logging.getLogger(__name__)
-
-
-#: Associate short string names of plugins with implementations. The
-#: plugin names are based on the spec used by the plugin, such as
-#: `'xep_0030'` for a plugin that implements XEP-0030.
-PLUGIN_REGISTRY = {}
-
-#: In order to do cascading plugin disabling, reverse dependencies
-#: must be tracked.
-PLUGIN_DEPENDENTS = {}
-
-#: Only allow one thread to manipulate the plugin registry at a time.
-REGISTRY_LOCK = threading.RLock()
-
-
-class PluginNotFound(Exception):
- """Raised if an unknown plugin is accessed."""
-
-
-def register_plugin(impl, name=None):
- """Add a new plugin implementation to the registry.
-
- :param class impl: The plugin class.
-
- The implementation class must provide a :attr:`~BasePlugin.name`
- value that will be used as a short name for enabling and disabling
- the plugin. The name should be based on the specification used by
- the plugin. For example, a plugin implementing XEP-0030 would be
- named `'xep_0030'`.
- """
- if name is None:
- name = impl.name
- with REGISTRY_LOCK:
- PLUGIN_REGISTRY[name] = impl
- if name not in PLUGIN_DEPENDENTS:
- PLUGIN_DEPENDENTS[name] = set()
- for dep in impl.dependencies:
- if dep not in PLUGIN_DEPENDENTS:
- PLUGIN_DEPENDENTS[dep] = set()
- PLUGIN_DEPENDENTS[dep].add(name)
-
-
-def load_plugin(name, module=None):
- """Find and import a plugin module so that it can be registered.
-
- This function is called to import plugins that have selected for
- enabling, but no matching registered plugin has been found.
-
- :param str name: The name of the plugin. It is expected that
- plugins are in packages matching their name,
- even though the plugin class name does not
- have to match.
- :param str module: The name of the base module to search
- for the plugin.
- """
- try:
- if not module:
- try:
- module = 'sleekxmpp.plugins.%s' % name
- __import__(module)
- mod = sys.modules[module]
- except ImportError:
- module = 'sleekxmpp.features.%s' % name
- __import__(module)
- mod = sys.modules[module]
- elif isinstance(module, (str, unicode)):
- __import__(module)
- mod = sys.modules[module]
- else:
- mod = module
-
- # Add older style plugins to the registry.
- if hasattr(mod, name):
- plugin = getattr(mod, name)
- if hasattr(plugin, 'xep') or hasattr(plugin, 'rfc'):
- plugin.name = name
- # Mark the plugin as an older style plugin so
- # we can work around dependency issues.
- plugin.old_style = True
- register_plugin(plugin, name)
- except ImportError:
- log.exception("Unable to load plugin: %s", name)
-
-
-class PluginManager(object):
- def __init__(self, xmpp, config=None):
- #: We will track all enabled plugins in a set so that we
- #: can enable plugins in batches and pull in dependencies
- #: without problems.
- self._enabled = set()
-
- #: Maintain references to active plugins.
- self._plugins = {}
-
- self._plugin_lock = threading.RLock()
-
- #: Globally set default plugin configuration. This will
- #: be used for plugins that are auto-enabled through
- #: dependency loading.
- self.config = config if config else {}
-
- self.xmpp = xmpp
-
- def register(self, plugin, enable=True):
- """Register a new plugin, and optionally enable it.
-
- :param class plugin: The implementation class of the plugin
- to register.
- :param bool enable: If ``True``, immediately enable the
- plugin after registration.
- """
- register_plugin(plugin)
- if enable:
- self.enable(plugin.name)
-
- def enable(self, name, config=None, enabled=None):
- """Enable a plugin, including any dependencies.
-
- :param string name: The short name of the plugin.
- :param dict config: Optional settings dictionary for
- configuring plugin behaviour.
- """
- top_level = False
- if enabled is None:
- enabled = set()
-
- with self._plugin_lock:
- if name not in self._enabled:
- enabled.add(name)
- self._enabled.add(name)
- if not self.registered(name):
- load_plugin(name)
-
- plugin_class = PLUGIN_REGISTRY.get(name, None)
- if not plugin_class:
- raise PluginNotFound(name)
-
- if config is None:
- config = self.config.get(name, None)
-
- plugin = plugin_class(self.xmpp, config)
- self._plugins[name] = plugin
- for dep in plugin.dependencies:
- self.enable(dep, enabled=enabled)
- plugin._init()
-
- if top_level:
- for name in enabled:
- if hasattr(self.plugins[name], 'old_style'):
- # Older style plugins require post_init()
- # to run just before stream processing begins,
- # so we don't call it here.
- pass
- self.plugins[name].post_init()
-
- def enable_all(self, names=None, config=None):
- """Enable all registered plugins.
-
- :param list names: A list of plugin names to enable. If
- none are provided, all registered plugins
- will be enabled.
- :param dict config: A dictionary mapping plugin names to
- configuration dictionaries, as used by
- :meth:`~PluginManager.enable`.
- """
- names = names if names else PLUGIN_REGISTRY.keys()
- if config is None:
- config = {}
- for name in names:
- self.enable(name, config.get(name, {}))
-
- def enabled(self, name):
- """Check if a plugin has been enabled.
-
- :param string name: The name of the plugin to check.
- :return: boolean
- """
- return name in self._enabled
-
- def registered(self, name):
- """Check if a plugin has been registered.
-
- :param string name: The name of the plugin to check.
- :return: boolean
- """
- return name in PLUGIN_REGISTRY
-
- def disable(self, name, _disabled=None):
- """Disable a plugin, including any dependent upon it.
-
- :param string name: The name of the plugin to disable.
- :param set _disabled: Private set used to track the
- disabled status of plugins during
- the cascading process.
- """
- if _disabled is None:
- _disabled = set()
- with self._plugin_lock:
- if name not in _disabled and name in self._enabled:
- _disabled.add(name)
- plugin = self._plugins.get(name, None)
- if plugin is None:
- raise PluginNotFound(name)
- for dep in PLUGIN_DEPENDENTS[name]:
- self.disable(dep, _disabled)
- plugin._end()
- if name in self._enabled:
- self._enabled.remove(name)
- del self._plugins[name]
-
- def __keys__(self):
- """Return the set of enabled plugins."""
- return self._plugins.keys()
-
- def __getitem__(self, name):
- """
- Allow plugins to be accessed through the manager as if
- it were a dictionary.
- """
- plugin = self._plugins.get(name, None)
- if plugin is None:
- raise PluginNotFound(name)
- return plugin
-
- def __iter__(self):
- """Return an iterator over the set of enabled plugins."""
- return self._plugins.__iter__()
-
- def __len__(self):
- """Return the number of enabled plugins."""
- return len(self._plugins)
-
-
-class BasePlugin(object):
-
- #: A short name for the plugin based on the implemented specification.
- #: For example, a plugin for XEP-0030 would use `'xep_0030'`.
- name = ''
-
- #: A longer name for the plugin, describing its purpose. For example,
- #: a plugin for XEP-0030 would use `'Service Discovery'` as its
- #: description value.
- description = ''
-
- #: Some plugins may depend on others in order to function properly.
- #: Any plugin names included in :attr:`~BasePlugin.dependencies` will
- #: be initialized as needed if this plugin is enabled.
- dependencies = set()
-
- #: The basic, standard configuration for the plugin, which may
- #: be overridden when initializing the plugin. The configuration
- #: fields included here may be accessed directly as attributes of
- #: the plugin. For example, including the configuration field 'foo'
- #: would mean accessing `plugin.foo` returns the current value of
- #: `plugin.config['foo']`.
- default_config = {}
-
- def __init__(self, xmpp, config=None):
- self.xmpp = xmpp
- if self.xmpp:
- self.api = self.xmpp.api.wrap(self.name)
-
- #: A plugin's behaviour may be configurable, in which case those
- #: configuration settings will be provided as a dictionary.
- self.config = copy.copy(self.default_config)
- if config:
- self.config.update(config)
-
- def __getattr__(self, key):
- """Provide direct access to configuration fields.
-
- If the standard configuration includes the option `'foo'`, then
- accessing `self.foo` should be the same as `self.config['foo']`.
- """
- if key in self.default_config:
- return self.config.get(key, None)
- else:
- return object.__getattribute__(self, key)
-
- def __setattr__(self, key, value):
- """Provide direct assignment to configuration fields.
-
- If the standard configuration includes the option `'foo'`, then
- assigning to `self.foo` should be the same as assigning to
- `self.config['foo']`.
- """
- if key in self.default_config:
- self.config[key] = value
- else:
- super(BasePlugin, self).__setattr__(key, value)
-
- def _init(self):
- """Initialize plugin state, such as registering event handlers.
-
- Also sets up required event handlers.
- """
- if self.xmpp is not None:
- self.xmpp.add_event_handler('session_bind', self.session_bind)
- if self.xmpp.session_bind_event.is_set():
- self.session_bind(self.xmpp.boundjid.full)
- self.plugin_init()
- log.debug('Loaded Plugin: %s', self.description)
-
- def _end(self):
- """Cleanup plugin state, and prepare for plugin removal.
-
- Also removes required event handlers.
- """
- if self.xmpp is not None:
- self.xmpp.del_event_handler('session_bind', self.session_bind)
- self.plugin_end()
- log.debug('Disabled Plugin: %s' % self.description)
-
- def plugin_init(self):
- """Initialize plugin state, such as registering event handlers."""
- pass
-
- def plugin_end(self):
- """Cleanup plugin state, and prepare for plugin removal."""
- pass
-
- def session_bind(self, jid):
- """Initialize plugin state based on the bound JID."""
- pass
-
- def post_init(self):
- """Initialize any cross-plugin state.
-
- Only needed if the plugin has circular dependencies.
- """
- pass
-
-
-base_plugin = BasePlugin