From 38c923b8b6903dfe81f670be8c556162d99ee652 Mon Sep 17 00:00:00 2001 From: Zac Medico Date: Thu, 9 Nov 2006 10:44:07 +0000 Subject: Thanks again to Chris White for these additional portage_dep docstrings. svn path=/main/trunk/; revision=4999 --- pym/portage_dep.py | 185 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 162 insertions(+), 23 deletions(-) diff --git a/pym/portage_dep.py b/pym/portage_dep.py index 6c60e34af..e5446ef15 100644 --- a/pym/portage_dep.py +++ b/pym/portage_dep.py @@ -23,13 +23,37 @@ import portage_exception from portage_versions import catpkgsplit, catsplit, pkgcmp, pkgsplit, ververify def strip_empty(myarr): + """ + Strip all empty elements from an array + + @param myarr: The list of elements + @type myarr: List + @rtype: Array + @return: The array with empty elements removed + """ for x in range(len(myarr)-1, -1, -1): if not myarr[x]: del myarr[x] return myarr def paren_reduce(mystr,tokenize=1): - "Accepts a list of strings, and converts '(' and ')' surrounded items to sub-lists" + """ + Take a string and convert all paren enclosed entities into sublists, optionally + futher splitting the list elements by spaces. + + Example usage: + >>> paren_reduce('foobar foo ( bar baz )',1) + ['foobar', 'foo', ['bar', 'baz']] + >>> paren_reduce('foobar foo ( bar baz )',0) + ['foobar foo ', [' bar baz ']] + + @param mystr: The string to reduce + @type mystr: String + @param tokenize: Split on spaces to produces further list breakdown + @type tokenize: Integer + @rtype: Array + @return: The reduced string in an array + """ mylist = [] while mystr: if ("(" not in mystr) and (")" not in mystr): @@ -61,6 +85,11 @@ def paren_enclose(mylist): """ Convert a list to a string with sublists enclosed with parens. + Example usage: + >>> test = ['foobar','foo',['bar','baz']] + >>> paren_enclose(test) + 'foobar foo ( bar baz )' + @param mylist: The list @type mylist: List @rtype: String @@ -97,7 +126,7 @@ def use_reduce(deparray, uselist=[], masklist=[], matchall=0, excludeall=[]): raise portage_exception.InvalidDependString(deparray[x]+" missing atom list in \""+paren_enclose(deparray)+"\"") if deparray and deparray[-1] and deparray[-1][-1] == "?": raise portage_exception.InvalidDependString("Conditional without target in \""+paren_enclose(deparray)+"\"") - + mydeparray = deparray[:] rlist = [] while mydeparray: @@ -172,9 +201,9 @@ def dep_opconvert(deplist): list of deps that follows.. Example usage: - >>> test = ["blah", "||", ["foo", "bar", "baz"]] - >>> dep_opconvert(test) - ['blah', ['||', 'foo', 'bar', 'baz']] + >>> test = ["blah", "||", ["foo", "bar", "baz"]] + >>> dep_opconvert(test) + ['blah', ['||', 'foo', 'bar', 'baz']] @param deplist: A list of deps to format @type mydep: List @@ -201,15 +230,15 @@ def get_operator(mydep): Return the operator used in a depstring. Example usage: - >>> from portage_dep import * - >>> get_operator(">=test-1.0") - '>=' + >>> from portage_dep import * + >>> get_operator(">=test-1.0") + '>=' @param mydep: The dep string to check @type mydep: String @rtype: String - @return: - The operator. One of: '~', '=', '>', '<', '=*', '>=', or '<=' + @return: The operator. One of: + '~', '=', '>', '<', '=*', '>=', or '<=' """ if mydep[0] == "~": operator = "~" @@ -229,6 +258,18 @@ def get_operator(mydep): return operator def dep_getcpv(mydep): + """ + Return the category-package-version with any operators/slot specifications stripped off + + Example usage: + >>> dep_getcpv('>=media-libs/test-3.0') + 'media-libs/test-3.0' + + @param mydep: The depstring + @type mydep: String + @rtype: String + @return: The depstring with the operator removed + """ if mydep and mydep[0] == "*": mydep = mydep[1:] if mydep and mydep[-1] == "*": @@ -245,12 +286,40 @@ def dep_getcpv(mydep): return mydep def dep_getslot(mydep): + """ + Retrieve the slot on a depend. + + Example usage: + >>> dep_getslot('app-misc/test:3') + '3' + + @param mydep: The depstring to retrieve the slot of + @type mydep: String + @rtype: String + @return: The slot + """ colon = mydep.rfind(":") if colon != -1: return mydep[colon+1:] return None def isvalidatom(atom): + """ + Check to see if a depend atom is valid + + Example usage: + >>> isvalidatom('media-libs/test-3.0') + 0 + >>> isvalidatom('>=media-libs/test-3.0') + 1 + + @param atom: The depend atom to check against + @type atom: String + @rtype: Integer + @return: One of the following: + 1) 0 if the atom is invalid + 2) 1 if the atom is valid + """ mycpv_cps = catpkgsplit(dep_getcpv(atom)) operator = get_operator(atom) if operator: @@ -273,6 +342,24 @@ def isvalidatom(atom): return 0 def isjustname(mypkg): + """ + Checks to see if the depstring is only the package name + + Example usage: + >>> isjustname('media-libs/test-3.0') + 0 + >>> isjustname('test') + 1 + >>> isjustname('media-libs/test') + 1 + + @param mypkg: The package atom to check + @param mypkg: String + @rtype: Integer + @return: One of the following: + 1) 0 if the package string is not just the package name + 2) 1 if it is + """ myparts = mypkg.split('-') for x in myparts: if ververify(x): @@ -282,7 +369,23 @@ def isjustname(mypkg): iscache = {} def isspecific(mypkg): - "now supports packages with no category" + """ + Checks to see if a package is in category/package-version or package-version format, + possibly returning a cached result. + + Example usage: + >>> isspecific('media-libs/test') + 0 + >>> isspecific('media-libs/test-3.0') + 1 + + @param mypkg: The package depstring to check against + @type mypkg: String + @rtype: Integer + @return: One of the following: + 1) 0 if the package string is not specific + 2) 1 if it is + """ try: return iscache[mypkg] except KeyError: @@ -295,6 +398,18 @@ def isspecific(mypkg): return 0 def dep_getkey(mydep): + """ + Return the category/package-name of a depstring. + + Example usage: + >>> dep_getkey('media-libs/test-3.0') + 'media-libs/test' + + @param mydep: The depstring to retrieve the category/package-name of + @type mydep: String + @rtype: String + @return: The package category/package-version + """ mydep = dep_getcpv(mydep) if mydep and isspecific(mydep): mysplit = catpkgsplit(mydep) @@ -305,8 +420,15 @@ def dep_getkey(mydep): return mydep def match_to_list(mypkg, mylist): - """(pkgname, list) + """ Searches list for entries that matches the package. + + @param mypkg: The package atom to match + @type mypkg: String + @param mylist: The list of package atoms to compare against + @param mylist: List + @rtype: List + @return: A unique list of package atoms that match the given package atom """ matches = [] for x in mylist: @@ -316,18 +438,24 @@ def match_to_list(mypkg, mylist): return matches def best_match_to_list(mypkg, mylist): - """(pkgname, list) + """ Returns the most specific entry that matches the package given. - Type Value - =cpv 6 - ~cpv 5 - =cpv* 4 - cp:slot 3 - >cpv 2 - =cpv 2 - <=cpv 2 - cp 1 + + @param mypkg: The package atom to check + @type mypkg: String + @param mylist: The list of package atoms to check against + @type mylist: List + @rtype: String + @return: The package atom which best matches given the following ordering: + - =cpv 6 + - ~cpv 5 + - =cpv* 4 + - cp:slot 3 + - >cpv 2 + - =cpv 2 + - <=cpv 2 + - cp 1 """ operator_values = {'=':6, '~':5, '=*':4, '>':2, '<':2, '>=':2, '<=':2, None:1} @@ -346,6 +474,17 @@ def best_match_to_list(mypkg, mylist): return bestm def match_from_list(mydep, candidate_list): + """ + Searches list for entries that matches the package. + + @param mydep: The package atom to match + @type mydep: String + @param candidate_list: The list of package atoms to compare against + @param candidate_list: List + @rtype: List + @return: A list of package atoms that match the given package atom + """ + from portage_util import writemsg if mydep[0] == "!": mydep = mydep[1:] -- cgit v1.2.3-1-g7c22