More Docstrings in portage.py

svn path=/main/trunk/; revision=5365

1 files changed, 118 insertions, 17 deletions

diff --git a/pym/portage.py b/pym/portage.py
index c84d161dc..7094ecc86 100644
--- a/pym/portage.py
+++ b/pym/portage.py
@@ -229,9 +229,30 @@ def cacheddir(my_original_path, ignorecvs, ignorelist, EmptyOnError, followSymli
 	writemsg("cacheddirStats: H:%d/M:%d/S:%d\n" % (cacheHit, cacheMiss, cacheStale),10)
 	return ret_list, ret_ftype
 
-
 def listdir(mypath, recursive=False, filesonly=False, ignorecvs=False, ignorelist=[], followSymlinks=True,
 	EmptyOnError=False, dirsonly=False):
+	"""
+	Portage-specific implementation of os.listdir
+
+	@param mypath: Path whose contents you wish to list
+	@type mypath: String
+	@param recursive: Recursively scan directories contained within mypath
+	@type recursive: Boolean
+	@param filesonly; Only return files, not more directories
+	@type filesonly: Boolean
+	@param ignorecvs: Ignore CVS directories ('CVS','.svn','SCCS')
+	@type ignorecvs: Boolean
+	@param ignorelist: List of filenames/directories to exclude
+	@type ignorelist: List
+	@param followSymlinks: Follow Symlink'd files and directories
+	@type followSymlinks: Boolean
+	@param EmptyOnError: Return [] if an error occurs.
+	@type EmptyOnError: Boolean
+	@param dirsonly: Only return directories.
+	@type dirsonly: Boolean
+	@rtype: List
+	@returns: A list of files and directories (or just files or just directories) or an empty list.
+	"""
 
 	list, ftype = cacheddir(mypath, ignorecvs, ignorelist, EmptyOnError, followSymlinks)
 
@@ -726,12 +747,17 @@ def env_update(makelinks=1, target_root=None, prev_mtimes=None, contents=None):
 		outfile.write("setenv %s '%s'\n" % (x, env[x]))
 	outfile.close()
 
-# returns a tuple.  (version[string], error[string])
-# They are pretty much mutually exclusive.
-# Either version is a string and error is none, or
-# version is None and error is a string
-#
 def ExtractKernelVersion(base_dir):
+	"""
+	Try to figure out what kernel version we are running
+	@param base_dir: Path to sources (usually /usr/src/linux)
+	@type base_dir: string
+	@rtype: tuple( version[string], error[string])
+	@returns:
+	1. tuple( version[string], error[string])
+	Either version or error is populated (but never both)
+
+	"""
 	lines = []
 	pathname = os.path.join(base_dir, 'Makefile')
 	try:
@@ -787,7 +813,18 @@ def ExtractKernelVersion(base_dir):
 	return (version,None)
 
 def autouse(myvartree, use_cache=1, mysettings=None):
-	"returns set of USE variables auto-enabled due to packages being installed"
+	"""
+	autuse returns a list of USE variables auto-enabled to packages being installed
+
+	@param myvartree: Instance of the vartree class (from /var/db/pkg...)
+	@type myvartree: vartree
+	@param use_cache: read values from cache
+	@type use_cache: Boolean
+	@param mysettings: Instance of config
+	@type mysettings: config
+	@rtype: string
+	@returns: A string containing a list of USE variables that are enabled via use.defaults
+	"""
 	if mysettings is None:
 		global settings
 		mysettings = settings
@@ -1365,8 +1402,9 @@ class config:
 			self.setcpv(mycpv)
 
 	def _init_dirs(self):
-		"""Create tmp, var/tmp and var/lib/portage (relative to $ROOT)."""
-
+		"""
+		Create a few directories that are critical to portage operation
+		"""
 		if not os.access(self["ROOT"], os.W_OK):
 			return
 
@@ -1449,7 +1487,14 @@ class config:
 			raise KeyError, "No such key defined in environment: %s" % key
 
 	def reset(self,keeping_pkg=0,use_cache=1):
-		"reset environment to original settings"
+		"""
+		Restore environment from self.backupenv, call self.regenerate()
+		@param keeping_pkg: Should we keep the set_cpv() data or delete it.
+		@type keeping_pkg: Boolean
+		@param use_cache: Should self.regenerate use the cache or not
+		@type use_cache: Boolean
+		@rype: None
+		"""
 		self.modifying()
 		self.configdict["env"].clear()
 		self.configdict["env"].update(self.backupenv)
@@ -1519,6 +1564,20 @@ class config:
 		return 0
 
 	def setcpv(self, mycpv, use_cache=1, mydb=None):
+		"""
+		Load a particular CPV into the config, this lets us see the
+		Default USE flags for a particular ebuild as well as the USE
+		flags from package.use.
+
+		@param mycpv: A cpv to load
+		@type mycpv: string
+		@param use_cache: Enables caching
+		@type use_cache: Boolean
+		@param mydb: a dbapi instance that supports aux_get with the IUSE key.
+		@type mydb: dbapi or derivative.
+		@rtype: None
+		"""
+
 		self.modifying()
 		if self.mycpv == mycpv:
 			return
@@ -1609,6 +1668,22 @@ class config:
 
 
 	def regenerate(self,useonly=0,use_cache=1):
+		"""
+		Regenerate settings
+		This involves regenerating valid USE flags, re-expanding USE_EXPAND flags
+		re-stacking USE flags (-flag and -*), as well as any other INCREMENTAL
+		variables.  This also updates the env.d configdict; useful in case an ebuild
+		changes the environment.
+
+		If FEATURES has already stacked, it is not stacked twice.
+
+		@param useonly: Only regenerate USE flags (not any other incrementals)
+		@type useonly: Boolean
+		@param use_cache: Enable Caching (only for autouse)
+		@type use_cache: Boolean
+		@rtype: None
+		"""
+
 		self.modifying()
 		if self.already_in_regenerate:
 			# XXX: THIS REALLY NEEDS TO GET FIXED. autouse() loops.
@@ -1966,13 +2041,39 @@ class config:
 # XXX This would be to replace getstatusoutput completely.
 # XXX Issue: cannot block execution. Deadlock condition.
 def spawn(mystring, mysettings, debug=0, free=0, droppriv=0, sesandbox=0, **keywords):
-	"""spawn a subprocess with optional sandbox protection,
-	depending on whether sandbox is enabled.  The "free" argument,
-	when set to 1, will disable sandboxing.  This allows us to
-	spawn processes that are supposed to modify files outside of the
-	sandbox.  We can't use os.system anymore because it messes up
-	signal handling.  Using spawn allows our Portage signal handler
-	to work."""
+	"""
+	Spawn a subprocess with extra portage-specific options.
+	Optiosn include:
+
+	Sandbox: Sandbox means the spawned process will be limited in its ability t
+	read and write files (normally this means it is restricted to ${IMAGE}/)
+	SElinux Sandbox: Enables sandboxing on SElinux
+	Reduced Privileges: Drops privilages such that the process runs as portage:portage
+	instead of as root.
+
+	Notes: os.system cannot be used because it messes with signal handling.  Instead we
+	use the portage_exec spawn* family of functions.
+
+	This function waits for the process to terminate.
+
+	@param mystring: Command to run
+	@type mystring: String
+	@param mysettings: Either a Dict of Key,Value pairs or an instance of portage.config
+	@type mysettings: Dictionary or config instance
+	@param debug: Ignored
+	@type debug: Boolean
+	@param free: Enable sandboxing for this process
+	@type free: Boolean
+	@param droppriv: Drop to portage:portage when running this command
+	@type droppriv: Boolean
+	@param sesandbox: Enable SELinux Sandboxing (toggles a context switch)
+	@type sesandbox: Boolean
+	@param keywords: Extra options encoded as a dict, to be passed to spawn
+	@type keywords: Dictionary
+	@rtype: Integer
+	@returns:
+	1. The return code of the spawned process.
+	"""
 
 	if type(mysettings) == types.DictType:
 		env=mysettings