More Docstrings in portage.py
authorAlec Warner <antarus@gentoo.org>
Sat, 23 Dec 2006 15:53:44 +0000 (15:53 -0000)
committerAlec Warner <antarus@gentoo.org>
Sat, 23 Dec 2006 15:53:44 +0000 (15:53 -0000)
svn path=/main/trunk/; revision=5365

pym/portage.py

index c84d161dc831346c27b908975d6c839d3efbe589..7094ecc86abf990a7066fcdd293f0b18872b6538 100644 (file)
@@ -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