From e9c768c39e540b9f272ebc08b90f2fc88c35878e Mon Sep 17 00:00:00 2001 From: Alec Warner Date: Sat, 23 Dec 2006 15:53:44 +0000 Subject: More Docstrings in portage.py svn path=/main/trunk/; revision=5365 --- pym/portage.py | 135 +++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 118 insertions(+), 17 deletions(-) (limited to 'pym') 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 -- cgit v1.2.3-1-g7c22