PluginRegistry

Complexity

Total Complexity

37

Size/Duplication

Total Lines	272
Duplicated Lines	0 %

Importance

Changes	2
Bugs	0	Features	0

16 Methods

Rating	Name	Duplication	Size	Complexity
A	nplugins()	0	7	1
A	load_class()	0	12	3
B	__init__()	0	29	2
F	load_instance()	0	47	9
A	get_renders()	0	6	1
A	nrenders()	0	7	1
A	get_render()	0	12	2
A	load_from_file()	0	16	2
B	load_all()	0	29	5
A	get_writers()	0	6	1
A	get_writer()	0	12	2
A	nreaders()	0	7	1
A	get_reader()	0	12	2
B	load_from_module()	0	28	3
A	nwriters()	0	7	1
A	get_readers()	0	6	1

# -*- coding: utf-8 -*-
"""

Plugin loader and Registry.

Currently supports the notion of Reader, Render and Writer plugins.

.. moduleauthor:: Kenny Freeman <kenny.freeman@gmail.com>

"""
import os
import imp
import inspect
import traceback
from plumd.config import Conf
from plumd.config import find as find_configs
from plumd import ConfigError, PluginLoadError
from plumd import Reader, Writer, Render

__author__ = 'Kenny Freeman'
__email__ = 'kenny.freeman@gmail.com'
__version__ = '0.7'
__license__ = "ISCL"
__docformat__ = 'reStructuredText'


class PluginRegistry(object):
    """Class loader and registry to maintain references.

    Uses a dict to record classes:

        class name => ( file, module, class )

    The plugin is loaded from <file> if defined in the plugin configuration
    otherwise <module> must be defined.

    If both <file> and <module> are defined in a plugin configuration, <file> is
    used and <module> ignored.
    """

    def __init__(self, log, config):
        """Plugin/Class loader and registry for reader/writer plugins.

        :param log: A logger
        :type log: logging.RootLogger
        :param config: A plumd.Config object
        :type config: plumd.config.Conf
        """
        self.log = log
        self.defaults = {
            'interval': config.get('interval'),
            'poll.interval': config.get('poll.interval'),
            'delay.poll': config.get('delay.poll'),
            'meta': config.get('meta'),
            'enabled': True
        }
        self.classes = {}
        self.readers = {}
        self.renders = {}
        self.writers = {}

        # ensure the configured plugin directory exists
        self.plugin_dir = config.get("config.plugins")
        if not os.path.isdir(self.plugin_dir):
            msg = "invalid plugin directory configured: {0}"
            raise ConfigError(msg.format(self.plugin_dir))

        # load all configured plugins
        self.load_all()

    @property
    def nreaders(self):
        """Return the count of Reader plugins loaded.

        :rtype: int
        """
        return len(self.readers.keys())

    @property
    def nrenders(self):
        """Return the count of Render plugins loaded.

        :rtype: int
        """
        return len(self.renders.keys())

    @property
    def nwriters(self):
        """Return the count of Writer plugins loaded.

        :rtype: int
        """
        return len(self.writers.keys())

    @property
    def nplugins(self):
        """Return the count of Reader + Writer plugins loaded.

        :rtype: int
        """
        return len(self.readers.keys()) + len(self.renders.keys()) + len(self.writers.keys())

    def get_readers(self):
        """Return a list of tuples of our reader plugins: [(name, Reader)...].

        :rtype: list((str, Reader))
        """
        return self.readers.items()

    def get_renders(self):
        """Return a list of tuples of our render plugins: [(name, Reader)...].

        :rtype: list((str, Render))
        """
        return self.renders.items()

    def get_writers(self):
        """Return a list of tuples of our writer plugins: [(name, Reader)...].

        :rtype: list((str, Writer))
        """
        return self.writers.items()

    def get_reader(self, pname):
        """Return the instance of the reader plugin identified by pname.

        :param pname: The name of the plugins class
        :type pname: str
        :raises: ValueError if pname not configured
        :rtype: object
        """
        if pname not in self.readers:
            err = "reader {0} not defined in configuration"
            raise ValueError(err.format(pname))
        return self.readers[pname]

    def get_render(self, pname):
        """Return the instance of the render plugin identified by pname.

        :param pname: The name of the plugins class
        :type pname: str
        :raises: ValueError if pname not configured
        :rtype: object
        """
        if pname not in self.renders:
            err = "renderer {0} not defined in configuration"
            raise ValueError(err.format(pname))
        return self.renders[pname]

    def get_writer(self, pname):
        """Return the instance of the writer plugin identified by pname.

        :param pname: The name of the plugins class
        :type pname: str
        :raises: ValueError if pname not configured
        :rtype: object
        """
        if pname not in self.writers:
            err = "writer {0} not defined in configuration"
            raise ValueError(err.format(pname))
        return self.writers[pname]

    def load_class(self, cname, mod):
        """Load and register class from module.

        :param cname: The class name to load
        :type cname: str
        :param mod: A module object from eg. imp.load_source or __import__
        :type mod: module
        :raises: PluginLoadError: many things can go wrong during loading
        """
        for iname, icls in inspect.getmembers(mod, inspect.isclass):
            if iname == cname:
                self.classes[cname] = icls

    def load_instance(self, cname, mod, config):
        """Load and register an instance of <class> from <module>.

        :param cname: The class name to load
        :type cname: str
        :param mod: A module object from eg. imp.load_source or __import__
        :type mod: module
        :param config: A conf configuration helper instance to pass to the class
        :type config: conf
        :raises: PluginLoadError: many things can go wrong during loading
        """
        pobj = None
        # ensure plugin has a uniq name
        pname = config.get('name', exception=True)
        if pname in self.readers or pname in self.writers:
            err = "duplicate plugin name: {0}"
            raise ConfigError(err.format(pname))

        # load the class if it's not already loaded
        if cname not in self.classes:
            self.load_class(cname, mod)

        # attempt to instantiate the plugin instance
        try:
            pobj = self.classes[cname](self.log, config)
        except Exception as exc:
            trace = traceback.format_exc()
            estr = "class {0}, module {1} raised: {2}, trace:{3}"
            eargs = [cname, mod.__name__, exc, trace]
            raise PluginLoadError(estr.format(*eargs))

