Some documentation work

5 files changed, 107 insertions, 16 deletions

diff --git a/portato/config_parser.py b/portato/config_parser.py
index 30873e7..19d3929 100644
--- a/portato/config_parser.py
+++ b/portato/config_parser.py
@@ -3,13 +3,33 @@
 # File: portato/config_parser.py
 # This file is part of the Portato-Project, a graphical portage-frontend.
 #
-# Copyright (C) 2006 René 'Necoro' Neumann
+# Copyright (C) 2006-2007 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 simple parser for configuration files in ini-style.
+
+The main difference to other simple ini-parsers is, that it does not
+write the whole structure into the file, but only the changed values.
+Thus it keeps comments and structuring of the file.
+
+@var DELIMITER: list of delimiters allowed
+@type DELIMITER: string[]
+
+@var COMMENT: comment marks allowed
+@type COMMENT: string[]
+
+@var TRUE: Regular expression for all TRUE values allowed.
+Currently supported are the values (case insensitive): true, 1, on, wahr, ja, yes.
+@var FALSE: Regular expression for all FALSE values allowed.
+Currently supported are the values (case insensitive): false, 0, off, falsch, nein, no,
+@var SECTION: Regular expression allowing the recognition of a section header.
+@var EXPRESSION: Regular expression defining a normal option-value pair.
+"""
+
 from helper import debug
 
 import re
@@ -25,7 +45,18 @@ SECTION = re.compile("\s*\[(\w+)\]\s*")
 EXPRESSION = re.compile(r"\s*(\w+)\s*[:=]\s*(.*)\s*")
 
 class Value (object):
-	"""Class defining a value of a key."""
+	"""Class defining a value of a key.
+	
+	@ivar value: The specific value. This is a property.
+	@type value: arbitrary
+	@ivar line: The line in the config file.
+	@type line: int
+	@ivar boolean: The boolean meaning of this value. Set this to C{None} if this is not a boolean.
+	@type boolean: boolean
+	@ivar changed: Set to True if the value has been changed.
+	@type changed: boolean
+	@ivar old: The old value.
+	@type old: arbitrary"""
 
 	def __init__ (self, value, line, bool = None):
 		"""Constructor.
@@ -34,7 +65,7 @@ class Value (object):
 		@type value: string
 		@param line: the line in the config file
 		@type line: int
-		@param bool: boolean meaning of the value
+		@param bool: The boolean meaning of the value. Set this to C{None} if this is not a boolean.
 		@type bool: boolean"""
 
 		self.__value = value
@@ -82,7 +113,19 @@ class Value (object):
 	value = property(get,set)
 	
 class ConfigParser:
-	"""The newly implemented Config-Parser."""
+	"""The parser class.
+
+	@cvar true_false: A mapping from the truth values to their opposits.
+	@type true_false: string -> string
+	
+	@ivar file: the file to scan
+	@type file: string
+	@ivar cache: caches the content of the file
+	@type cache: string[]
+	@ivar vars: the found options grouped by section
+	@type vars: string -> (string -> L{Value})
+	@ivar pos: the positions of the values grouped by lineno
+	@type pos: int -> (int, int)"""
 
 	# generates the complementary true-false-pairs
 	true_false = {
diff --git a/portato/constants.py b/portato/constants.py
index 7df6538..f8da545 100644
--- a/portato/constants.py
+++ b/portato/constants.py
@@ -10,6 +10,30 @@
 #
 # Written by René 'Necoro' Neumann <necoro@necoro.net>
 
+"""
+Constants used through out the program. Mainly different pathes.
+These should be set during the installation.
+
+@var CONFIG_DIR: The configuration directory.
+@type CONFIG_DIR: string
+@var CONFIG_LOCATION: L{CONFIG_DIR} plus name of the config file.
+@type CONFIG_LOCATION: string
+@var DATA_DIR: Directory which contains several data files (e.g. ui-files).
+@type DATA_DIR: string
+@var PLUGIN_DIR: Directory containing the plugin xmls.
+@type PLUGIN_DIR: string
+@var VERSION: the current version
+@type VERSION: string
+@var ICON_DIR: directory containing the icons
+@type ICON_DIR: string
+@var APP_ICON: the path of the application icon
+@type APP_ICON: string
+@var FRONTENDS: the list of frontends which are installed
+@type FRONTENDS: string[]
+@var STD_FRONTEND: the frontend uses as the default, i.e. if no other one is given on the cmdline
+@type STD_FRONTEND: string
+"""
+
 CONFIG_DIR = "/etc/portato/"
 CONFIG_LOCATION = CONFIG_DIR+"portato.cfg"
 
diff --git a/portato/gui/gui_helper.py b/portato/gui/gui_helper.py
index f914b55..3c9edce 100644
--- a/portato/gui/gui_helper.py
+++ b/portato/gui/gui_helper.py
@@ -459,11 +459,10 @@ class EmergeQueue:
 					self.title_update(title)
 				time.sleep(0.5)
 
-		self.process = None
 
 		if self.title_update: self.title_update(None)
 
-		@plugin.hook("after_emerge", packages)
+		@plugin.hook("after_emerge", packages = packages, retcode = self.process.returncode)
 		def update_packages():
 			for p in packages:
 				if p in ["world", "system"]: continue
@@ -472,6 +471,7 @@ class EmergeQueue:
 				debug("Category %s refreshed" % cat)
 
 		update_packages()
+		self.process = None
 
 	def _emerge (self, options, packages, it, command = None):
 		"""Calls emerge and updates the terminal.
