path: root/portato/plugin.py

# -*- coding: utf-8 -*-
#
# File: portato/plugin.py
# This file is part of the Portato-Project, a graphical portage-frontend.
#
# Copyright (C) 2006-2010 René 'Necoro' Neumann
# This is free software.  You may redistribute copies of it under the terms of
# the GNU General Public License version 2.
# There is NO WARRANTY, to the extent permitted by law.
#
# Written by René 'Necoro' Neumann <necoro@necoro.net>

"""
A module managing the plugins for Portato.
"""
__docformat__ = "restructuredtext"

import os
import os.path as osp
import traceback
from collections import defaultdict, Callable
from functools import wraps

from . import helper
from .helper import debug, warning, info, error
from .constants import PLUGIN_DIR
from .backend import system
from . import plugins as plugin_module

class PluginLoadException (Exception):
    """
    Exception signaling a failed plugin loading.
    """
    pass

class Call (object):
    """
    This class represents an object, which is attached to a specified hook.

    :IVariables:

        plugin : `Plugin`
            The plugin where this call belongs to.

        hook : string
            The name of the corresponding hook.

        call
            The function to call.

        type : string
            This is either ``before``, ``after`` or ``override`` and defines the type of the call:

                before
                    access before the original function
                override
                    access *instead of* the original function. **USE THIS ONLY IF YOU KNOW WHAT YOU ARE DOING**
                after
                    access after the original function has been called

            Default: ``before``

        dep : string
            This defines a plugin which should be executed after/before this one.
            ``"*"`` means all and ``"-*"`` means none.
    """
    __slots__ = ("plugin", "hook", "call", "type", "dep")

    def __init__ (self, plugin, hook, call, type = "before", dep = None):
        self.plugin = plugin
        self.hook = hook
        self.call = call
        self.type = type
        self.dep = dep

class Hook (object):
    """
    Representing a hook with all the `Call` s for the different types.
    """
            
    __slots__ = ("before", "override", "after")

    def __init__ (self):
        self.before = []
        self.override = None
        self.after = []

class WidgetSlot (object):
    """
    A slot, where plugins can add widgets.

    :IVariables:

        widget : gobject.GObjectMeta
            The widget class, which can be used in this slot.

        name : string
            The slot's name.

        init : function
            Function to call, iff there is at least one widget for that slot.

        add : function(`Widget`)
            Function to call, if a widget is added.

        max : int
            The maximum number of widgets which can be registered. -1 means unlimited.

    """
    
    slots = {}
    
    def __init__ (self, widget, name, add = None, init = None, max = -1):
        self.widget = widget
        self.name = name
        self.max = max

        # we might be subclassed
        # in this case do not overwrite

        if not hasattr(self, "init"):
            self.init = init

        if not hasattr(self, "add"):
            self.add = add
        
        self._inited = False

        debug("Registering new WidgetSlot '%s'.", name)
        WidgetSlot.slots[name] = self

    def add_widget (self, w):
        if not self._inited:
            if self.init is not None:
                self.init()
            self._inited = True

        if self.add is not None:
            self.add(w)

class Widget (object):
    """
    Fills a WidgetSlot.

    :IVariables:

        slot : string
            The name of the slot to fill.

        widget : gtk.Widget
            The widget which is added.

    """

    __slots__ = ("slot", "widget")

    def __init__ (self, slot, widget):
        self.slot = slot
        self.widget = widget

