r414 - branches/rewrite/src
Sergio Talens-Oliag
partial-mirror-devel@lists.alioth.debian.org
Thu, 16 Dec 2004 05:31:14 -0700
Author: sto
Date: Thu Dec 16 05:31:12 2004
New Revision: 414
Modified:
branches/rewrite/src/PackageList.py
Log:
Added docstrings
Modified: branches/rewrite/src/PackageList.py
==============================================================================
--- branches/rewrite/src/PackageList.py (original)
+++ branches/rewrite/src/PackageList.py Thu Dec 16 05:31:12 2004
@@ -15,40 +15,53 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
# $Id$
+"""
+PackageList classes and functions
+
+This file implements a class to represent lists of packages and operations
+related to those lists, like dependencies resolution and package filtering
+"""
import re
import os
import apt_pkg
+
class PackageAlreadyExists(Exception):
"""
- Exception called when someone try to add a package but this was already included.
+ Exception called when someone tries to add a package but it was already
+ included.
Attributes:
- package -- The name of package.
+ package -- The name of package.
"""
def __init__(self, package):
Exception.__init__(self)
- self.package = package
-
+ self.package = package
+
class PackageDoesNotExist(Exception):
"""
- Exception called when someone try to remove a package but this doesn't exist.
+ Exception called when someone tries to remove a package that was not
+ included.
Attributes:
package -- The name of package.
"""
def __init__(self, package):
Exception.__init__(self)
- self.package = package
+ self.package = package
class PackageList:
"""
- This class is use to store a list of packages and provide ways to
- filter the information against your information.
+ This class is used to store a list of packages and provide ways to select
+ subsets of those packages applying filters to the list.
+
+ It also provides methods to resolve depencencies (Depends, Recommends and
+ Suggests) against a full set of packages and include the needed packages
+ on the list.
- It make a cache by name, subsection and priority to make things
- faster.
+ To make filtering faster the class includes caches by name, subsection and
+ priority.
"""
def __init__(self):
@@ -70,20 +83,30 @@
return self._name.has_key(item)
def keys(self):
+ """Returns a copy of the list of package names"""
return self._name.keys()
def values(self):
+ """Returns a copy of the list of packages"""
return self._name.values()
def items(self):
+ """Returns a copy of the list of (name, package) pairs"""
return self._name.items()
def get(self, key):
+ """Returns a package given it's name"""
if not self._name.has_key(key):
raise PackageDoesNotExist, key
return self._name[key]
def add(self, package):
+ """
+ Method to add a package to the list (updating caches).
+
+ Note that the package is only added if it's name is not already on the
+ list of packages, or else a PackageAlreadyExists exception is raised.
+ """
if self._name.has_key(package['Package']):
raise PackageAlreadyExists, package['Package']
@@ -103,6 +126,12 @@
self._provides[p].append(package)
def remove(self, package):
+ """
+ Method to remove a package from the list (updating caches).
+
+ If the package was not on the list a PackageDoesNotExist exception is
+ raised.
+ """
if isinstance(package, str):
if not self._name.has_key(package):
raise PackageDoesNotExist, package
@@ -124,6 +153,26 @@
def _satisfyPackage(self, package, field, pkglist, checkingTree = []):
+ """
+ Recursive function used to compute the dependencies of the list of
+ packages against an external package list.
+
+ Parameters:
+
+ - *package*: name of the package being checked.
+
+ - *field*: dependency field being checked:
+
+ - `Depends`, `Pre-Depends`, `Recommends` and `Suggests` for binary
+ packages.
+
+ - `Build-Depends` and `Build-Depends-Indep` for source packages.
+
+ - *pkglist*: PackageList used to resolve the dependencies.
+
+ - *checkingTree*: list of packages already considered on the
+ dependency check, to avoid loops.
+ """
if package.has_key(field):
# Handle ciclical depends
if package in checkingTree:
@@ -166,23 +215,58 @@
return True
def resolveDepends(self, pkglist):
+ """
+ Resolve our dependencies adding needed packages to our list from the
+ `pkglist`.
+ """
for p in self.values():
for field in ('Depends', 'Pre-Depends'):
self._satisfyPackage(p, field, pkglist)
-
- def resolveSuggests(self, pkglist):
- for p in self.values():
- for field in ('Suggests', 'Depends', 'Pre-Depends'):
- self._satisfyPackage(p, field, pkglist)
-
-
def resolveRecommends(self, pkglist):
+ """
+ Add all the recommended packages and the dependencies to our list taking
+ missing ones from `pkglist`.
+
+ Note that the current implementation adds all recommended packages recursively
+ (that is, the Recommends of recommended packages are also included).
+ """
for p in self.values():
for field in ('Recommends', 'Depends', 'Pre-Depends'):
self._satisfyPackage(p, field, pkglist)
+ def resolveSuggests(self, pkglist):
+ """
+ Add all the suggested packages and the dependencies to our list taking
+ missing ones from `pkglist`.
+
+ Note that the current implementation adds all Suggestions recursively
+ (that is, the Suggestions of suggested packages are also included).
+ """
+ for p in self.values():
+ for field in ('Suggests', 'Depends', 'Pre-Depends'):
+ self._satisfyPackage(p, field, pkglist)
+
def filter(self, condition):
+ """
+ Return a PackageList that contains only the packages that verify a set
+ of conditions.
+
+ The condition argument is a dictionary that can have the following keys:
+
+ - *include-from*: includes packages form the given tasksel task
+
+ - *exclude-from*: excludes packages form the given tasksel task
+
+ - *subsection*: includes packages that belong to a section that match
+ the given regular expression
+
+ - *priority*: includes packages that have a priority that match the
+ given regular expression
+
+ - any other key: includes packages that have a name that match the given
+ regular expression.
+ """
packages = PackageList()
for (item, value) in condition.items():