@@ -485,7 +485,7 @@ class EmergeQueue:
 		@param command: the command to execute - default is "/usr/bin/python /usr/bin/emerge"
 		@type command: string[]"""
 
-		@plugin.hook("emerge", packages, command)
+		@plugin.hook("emerge", packages = packages, command = command, console = self.console)
 		def sub_emerge(command):
 			if command is None:
 				command = system.get_merge_command()
diff --git a/portato/helper.py b/portato/helper.py
index f327f75..9328223 100644
--- a/portato/helper.py
+++ b/portato/helper.py
@@ -10,6 +10,13 @@
 #
 # Written by René 'Necoro' Neumann <necoro@necoro.net> et.al.
 
+"""
+Some nice functions used in the program.
+
+@var DEBUG: Boolean controlling whether to printout debug messages.
+@type DEBUG: boolean
+"""
+
 import traceback, os.path, sys, types
 
 DEBUG = True
@@ -30,15 +37,13 @@ def debug(*args, **kwargs):
 	If debug(obj0, obj1, obj2) is called, the text part of the output 
 	looks like the output from print obj0, obj1, obj2.
 	
-	Keywords which can be used:
-		- name: Use the given name instead the correct function name.
-		- file: output file to use
-		- minus: The value given is the amount of frames to ignore in the stack to return the correct function call.
-				 This should be used if you are wrapping the debug call.
-		- warn: Prints the message as a warning. Value of DEBUG is ignored.
-		- error: Prints the message as an error. Value of DEBUG is ignored."""
+	@keyword name: Use the given name instead the correct function name.
+	@keyword file: Output file to use.
+	@keyword minus: The value given is the amount of frames to ignore in the stack to return the correct function call.
+	This should be used if you are wrapping the debug call.
+	@keyword warn: Prints the message as a warning. Value of DEBUG is ignored.
+	@keyword error: Prints the message as an error. Value of DEBUG is ignored."""
 
-	
 	if not DEBUG and not ("warn" in kwargs or "error" in kwargs): return
 	
 	stack = traceback.extract_stack()
diff --git a/portato/plugin.py b/portato/plugin.py
index da1e883..8a54c11 100644
--- a/portato/plugin.py
+++ b/portato/plugin.py
@@ -411,6 +411,8 @@ class PluginQueue:
 		"""Creates the lists of connects in a way, that all dependencies are fullfilled."""
 		unresolved_before = {} 
 		unresolved_after = {}
+		star_before = {} # should be _before_ all other
+		star_after = {} # should be _after_ all other
 
 		for plugin in self.list: # plugins
 			for hook in plugin.hooks: # hooks in plugin
@@ -423,6 +425,11 @@ class PluginQueue:
 					if connect.is_before_type():
 						if connect.depend_plugin is None: # no dependency -> straight add
 							self.hooks[hook.hook][0].append(connect)
+						elif connect.depend_plugin == "*":
+							if not hook.hook in star_before:
+								star_before[hook.hook] = []
+
+							star_before[hook.hook].append(connect)
 						else:
 							named = [x.plugin.name for x in self.hooks[hook.hook][0]]
 							if connect.depend_plugin in named:
@@ -437,6 +444,11 @@ class PluginQueue:
 					elif connect.is_after_type():
 						if connect.depend_plugin is None: # no dependency -> straight add
 							self.hooks[hook.hook][2].append(connect)
+						elif connect.depend_plugin == "*":
+							if not hook.hook in star_after:
+								star_after[hook.hook] = []
+
+							star_after[hook.hook].append(connect)
 						else:
 							named = [x.plugin.name for x in self.hooks[hook.hook][2]]
 							if connect.depend_plugin in named:
@@ -457,13 +469,20 @@ class PluginQueue:
 		
 		self._resolve_unresolved(unresolved_before, unresolved_after)
 
+		for hook in star_before:
+			self.hooks[hook][0][0:0] = star_before[hook] # prepend the list
+
+		for hook in star_after:
+			self.hooks[hook][2].extend(star_after[hook]) # append the list
+
+
 	def _resolve_unresolved (self, before, after):
 		def resolve(hook, list, idx, add):
 			if not list: 
 				return
 			
 			changed = False
-			for connect in list:
+			for connect in list[:]:
 				named = [x.plugin.name for x in self.hooks[hook][idx]]
 				if connect.depend_plugin in named:
 					changed = True