From 4343fbef79335369313538a07e67db2210e2b516 Mon Sep 17 00:00:00 2001 From: Alec Warner Date: Mon, 25 Dec 2006 04:52:11 +0000 Subject: [PATCH] more docstrings.. svn path=/main/trunk/; revision=5385 --- pym/portage.py | 125 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 111 insertions(+), 14 deletions(-) diff --git a/pym/portage.py b/pym/portage.py index 98e899b12..b3eb4a581 100644 --- a/pym/portage.py +++ b/pym/portage.py @@ -6305,10 +6305,30 @@ class binarytree(object): return myslot class dblink: - "this class provides an interface to the standard text package database" + """ + This class provides an interface to the installed package database + At present this is implemented as a text backend in /var/db/pkg. + """ def __init__(self, cat, pkg, myroot, mysettings, treetype=None, vartree=None): - "create a dblink object for cat/pkg. This dblink entry may or may not exist" + """ + Creates a DBlink object for a given CPV. + The given CPV may not be present in the database already. + + @param cat: Category + @type cat: String + @param pkg: Package (PV) + @type pkg: String + @param myroot: Typically ${ROOT} + @type myroot: String (Path) + @param mysettings: Typically portage.config + @type mysettings: An instance of portage.config + @param treetype: one of ['porttree','bintree','vartree'] + @type treetype: String + @param vartree: an instance of vartree corresponding to myroot. + @type vartree: vartree + """ + self.cat = cat self.pkg = pkg self.mycpv = self.cat+"/"+self.pkg @@ -6363,13 +6383,18 @@ class dblink: def create(self): "create the skeleton db directory structure. No contents, virtuals, provides or anything. Also will create /var/db/pkg if necessary." + """ + This function should never get called (there is no reason to use it). + """ # XXXXX Delete this eventually raise Exception, "This is bad. Don't use it." if not os.path.exists(self.dbdir): os.makedirs(self.dbdir) def delete(self): - "erase this db entry completely" + """ + Remove this entry from the database + """ if not os.path.exists(self.dbdir): return try: @@ -6386,10 +6411,16 @@ class dblink: sys.exit(1) def clearcontents(self): + """ + For a given db entry (self), erase the CONTENTS values. + """ if os.path.exists(self.dbdir+"/CONTENTS"): os.unlink(self.dbdir+"/CONTENTS") def getcontents(self): + """ + Get the installed files of a given package (aka what that package installed) + """ if not os.path.exists(self.dbdir+"/CONTENTS"): return None if self.contentscache != []: @@ -6444,8 +6475,30 @@ class dblink: def unmerge(self, pkgfiles=None, trimworld=1, cleanup=1, ldpath_mtimes=None): - """The caller must ensure that lockdb() and unlockdb() are called - before and after this method.""" + """ + Calls prerm + Unmerges a given package (CPV) + calls postrm + calls cleanrm + calls env_update + + @param pkgfiles: files to unmerge (generally self.getcontents() ) + @type pkgfiles: Dictionary + @param trimworld: Remove CPV from world file if True, not if False + @type trimworld: Boolean + @param cleanup: cleanup to pass to doebuild (see doebuild) + @type cleanup: Boolean + @param ldpath_mtimes: mtimes to pass to env_update (see env_update) + @type ldpath_mtimes: Dictionary + @rtype: Integer + @returns: + 1. os.EX_OK if everything went well. + 2. return code of the failed phase (for prerm, postrm, cleanrm) + + Notes: + The caller must ensure that lockdb() and unlockdb() are called + before and after this method. + """ contents = self.getcontents() # Now, don't assume that the name of the ebuild is the same as the @@ -6532,7 +6585,15 @@ class dblink: return os.EX_OK def _unmerge_pkgfiles(self, pkgfiles): - + """ + + Unmerges the contents of a package from the liveFS + Removes the VDB entry for self + + @param pkgfiles: typically self.getcontents() + @type pkgfiles: Dictionary { filename: [ 'type', '?', 'md5sum' ] } + @rtype: None + """ global dircache dircache={} @@ -6651,8 +6712,19 @@ class dblink: self.vartree.zap(self.mycpv) def isowner(self,filename,destroot): - """ check if filename is a new file or belongs to this package - (for this or a previous version)""" + """ + Check if filename is a new file or belongs to this package + (for this or a previous version) + + @param filename: + @type filename: + @param destroot: + @type destroot: + @rtype: Boolean + @returns: + 1. True if this package owns the file. + 2. False if this package does not own the file. + """ destfile = normalize_path( os.path.join(destroot, filename.lstrip(os.path.sep))) try: @@ -6704,12 +6776,37 @@ class dblink: def treewalk(self, srcroot, destroot, inforoot, myebuild, cleanup=0, mydbapi=None, prev_mtimes=None): - # srcroot = ${D}; - # destroot = where to merge, ie. ${ROOT}, - # inforoot = root of db entry, - # secondhand = list of symlinks that have been skipped due to - # their target not existing (will merge later), - + """ + + This function does the following: + + Collision Protection. + calls doebuild(mydo=pkg_preinst) + Merges the package to the livefs + unmerges old version (if required) + calls doebuild(mydo=pkg_postinst) + calls env_update + + @param srcroot: Typically this is ${D} + @type srcroot: String (Path) + @param destroot: Path to merge to (usually ${ROOT}) + @type destroot: String (Path) + @param inforoot: root of the vardb entry ? + @type inforoot: String (Path) + @param myebuild: path to the ebuild that we are processing + @type myebuild: String (Path) + @param mydbapi: dbapi which is handed to doebuild. + @type mydbapi: portdbapi instance + @param prev_mtimes: { Filename:mtime } mapping for env_update + @type prev_mtimes: Dictionary + @rtype: Boolean + @returns: + 1. 0 on success + 2. 1 on failure + + secondhand is a list of symlinks that have been skipped due to their target + not existing; we will merge these symlinks at a later time. + """ if not os.path.isdir(srcroot): writemsg("!!! Directory Not Found: D='%s'\n" % srcroot, noiselevel=-1) -- 2.26.2