commit: 75dfea84dea28ca2e14b6f1cb7bc3ca1c2f87a0c Author: Rolf Eike Beer <eike <AT> sf-mail <DOT> de> AuthorDate: Thu May 9 18:12:14 2019 +0000 Commit: Zac Medico <zmedico <AT> gentoo <DOT> org> CommitDate: Sat May 11 20:45:26 2019 +0000 URL: https://gitweb.gentoo.org/proj/portage.git/commit/?id=75dfea84
really fix some dep API documentation -interface description needs to be last for epydoc, even if it works at some places when it is not -fix some other minor things like wrong parameter names and missing types Closes: https://github.com/gentoo/portage/pull/426 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 | 112 +++++++++++++++++++++++--------------------- 1 file changed, 58 insertions(+), 54 deletions(-) diff --git a/lib/portage/dep/__init__.py b/lib/portage/dep/__init__.py index 418bfa011..285e0c2ec 100644 --- a/lib/portage/dep/__init__.py +++ b/lib/portage/dep/__init__.py @@ -186,20 +186,20 @@ def _get_useflag_re(eapi): def cpvequal(cpv1, cpv2): """ + Example Usage: + >>> from portage.dep import cpvequal + >>> cpvequal("sys-apps/portage-2.1","sys-apps/portage-2.1") + >>> True + @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" @type cpv2: String @rtype: Boolean @return: - 1. True if cpv1 = cpv2 - 2. False Otherwise - 3. Throws PortageException if cpv1 or cpv2 is not a CPV - - Example Usage: - >>> from portage.dep import cpvequal - >>> cpvequal("sys-apps/portage-2.1","sys-apps/portage-2.1") - >>> True + 1. True if cpv1 = cpv2 + 2. False Otherwise + 3. Throws PortageException if cpv1 or cpv2 is not a CPV """ try: @@ -411,8 +411,8 @@ def use_reduce(depstr, uselist=[], masklist=[], matchall=False, excludeall=[], i Takes a dep string and reduces the use? conditionals out, leaving an array with subarrays. All redundant brackets are removed. - @param deparray: depstring - @type deparray: String + @param depstr: depstring + @type depstr: String @param uselist: List of use enabled flags @type uselist: List @param masklist: List of masked flags (always treated as disabled) @@ -734,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 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.") % \ @@ -1434,7 +1434,7 @@ class Atom(_unicode): """ Returns True if slot_operator == "=" and sub_slot is not None. NOTE: foo/bar:2= is unbuilt and returns False, whereas foo/bar:2/2= - is built and returns True. + is built and returns True. """ return self.slot_operator == "=" and self.sub_slot is not None @@ -1729,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) @@ -1749,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) @@ -1767,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: @@ -1823,13 +1823,17 @@ def dep_getrepo(mydep): else: return mydep[colon+2:bracket] return None + def remove_slot(mydep): """ Removes dep components from the right side of an atom: - * slot - * use - * repo + - slot + - use + - repo And repo_name from the left side. + + @type mydep: String + @rtype: String """ colon = mydep.find(_slot_separator) if colon != -1: @@ -1897,18 +1901,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: @@ -1930,18 +1934,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): @@ -1960,18 +1964,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): @@ -1987,14 +1991,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)
