commit: 7f2c4b0d402be190a9575346a76e3ee9361179ac Author: Rolf Eike Beer <eike <AT> sf-mail <DOT> de> AuthorDate: Sat May 4 17:54:22 2019 +0000 Commit: Zac Medico <zmedico <AT> gentoo <DOT> org> CommitDate: Sat May 4 21:08:03 2019 +0000 URL: https://gitweb.gentoo.org/proj/portage.git/commit/?id=7f2c4b0d
fix some documentation in the dep API -fix bad parameter names -fix duplicate @param that should be @type -move "Example usage:" below the parameter list Closes: https://github.com/gentoo/portage/pull/424 Signed-off-by: Rolf Eike Beer <eike <AT> sf-mail.de> Signed-off-by: Zac Medico <zmedico <AT> gentoo.org> lib/portage/dep/__init__.py | 140 ++++++++++++++++++++++---------------------- 1 file changed, 69 insertions(+), 71 deletions(-) diff --git a/lib/portage/dep/__init__.py b/lib/portage/dep/__init__.py index 26595da47..418bfa011 100644 --- a/lib/portage/dep/__init__.py +++ b/lib/portage/dep/__init__.py @@ -186,7 +186,6 @@ def _get_useflag_re(eapi): def cpvequal(cpv1, cpv2): """ - @param cpv1: CategoryPackageVersion (no operators) Example: "sys-apps/portage-2.1" @type cpv1: String @param cpv2: CategoryPackageVersion (no operators) Example: "sys-apps/portage-2.1" @@ -201,7 +200,6 @@ def cpvequal(cpv1, cpv2): >>> from portage.dep import cpvequal >>> cpvequal("sys-apps/portage-2.1","sys-apps/portage-2.1") >>> True - """ try: @@ -384,15 +382,15 @@ def paren_enclose(mylist, unevaluated_atom=False, opconvert=False): """ 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 @return: The paren enclosed string + + Example usage: + >>> test = ['foobar','foo',['bar','baz']] + >>> paren_enclose(test) + 'foobar foo ( bar baz )' """ mystrparts = [] for x in mylist: @@ -736,16 +734,16 @@ def dep_opconvert(deplist): dep is a '||' or '&&' operator, combine it with the list of deps that follows.. - Example usage: - >>> test = ["blah", "||", ["foo", "bar", "baz"]] - >>> dep_opconvert(test) - ['blah', ['||', 'foo', 'bar', 'baz']] - @param deplist: A list of deps to format - @type mydep: List + @type deplist: List @rtype: List @return: The new list with the new ordering + + Example usage: + >>> test = ["blah", "||", ["foo", "bar", "baz"]] + >>> dep_opconvert(test) + ['blah', ['||', 'foo', 'bar', 'baz']] """ if portage._internal_caller: warnings.warn(_("%s is deprecated. Use %s with the opconvert parameter set to True instead.") % \ @@ -769,14 +767,14 @@ def flatten(mylist): Recursively traverse nested lists and return a single list containing all non-list elements that are found. - Example usage: - >>> flatten([1, [2, 3, [4]]]) - [1, 2, 3, 4] - @param mylist: A list containing nested lists and non-list elements. @type mylist: List @rtype: List @return: A single list containing only non-list elements. + + Example usage: + >>> flatten([1, [2, 3, [4]]]) + [1, 2, 3, 4] """ if portage._internal_caller: warnings.warn(_("%s is deprecated and will be removed without replacement.") % \ @@ -1731,16 +1729,16 @@ def get_operator(mydep): """ Return the operator used in a depstring. - Example usage: - >>> 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 '<=' + + Example usage: + >>> from portage.dep import * + >>> get_operator(">=test-1.0") + '>=' """ if not isinstance(mydep, Atom): mydep = Atom(mydep) @@ -1751,14 +1749,14 @@ 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 + + Example usage: + >>> dep_getcpv('>=media-libs/test-3.0') + 'media-libs/test-3.0' """ if not isinstance(mydep, Atom): mydep = Atom(mydep) @@ -1769,14 +1767,14 @@ 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 + + Example usage: + >>> dep_getslot('app-misc/test:3') + '3' """ slot = getattr(mydep, "slot", False) if slot is not False: @@ -1798,14 +1796,14 @@ def dep_getrepo(mydep): """ Retrieve the repo on a depend. - Example usage: - >>> dep_getrepo('app-misc/test::repository') - 'repository' - @param mydep: The depstring to retrieve the repository of @type mydep: String @rtype: String @return: The repository name + + Example usage: + >>> dep_getrepo('app-misc/test::repository') + 'repository' """ repo = getattr(mydep, "repo", False) if repo is not False: @@ -1845,15 +1843,15 @@ def remove_slot(mydep): def dep_getusedeps( depend ): """ Pull a listing of USE Dependencies out of a dep atom. - - Example usage: - >>> dep_getusedeps('app-misc/test:3[foo,-bar]') - ('foo', '-bar') - + @param depend: The depstring to process @type depend: String @rtype: List @return: List of use flags ( or [] if no flags exist ) + + Example usage: + >>> dep_getusedeps('app-misc/test:3[foo,-bar]') + ('foo', '-bar') """ use_list = [] open_bracket = depend.find('[') @@ -1899,18 +1897,18 @@ def isvalidatom(atom, allow_blockers=False, allow_wildcard=False, """ Check to see if a depend atom is valid - Example usage: - >>> isvalidatom('media-libs/test-3.0') - False - >>> isvalidatom('>=media-libs/test-3.0') - True - @param atom: The depend atom to check against @type atom: String or Atom @rtype: Boolean @return: One of the following: 1) False if the atom is invalid 2) True if the atom is valid + + Example usage: + >>> isvalidatom('media-libs/test-3.0') + False + >>> isvalidatom('>=media-libs/test-3.0') + True """ if eapi is not None and isinstance(atom, Atom) and atom.eapi != eapi: @@ -1932,18 +1930,18 @@ def isjustname(mypkg): """ Checks to see if the atom is only the package name (no version parts). - Example usage: - >>> isjustname('=media-libs/test-3.0') - False - >>> isjustname('media-libs/test') - True - @param mypkg: The package atom to check @param mypkg: String or Atom @rtype: Integer @return: One of the following: 1) False if the package string is not just the package name 2) True if it is + + Example usage: + >>> isjustname('=media-libs/test-3.0') + False + >>> isjustname('media-libs/test') + True """ try: if not isinstance(mypkg, Atom): @@ -1962,18 +1960,18 @@ def isspecific(mypkg): Checks to see if a package is in =category/package-version or package-version format. - Example usage: - >>> isspecific('media-libs/test') - False - >>> isspecific('=media-libs/test-3.0') - True - @param mypkg: The package depstring to check against @type mypkg: String @rtype: Boolean @return: One of the following: 1) False if the package string is not specific 2) True if it is + + Example usage: + >>> isspecific('media-libs/test') + False + >>> isspecific('=media-libs/test-3.0') + True """ try: if not isinstance(mypkg, Atom): @@ -1989,14 +1987,14 @@ 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-name + + Example usage: + >>> dep_getkey('=media-libs/test-3.0') + 'media-libs/test' """ if not isinstance(mydep, Atom): mydep = Atom(mydep, allow_wildcard=True, allow_repo=True) @@ -2010,7 +2008,7 @@ def match_to_list(mypkg, mylist): @param mypkg: The package atom to match @type mypkg: String @param mylist: The list of package atoms to compare against - @param mylist: List + @type mylist: List @rtype: List @return: A unique list of package atoms that match the given package atom """ @@ -2107,7 +2105,7 @@ def match_from_list(mydep, candidate_list): @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 + @type candidate_list: List @rtype: List @return: A list of package atoms that match the given package atom """ @@ -2524,15 +2522,15 @@ class _RequiredUseBranch(object): def check_required_use(required_use, use, iuse_match, eapi=None): """ Checks if the use flags listed in 'use' satisfy all - constraints specified in 'constraints'. + constraints specified in 'required_use'. @param required_use: REQUIRED_USE string @type required_use: String @param use: Enabled use flags - @param use: List + @type use: List @param iuse_match: Callable that takes a single flag argument and returns True if the flag is matched, false otherwise, - @param iuse_match: Callable + @type iuse_match: Callable @rtype: Bool @return: Indicates if REQUIRED_USE constraints are satisfied """ @@ -2711,17 +2709,17 @@ def extract_affecting_use(mystr, atom, eapi=None): Take a dep string and an atom and return the use flags that decide if the given atom is in effect. - Example usage: - >>> extract_affecting_use('sasl? ( dev-libs/cyrus-sasl ) \ - !minimal? ( cxx? ( dev-libs/cyrus-sasl ) )', 'dev-libs/cyrus-sasl') - {'cxx', 'minimal', 'sasl'} - @param mystr: The dependency string @type mystr: String @param atom: The atom to get into effect @type atom: String @rtype: Set of strings @return: Set of use flags affecting given atom + + Example usage: + >>> extract_affecting_use('sasl? ( dev-libs/cyrus-sasl ) \ + !minimal? ( cxx? ( dev-libs/cyrus-sasl ) )', 'dev-libs/cyrus-sasl') + {'cxx', 'minimal', 'sasl'} """ useflag_re = _get_useflag_re(eapi) mysplit = mystr.split()
