plugins.py

# -*- coding: utf-8 -*-
#
#   plugins.py — Plugin loader
#
#   This file is part of debexpo - https://alioth.debian.org/projects/debexpo/
#
#   Copyright © 2008 Jonny Lamb <jonny@debian.org>
#   Copyright © 2010 Jan Dittberner <jandd@debian.org>
#   Copyright © 2012 Clément Schreiner <clement@mux.me>
#
#   Permission is hereby granted, free of charge, to any person
#   obtaining a copy of this software and associated documentation
#   files (the "Software"), to deal in the Software without
#   restriction, including without limitation the rights to use,
#   copy, modify, merge, publish, distribute, sublicense, and/or sell
#   copies of the Software, and to permit persons to whom the
#   Software is furnished to do so, subject to the following
#   conditions:
#
#   The above copyright notice and this permission notice shall be
#   included in all copies or substantial portions of the Software.
#
#   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
#   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
#   OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
#   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
#   HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
#   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
#   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
#   OTHER DEALINGS IN THE SOFTWARE.

"""
Holds the plugin loader.
"""

__author__ = 'Jonny Lamb'
__copyright__ = ', '.join([
    'Copyright © 2008 Jonny Lamb',
    'Copyright © 2010 Jan Dittberner',
    'Copyright © 2012 Clément Schreiner',
    ])
__license__ = 'MIT'

import logging
import os
import shutil
import sys
import traceback
from collections import namedtuple

import pylons

from debexpo.model import meta


log = logging.getLogger(__name__)


PluginModule = namedtuple('PluginModule', ['name', 'stage', 'plugin', 'models'])


class Plugins(object):
    """
    Plugin loader.
    """

    # FIXME: remove changes and changes_file arguments
    # (once they're accessible from the git storage backend, that is)
    def __init__(self, type, package_version, changes=None, changes_file=None, **kw):
        """
        Class constructor. Sets class attributes and then runs the plugins.

        ``type``
            Type of plugins to import (for example 'qa'.)

        ``package_version``
            PackageVersion instance of the package we load plugins for

        ``changes``
            Changes class for the package to test. Needed for the importer

        ``changes_file``
            Name of the changes file.

        ``kw``
            Extra information for plugins to have.
        """
        self.config = pylons.config
        self.type = type.replace('-', '_')
        self.changes = changes
        self.changes_file = changes_file

        self.result_objects = []
        self.tempdir = None
        self.kw = kw

        self.package_version = package_version

        self.modules = self.import_plugins(self.type)

        # the plugin instances
        self.plugins = {}

    @classmethod
    def _import_plugin(cls, name):
        """
        Imports a module and returns it.

        This method was stolen from:
            http://docs.python.org/lib/built-in-funcs.html

        ``name``
            Module to import.
        """
        try:
            log.debug('Trying to import plugin: %s', name)
            mod = __import__(name)
            components = name.split('.')
            for comp in components[1:]:
                mod = getattr(mod, comp)
            log.debug('Import succeeded.')
            return mod
        except ImportError, e:
            if str(e).startswith('No module named'):
                # Not fatal: the plugin module was not found at this location
                # (might be okay because plugins are looked for in several locations)
                log.debug('Import failed - module not found: %s', e)
            else:
                # The module was found but failed to import for other reasons.
                # It's worth looking into why importing failed.
                log.warn('Import of module "%s" failed with error: %s', name, e)
            return None

    @classmethod
    def _what_plugins(cls, stage):
        """
        List of the plugins that must be run.
        """

        config = pylons.config

        key = 'debexpo.plugins.' + stage
        log.debug("Getting plugins with key (repr): %s", repr(key))
        plugins = config.get(key)

        return plugins.split(' ')

    @classmethod
    def import_plugins(cls, stage):
        """
        Import all plugins for given stage and return them as a list.
        """

        modules = {}
        config = pylons.config

        plugins = cls._what_plugins(stage)
        log.debug("Importing these plugins: %s", plugins)

        for plugin_name in plugins:
            if config.get('debexpo.plugindir') != '':
                # First try in the user-defined plugindir
                sys.path.append(config['debexpo.plugindir'])
                module = cls._import_plugin(plugin_name)
                if module is not None:
                    log.debug('Found module in debexpo.plugin_dir')

                else:
                    # Try in debexpo.plugins
                    name = 'debexpo.plugins.%s' % plugin_name
                    module = cls._import_plugin(name)

                if module is None or not hasattr(module, 'plugin'):
                    log.debug('No plugin found in module %s' % plugin_name)
                    continue

                models = getattr(module, 'models', [])

                modules[plugin_name] = PluginModule(name=plugin_name,
                                               plugin=getattr(module, 'plugin'),
                                               models=models,
                                               stage=stage)

        return modules

    def load_plugins(self):
        """
        Instantiate all plugins and register them in the 'plugins'
        dictionary attribute.
        e.g.: self.plugins['native'] -> <NativePlugin 42>
        """
        for module in self.modules.itervalues():
            try:
                self.plugins[module.name] = module.plugin(module.name,
                                                          self.package_version,
                                                          models=module.models,
                                                          changes=self.changes,
                                                          kw=self.kw)
            except Exception:
                log.debug('Something went wrong while loading the plugin {}:'
                         '{}'.format(module.name, traceback.format_exc()))


    def run_plugins(self):
        """
        Run all imported plugins.
        """

        if len(self) == 0:
            log.debug('No plugin loaded.')

        # Run each plugin.
        for name, plugin in self.iteritems():
            log.debug('Running plugin: %s' % name)
            try:
                plugin.run()
            except Exception:
                log.debug("Something wrong happened while running the plugin '%s': %s"
                          % (name, traceback.format_exc()))
            else:
                plugin.save()

    def load_results(self):
        """
        Calls ``load`` method on all loaded plugin instances.
        """

        for name, plugin in self.iteritems():
            plugin.load()


    #
    # magic methods from accessing the ``plugins`` attribute
    #

    # FIXME: do this properly with collections.abc? (not sure)

    def __getitem__(self, key):
        """
        Returns a plugin instance for the given plugin name.
        plugins['native'] -> NativePlugin instance
        """
        return self.plugins[key]

    def get(self, key, default):
        return self.plugins.get(key, default)

    def iteritems(self):
        """Iter the items in the ``plugins`` dictionary attribute."""
        return self.plugins.iteritems()

    def __len__(self):
        """Number of plugins that have been loaded."""
        return len(self.plugins)

    def __iter__(self):
        """ Iter over plugin instances' names """
        for name in self.plugins:
            yield name

    def __contains__(self, key):
        return key in self.plugins