From 68d5504f7cd53bcbadc30502229e0ab38cf62107 Mon Sep 17 00:00:00 2001 From: necoro <> Date: Fri, 13 Oct 2006 13:11:24 +0000 Subject: Documentation work --- geneticone/backend/portage_helper.py | 128 +++++++++++++++++++++++++++-------- 1 file changed, 101 insertions(+), 27 deletions(-) (limited to 'geneticone/backend/portage_helper.py') diff --git a/geneticone/backend/portage_helper.py b/geneticone/backend/portage_helper.py index 23172e5..37a2b91 100644 --- a/geneticone/backend/portage_helper.py +++ b/geneticone/backend/portage_helper.py @@ -19,12 +19,14 @@ import package def find_lambda (name): """Returns the function needed by all the find_all_*-functions. Returns None if no name is given. + @param name: name to build the function of @type name: string @returns: 1. None if no name is given 2. a lambda function @rtype: function""" + if name != None: return lambda x: re.match(".*"+name+".*",x) else: @@ -32,10 +34,12 @@ def find_lambda (name): def geneticize_list (list_of_packages): """Convertes a list of gentoolkit.Packages into L{backend.Package}s. + @param list_of_packages: the list of packages @type list_of_packages: list of gentoolkit.Packages @returns: converted list - @rtype: list of geneticone.backend.Packages""" + @rtype: backend.Package[]""" + return [package.Package(x) for x in list_of_packages] def find_best_match (search_key, only_installed = False): @@ -47,7 +51,7 @@ def find_best_match (search_key, only_installed = False): @type only_installed: boolean @returns: the package found or None - @rtype: backend.Package or None""" + @rtype: backend.Package""" t = None if not only_installed: @@ -60,39 +64,59 @@ def find_best_match (search_key, only_installed = False): def find_packages (search_key, masked=False): """This returns a list of packages which have to fit exactly. Additionally ranges like '<,>,=,~,!' et. al. are possible. + @param search_key: the key to look for @type search_key: string @param masked: if True, also look for masked packages @type masked: boolean + @returns: list of found packages - @rtype: list of backend.Package""" + @rtype: backend.Package[]""" return geneticize_list(gentoolkit.find_packages(search_key, masked)) def find_installed_packages (search_key, masked=False): """This returns a list of packages which have to fit exactly. Additionally ranges like '<,>,=,~,!' et. al. are possible. + @param search_key: the key to look for @type search_key: string @param masked: if True, also look for masked packages @type masked: boolean + @returns: list of found packages - @rtype: list of backend.Package""" + @rtype: backend.Package[]""" return geneticize_list(gentoolkit.find_installed_packages(search_key, masked)) def find_system_packages (): - """Returns a list-tuple (resolved_packages, unresolved_packages) for all system packages.""" + """Looks for all packages saved as "system-packages". + + @returns: a tuple of (resolved_packages, unresolved_packages). + @rtype: (backend.Package[], backend.Package[])""" + list = gentoolkit.find_system_packages() return (geneticize_list(list[0]), geneticize_list(list[1])) def find_world_packages (): - """Returns a list-tuple (resolved_packages, unresolved_packages) for all packages in the world-file.""" + """Looks for all packages saved in the world-file. + + @returns: a tuple of (resolved_packages, unresolved_packages). + @rtype: (backend.Package[], backend.Package[])""" + list = gentoolkit.find_world_packages() return geneticize_list(list[0]),geneticize_list(list[1]) def find_all_installed_packages (name=None, withVersion=True): - """Returns a list of all installed packages matching ".*name.*". - Returns ALL installed packages if name is None.""" + """Finds all installed packages matching a name or all if no name is specified. + + @param name: the name to look for - it is expanded to .*name.* ; if None, all packages are returned + @type name: string or None + @param withVersion: if True version-specific packages are returned; else only the cat/package-strings a delivered + @type withVersion: boolean + + @returns: all packages/cp-strings found + @rtype: backend.Package[] or cp-string[]""" + if withVersion: return geneticize_list(gentoolkit.find_all_installed_packages(find_lambda(name))) else: @@ -102,13 +126,26 @@ def find_all_installed_packages (name=None, withVersion=True): return t def find_all_uninstalled_packages (name=None): - """Returns a list of all uninstalled packages matching ".*name.*". - Returns ALL uninstalled packages if name is None.""" + """Finds all uninstalled packages matching a name or all if no name is specified. + + @param name: the name to look for - it is expanded to .*name.* ; if None, all packages are returned + @type name: string or None + @returns: all packages found + @rtype: backend.Package[]""" + return geneticize_list(gentoolkit.find_all_uninstalled_packages(find_lambda(name))) -def find_all_packages (name=None, withVersion = True): - """Returns a list of all packages matching ".*name.*". - Returns ALL packages if name is None.""" +def find_all_packages (name=None, withVersion=True): + """Finds all packages matching a name or all if no name is specified. + + @param name: the name to look for - it is expanded to .*name.* ; if None, all packages are returned + @type name: string or None + @param withVersion: if True version-specific packages are returned; else only the cat/package-strings a delivered + @type withVersion: boolean + + @returns: all packages/cp-strings found + @rtype: backend.Package[] or cp-string[]""" + if (withVersion): return geneticize_list(gentoolkit.find_all_packages(find_lambda(name))) else: @@ -120,25 +157,37 @@ def find_all_packages (name=None, withVersion = True): return t def find_all_world_packages (name=None): - """Returns a list of all world packages matching ".*name.*". - Returns ALL world packages if name is None.""" + """Finds all world packages matching a name or all if no name is specified. + + @param name: the name to look for - it is expanded to .*name.* ; if None, all packages are returned + @type name: string or None + @returns: all packages found + @rtype: backend.Package[]""" + world = filter(find_lambda(name), [x.get_cpv() for x in find_world_packages()[0]]) world = unique_array(world) - return [package.Package(x) for x in world] + return geneticize_list(world) def find_all_system_packages (name=None): - """Returns a list of all system packages matching ".*name.*". - Returns ALL system packages if name is None.""" + """Finds all system packages matching a name or all if no name is specified. + + @param name: the name to look for - it is expanded to .*name.* ; if None, all packages are returned + @type name: string or None + @returns: all packages found + @rtype: backend.Package[]""" + sys = filter(find_lambda(name), [x.get_cpv() for x in find_system_packages()[0]]) sys = unique_array(sys) - return [package.Package(x) for x in sys] + return geneticize_list(sys) def get_all_versions (cp): """Returns all versions of a certain package. + @param cp: the package @type cp: string (cat/pkg) @returns: the list of found packages - @rtype: list of backend.Package""" + @rtype: backend.Package[]""" + t = porttree.dbapi.cp_list(cp) t += vartree.dbapi.cp_list(cp) t = unique_array(t) @@ -146,25 +195,41 @@ def get_all_versions (cp): def get_all_installed_versions (cp): """Returns all installed versions of a certain package. + @param cp: the package @type cp: string (cat/pkg) @returns: the list of found packages - @rtype: list of backend.Package""" + @rtype: backend.Package[]""" + return geneticize_list(vartree.dbapi.cp_list(cp)) def list_categories (name=None): - """Returns a list of categories matching ".*name.*" or all categories.""" + """Finds all categories matching a name or all if no name is specified. + + @param name: the name to look for - it is expanded to .*name.* ; if None, all categories are returned + @type name: string or None + @returns: all categories found + @rtype: string[]""" + categories = gentoolkit.settings.categories return filter(find_lambda(name), categories) def split_package_name (name): - """Returns a list in the form [category, name, version, revision]. Revision will - be 'r0' if none can be inferred. Category and version will be empty, if none can - be inferred.""" + """Splits a package name in its elements. + + @param name: name to split + @type name: string + @returns: list: [category, name, version, rev] whereby rev is "r0" if not specified in the name + @rtype: string[]""" + return gentoolkit.split_package_name(name) def sort_package_list(pkglist): - """Sorts a package list in the same manner portage does.""" + """Sorts a package list in the same manner portage does. + + @param pkglist: list to sort + @type pkglist: Packages[]""" + return gentoolkit.sort_package_list(pkglist) def reload_settings (): @@ -176,7 +241,16 @@ local_use_descs = {} def get_use_desc (flag, package = None): """Returns the description of a specific useflag or None if no desc was found. If a package is given (in the / format) the local use descriptions are searched too. - In the first run the dictionaries 'use_descs' and 'local_use_descs' are filled.""" + + @param flag: flag to get the description for + @type flag: string + @param package: name of a package: if given local use descriptions are searched too + @type package: cp-string + @returns: found description + @rtype: string""" + + # In the first run the dictionaries 'use_descs' and 'local_use_descs' are filled. + # fill cache if needed if use_descs == {} or local_use_descs == {}: # read use.desc -- cgit v1.2.3-54-g00ecf