summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAlec Warner <antarus@gentoo.org>2006-12-25 04:52:11 +0000
committerAlec Warner <antarus@gentoo.org>2006-12-25 04:52:11 +0000
commit4343fbef79335369313538a07e67db2210e2b516 (patch)
tree3b73faba658e1e6a3c14b6ae6b255570a1f6e7bc
parent967ada0394ca156938e81539bf4ac233a5b0f93c (diff)
downloadportage-4343fbef79335369313538a07e67db2210e2b516.tar.gz
portage-4343fbef79335369313538a07e67db2210e2b516.tar.bz2
portage-4343fbef79335369313538a07e67db2210e2b516.zip
more docstrings..
svn path=/main/trunk/; revision=5385
-rw-r--r--pym/portage.py125
1 files 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)