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) 2008 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.
"""

from __future__ import absolute_import
__docformat__ = "restructuredtext"

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

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 Menu (object):
	"""
	One single menu entry.

	:IVariables:

		label : string
			The label of the entry. Can have underscores to define the shortcut.

		call
			The function to call, if the entry is clicked.
	"""
	__slots__ = ("label", "call")

	def __init__ (self, label, call):
		self.label = label
		self.call = call

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 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.__menus = [] #: List of `Menu`
		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

	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 menus (self):
		"""
		Returns an iterator over the menus for this plugin.

		:rtype: iter<`Menu`>
		"""
		return iter(self.__menus)

	@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_menu (self, label, callable):
		"""
		Adds a new menu item for this plugin.

		:see: `Menu`
		"""
		self.__menus.append(Menu(label, callable))

	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))


class PluginQueue (object):
	"""
	Class managing and loading the plugins.
	
	:IVariables:

		plugins : `Plugin` []
			The list of managed plugins.

		hooks : string -> `Hook`
			For each hook name map to a `Hook` object holding the corresponding `Call` objects.
	"""

	def __init__ (self):
		"""
		Constructor.
		"""

		self.plugins = []
		self.hooks = defaultdict(Hook)

	def get_plugins (self, list_disabled = True):
		"""
		Returns the plugins.

		:param list_disabled: Also list disabled plugins.
		:type list_disabled: boolean

		:rtype: iter<`Plugin`>
		"""
		return (x for x in self.plugins if (x.enabled or list_disabled))

	def load (self):
		"""
		Load the plugins.
		
		This method scans the `portato.constants.PLUGIN_DIR` for python modules and tries to load them. If the modules are real plugins,
		they have called `register` and thus the plugins are added.
		"""

		# look them up
		plugins = []
		for f in os.listdir(PLUGIN_DIR):
			path = osp.join(PLUGIN_DIR, f)
			if osp.isdir(path):
				if osp.isfile(osp.join(path, "__init__.py")):
					plugins.append(f)
				else:
					debug("'%s' is not a plugin: __init__.py missing", path)
			else:
				if f.endswith(".py"):
					plugins.append(f[:-3])
				elif f.endswith(".pyc") or f.endswith(".pyo"):
					pass # ignore .pyc and .pyo
				else:
					debug("'%s' is not a plugin: not a .py file", path)

		# some magic ...
		plugin_module.__path__.insert(0, PLUGIN_DIR.rstrip("/")) # make the plugins loadable as "portato.plugins.name"
		# add Plugin and register to the builtins, so the plugins always have the correct version :)
		plugin_module.__builtins__["Plugin"] = Plugin
		plugin_module.__builtins__["register"] = register

		for p in plugins: # import them
			try:
				exec "from portato.plugins import %s" % p in {}
			except PluginLoadException, e:
				error(_("Loading plugin '%(plugin)s' failed: %(error)s"), {"plugin" : p, "error" : e.message})
			except:
				tb = traceback.format_exc()
				error(_("Loading plugin '%(plugin)s' failed: %(error)s"), {"plugin" : p, "error" : tb})

		self._organize()

	def add (self, plugin, disable = False):
		"""
		Adds a plugin to the internal list.

		:Parameters:

			plugin : `Plugin`
				``Plugin`` subclass or instance to add. If a class is passed, it is instantiated.

			disable : boolean
				Disable the plugin.

		:raise PluginLoadException: passed plugin is not of class `Plugin`
		"""

		if callable(plugin) and Plugin in plugin.__bases__:
			p = plugin(disable = disable) # need an instance and not the class
		elif isinstance(plugin, Plugin):
			p = plugin
			if disable:
				p.status = p.STAT_HARD_DISABLED
		else:
			raise PluginLoadException, "Is neither a subclass nor an instance of Plugin."

		p._init()

		self.plugins.append(p)
		
		if p.status == p.STAT_HARD_DISABLED:
			msg = _("Plugin is disabled!")
		elif p._unresolved_deps:
			msg = _("Plugin has unresolved dependencies - disabled!")
		else:
			msg = ""
		
		info("%s %s", _("Plugin '%s' loaded.") % p.name, msg)

	def hook (self, hook, *hargs, **hkwargs):
		"""
		The decorator to use in the program.
		All parameters except ``hook`` are passed to plugins.

		:param hook: the name of the hook
		:type hook: string
		"""

		def hook_decorator (func):
			"""
			The real decorator.
			"""
			h = self.hooks[hook]

			active = Hook()

			# remove disabled
			for type in ("before", "after"):
				calls = getattr(h, type)
				aCalls = getattr(active, type)
				for call in calls:
					if call.plugin.enabled:
						aCalls.append(call)

			if h.override and h.override.plugin.enabled:
				active.override = h.override

			@wraps(func)
			def wrapper (*args, **kwargs):
				ret = None

				# before
				for call in active.before:<