class Plugin (object):
    """
    This is the main plugin object. It is used where ever a plugin is wanted, and it is the one, which needs to be subclassed by plugin authors.

    :CVariables:

        STAT_DISABLED : status
            Status: Disabled.

        STAT_TEMP_ENABLED : status
            Status: Enabled for this session only.

        STAT_ENABLED : status
            Status: Enabled.

        STAT_TEMP_DISABLED : status
            Status: Disabled for this session only.

        STAT_HARD_DISABLED : status
            Status: Forced disabled by program (i.e. because of errors in the plugin).
    """

    (STAT_DISABLED, STAT_TEMP_ENABLED, STAT_ENABLED, STAT_TEMP_DISABLED) = range(4)
    STAT_HARD_DISABLED = -1

    def __init__ (self, disable = False):
        """
        :param disable: Forcefully disable the plugin
        :type disable: bool
        """
        self.__calls = [] #: List of `Call`
        self._unresolved_deps = False #: Does this plugin has unresolved dependencies?

        self.status = self.STAT_ENABLED #: The status of this plugin
        
        if disable:
            self.status = self.STAT_HARD_DISABLED

        # debug test
        if hasattr(self, "widget_init") and not isinstance(self, WidgetPlugin):
            debug("Plugin '%s' has an init_widget() function but is not a WidgetPlugin. Are you sure, this is correct?", self.name)

    def _init (self):
        """
        Method called from outside to init the extension parts of this plugin.
        If the current status is `STAT_HARD_DISABLED` or there are unresolved dependencies, the init process is not started.
        """

        for d in self.deps:
            if not system.find_packages(d, pkgSet=system.SET_INSTALLED, with_version = False):
                self._unresolved_deps = True
                break
        
        if self.status != self.STAT_HARD_DISABLED and not self._unresolved_deps:
            self.init()
    
    def init (self):
        """
        This method is called by `_init` and should be overriden by the plugin author.

        :precond: No unresolved deps and the status is not `STAT_HARD_DISABLED`.
        """
        pass

    @property
    def author (self):
        """
        Returns the plugin's author.
        The author is given by the ``__author__`` variable.

        :rtype: string
        """
        return getattr(self, "__author__", "")

    @property
    def description (self):
        """
        Returns the description of this plugin.
        It is given by either a ``__description__`` variable or by the normal class docstring.

        :rtype: string
        """
        if hasattr(self, "__description__"):
            return self.__description__
        else:
            doc = getattr(self, "__doc__", "")

            if not doc or doc == Plugin.__doc__:
                return ""
            else:
                return doc

    @property
    def name (self):
        """
        The name of the plugin. If no ``__name__`` variable is given, the class name is taken.

        :rtype: string
        """
        return getattr(self, "__name__", self.__class__.__name__)

    @property
    def calls (self):
        """
        Returns an iterator over the registered calls for this plugin.

        :rtype: iter<`Call`>
        """
        return iter(self.__calls)

    @property
    def deps (self):
        """
        Returns an iterator of the dependencies or ``[]`` if there are none.
        The dependencies are given in the ``__dependency__`` variable.

        :rtype: [] or iter<string>
        """
        if hasattr(self, "__dependency__"):
            return iter(self.__dependency__)
        else:
            return []

    @property
    def enabled (self):
        """
        Returns ``True`` if the plugin is enabled.

        :rtype: boolean
        :see: `status`
        """
        return (self.status in (self.STAT_ENABLED, self.STAT_TEMP_ENABLED))
    
    def add_call (self, hook, callable, type = "before", dep = None):
        """
        Adds a new call for this plugin.

        :see: `Call`
        """
        self.__calls.append(Call(self, hook, callable, type, dep))

    def __str__ (self):
        return self.name

    __repr__ = __str__

class WidgetPlugin (Plugin):

    def __init__ (self, *args, **kwargs):
        Plugin.__init__(self, *args, **kwargs)
        self.__widgets = [] #: List of `Widget`

    def _widget_init (self, window):
        self.window = window

        if self.status == self.STAT_ENABLED and not self._unresolved_deps:
            self.widget_init()

    def widget_init (self):
        debug("%s: No widgets to initialize. Wrong class used for plugin?", self.name)

    def add_widget (self, slot, widget):
        """
        Adds a new widget for this plugin.

        :see: `Widget`
        """

        if not slot in WidgetSlot.slots:
            raise PluginLoadException("Could not find specified widget slot: %s" % slot)
        
        self.__widgets.append(Widget(slot, widget))

    def create_widget (self, slot, args, **kwargs):
        """
        Creates a new widget for the plugin.

        :Parameters:
            
            slot : string
                The slot to create a widget for.

            args : list of objects
                The arguments to pass to the widget constructor.

            kwargs : dict
                Additional named parameters are for callback functions.
        """

        try:
            widget = WidgetSlot.slots[slot].widget
        except KeyError:
            raise PluginLoadException("Could not find specified widget slot: %s" % slot)

        if not hasattr(args, "__iter__"):
            w = widget(args)
        else:
            w = widget(*args)

        for k,v in kwargs.items():
            w.connect(k, v)

        self.add_widget(slot, w)
    
    @property
    def widgets (self):
        """
        Returns an iterator over the widgets for this plugin.

        :rtype: iter<`Widget`>
        """
        return iter(self.__widgets)

class PluginQueue