Usage of * or ** arguments should usually be done with care.

        # ensure it actually instantiated an object
        if not pobj:
            err = "failed to instantiate plugin {0}: {1}"
            raise ConfigError(err.format(pname, config.path))

        # it should be one of Reader or Writer, ensure we keep a reference
        pclasses = inspect.getmro(pobj.__class__)
        if Reader in pclasses:
            self.readers[pname] = pobj
        elif Writer in pclasses:
            self.writers[pname] = pobj
        elif Render in pclasses:
            self.renders[pname] = pobj
        else:
            err = "plugin is not a Reader or Writer: {0}: {1}"
            raise ConfigError(err.format(pname, cname))

    def load_from_file(self, cname, fname, config):
        """Load an instance of a Plugin from a file.

        :param cname: The name of the plugins class
        :type cname: str
        :param fname: The full path to the source file containing cname
        :type fname: str
        :param config: The plugins configuration
        :type config: plumd.config.Conf
        """
        pname = config.get("name", exception=True)
        if not os.path.isfile(fname):
            err = "invalid source file for plugin {0}: {1} in {2}"
            raise ConfigError(err.format(pname, fname, config.path))
        mod = imp.load_source(cname, fname)
        self.load_instance(cname, mod, config)

    def load_from_module(self, cname, mname, config):
        """Load an instance of a Plugin from a file.

        :param cname: The name of the plugins class
        :type cname: str
        :param mname: The full path to the source file containing cname
        :type mname: str
        :param config: The plugins configuration
        :type config: plumd.config.Conf
        """
        # allow import of modules with dots in the name
        mod = None
        fname = None
        if "." in mname:
            fname = mname
            self.log.debug("importing {0} from {1}".format(mname, fname))
        else:
            self.log.debug("importing {0}".format(mname))

        # attempt to import the module
        try:
            mod = __import__(mname.strip(), fromlist=fname)
        except Exception as e:
            msg = "module {0} import failed: {1}".format(mname, e)
            raise PluginLoadError(msg)

        # great, now load an instance class of it
        self.load_instance(cname, mod, config)

    def load_all(self):
        """Load all plugins defined in our configuration."""
        # find all the plugin configuration files
        # recursively scan the plugin configuration directory
        for pconf_fname in find_configs(self.plugin_dir, 'yaml'):
            # create a configuration object from the plugins config file
            pconfig = Conf(pconf_fname).defaults(self.defaults)

            # first of all, every plugin config needs a uniq name
            pname = pconfig.get('name', exception=True)

            # next, plugins can be defined however disabled in configuration
            if not pconfig.get('enabled'):
                msg = "skipping disabled plugin: {0}"
                self.log.info(msg.format(pname))

            # next every plugin config must define the plugins class
            pclass = pconfig.get('class', exception=True)
            if pclass in self.classes:
                msg = "duplicate plugin class defined: {0}: {1}"
                raise ConfigError(msg.format(pconf_fname, pclass))

            # next, do we load the class from a file or module?
            fname = pconfig.get('file')
            if fname:
                self.load_from_file(pclass, fname, pconfig)
            else:
                mname = pconfig.get('module', exception=True)
                self.load_from_module(pclass, mname, pconfig)