[gentoo-commits] proj/gentoopm:master commit in: gentoopm/basepm/

["Michał Górny" <mgorny@gentoo.org>]

commit:     0450187a63419b20fc8d7e5218974d2cdd8dc17e
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jul 10 12:35:08 2011 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Jul 10 12:35:08 2011 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/gentoopm.git;a=commit;h=0450187a

Doc the base PM classes.

---
 gentoopm/basepm/__init__.py |   22 +++++++---
 gentoopm/basepm/atom.py     |    6 +++
 gentoopm/basepm/filter.py   |   19 +++++++--
 gentoopm/basepm/metadata.py |   23 +++++++++--
 gentoopm/basepm/pkg.py      |   88 +++++++++++++++++++++++++++++++++----------
 gentoopm/basepm/repo.py     |   13 ++++++
 gentoopm/basepm/stack.py    |    4 ++
 7 files changed, 139 insertions(+), 36 deletions(-)

diff --git a/gentoopm/basepm/__init__.py b/gentoopm/basepm/__init__.py
index 9b33f1b..10a727c 100644
--- a/gentoopm/basepm/__init__.py
+++ b/gentoopm/basepm/__init__.py
@@ -18,6 +18,8 @@ class PackageManager(ABCObject):
 		"""
 		Return the canonical name of the PM. The value should be static
 		and unique.
+
+		@type: string
 		"""
 		pass
 
@@ -27,7 +29,7 @@ class PackageManager(ABCObject):
 		(Re-)load the configuration of a particular package manager. Set up
 		internal variables.
 
-		Called by default __init__().
+		Called by default L{__init__()}.
 		"""
 		pass
 
@@ -37,15 +39,18 @@ class PackageManager(ABCObject):
 	@abstractproperty
 	def repositories(self):
 		"""
-		Return an PMRepositoryDict (gentoopm.basepm.repo.PMRepositoryDict)
-		subclass referring to the currently enabled ebuild repositories.
+		Currently enabled ebuild repositories.
+
+		@type: L{PMRepositoryDict}
 		"""
 		pass
 
 	@abstractproperty
 	def installed(self):
 		"""
-		Return a PMRepository for installed packages (vardb).
+		Repository with installed packages (vardb).
+
+		@type: L{PMRepository}
 		"""
 		pass
 
@@ -53,14 +58,17 @@ class PackageManager(ABCObject):
 	def stack(self):
 		"""
 		Return a PMRepository providing access to the stacked packages in all
-		ebuild repositories. It returns packages from all the repos, with
-		the repo being the lowest-level key.
+		ebuild repositories. It returns packages from all the repos.
+
+		@type: L{PMRepoStackWrapper}
 		"""
 		return PMRepoStackWrapper(self.repositories)
 
 	@abstractproperty
 	def Atom(self):
 		"""
-		Return the PM-specific atom class.
+		The PM-specific atom class.
+
+		@type: L{PMAtom}
 		"""
 		pass

diff --git a/gentoopm/basepm/atom.py b/gentoopm/basepm/atom.py
index 45674fe..bd631f8 100644
--- a/gentoopm/basepm/atom.py
+++ b/gentoopm/basepm/atom.py
@@ -16,6 +16,9 @@ class PMAtom(ABCObject):
 	def __init__(self, s):
 		"""
 		Create a new atom from string.
+
+		@param s: atom-formatted string
+		@type s: string
 		"""
 		pass
 
@@ -24,5 +27,8 @@ class PMAtom(ABCObject):
 		"""
 		Check whether a package matches the atom (is contained in the set
 		of packages matched by atom).
+
+		@param pkg: a package to match
+		@type pkg: L{PMPackage}
 		"""
 		pass

diff --git a/gentoopm/basepm/filter.py b/gentoopm/basepm/filter.py
index 26d9e37..4347893 100644
--- a/gentoopm/basepm/filter.py
+++ b/gentoopm/basepm/filter.py
@@ -10,26 +10,37 @@ from gentoopm.util import ABCObject
 class PMPackageMatcher(ABCObject):
 	"""
 	Base class for a package matcher.
+
+	Package matcher is basically a function (or function class wrapper) which
+	checks the package for match.
 	"""
 
 	@abstractmethod
 	def __call__(self, pkg):
 		"""
 		Check whether a package matches the condition specified in the matcher.
-		Return True if it does, False otherwise.
+
+		@return: True if the package matches
+		@rtype: bool
 		"""
 		pass
 
 class PMKeywordMatcher(ABCObject):
 	"""
-	Base class for a keyword matcher (one passed as a keyword argument
-	instead of a plain string).
+	Base class for a keyword matcher.
+
+	A keyword matcher is a condition passed as an keyword argument
+	to the L{pkg.PMPackageSet.filter()} function. It's basically an object which will
+	be compared against metadata value using C{==} operator.
 	"""
 
 	@abstractmethod
 	def __eq__(self, val):
 		"""
 		Check whether the value of a metadata key matches the condition
-		specified in the matcher. Return True if it does, False otherwise.
+		specified in the matcher.
+		
+		@return: True if metadata value matches
+		@rtype: bool
 		"""
 		pass

diff --git a/gentoopm/basepm/metadata.py b/gentoopm/basepm/metadata.py
index 73c0961..f2f6bc8 100644
--- a/gentoopm/basepm/metadata.py
+++ b/gentoopm/basepm/metadata.py
@@ -26,6 +26,7 @@ metadata_keys = (
 	'CATEGORY', 'PN', 'PV', 'PR',
 	'P', 'PVR', 'PF'
 )
+""" A common supported metadata key list. """
 
 class PMPackageMetadata(ABCObject):
 	"""
@@ -34,8 +35,13 @@ class PMPackageMetadata(ABCObject):
 
 	def __getitem__(self, key):
 		"""
-		Get the value of a metadata key. Return it as a string, or an empty
-		string when unset.
+		Get the value of a metadata key.
+
+		@param key: the metadata key to catch
+		@type key: string
+		@return: the value of a metadata key, or C{''} when unset
+		@rtype: string
+		@raise KeyError: when invalid metadata key referred
 		"""
 		try:
 			return getattr(self, key)
@@ -48,15 +54,22 @@ class PMPackageMetadata(ABCObject):
 	@abstractmethod
 	def __getattr__(self, key):
 		"""
-		Get the value of a metadata key through an attribute. Return it
-		as a string, or an empty string when unset. Should raise
-		an AttributeError if the key is not in self.
+		Get the value of a metadata key through an attribute.
+
+		@param key: the metadata key to catch
+		@type key: string
+		@return: the value of a metadata key, or C{''} when unset
+		@rtype: string
+		@raise AttributeError: when invalid metadata key referred
 		"""
 		pass
 
 	def __iter__(self):
 		"""
 		Iterate over possible metadata keys.
+
+		@return: available metadata keys
+		@rtype: iter(string)
 		"""
 		return iter(metadata_keys)
 

diff --git a/gentoopm/basepm/pkg.py b/gentoopm/basepm/pkg.py
index b1f8e7d..b1192b1 100644
--- a/gentoopm/basepm/pkg.py
+++ b/gentoopm/basepm/pkg.py
@@ -10,29 +10,37 @@ from gentoopm.exceptions import EmptyPackageSetError, AmbiguousPackageSetError
 from gentoopm.util import ABCObject
 
 class PMPackageSet(ABCObject):
+	""" A set of packages. """
+
 	@abstractmethod
 	def __iter__(self):
 		"""
 		Iterate over the packages (or sets) in a set.
+
+		@return: packages in the set
+		@rtype: iter(L{PMPackage})
 		"""
 		pass
 
 	def filter(self, *args, **kwargs):
 		"""
-		Filter the packages based on arguments. Return a PMFilteredPackageSet
-		evaluating to a number of PMPackages.
+		Filter the packages based on arguments. Return a filtered package set.
 
-		The positional arguments can provide a number of PMPackageMatchers (see
-		gentoopm.basepm.filter) and/or a PMAtom instance. The keyword arguments
-		match metadata keys using '==' comparison with passed string
-		(or PMKeywordMatchers).
+		The positional arguments can provide a number of L{PMPackageMatcher}s
+		and/or a L{PMAtom} instance. The keyword arguments match metadata keys
+		using '==' comparison with passed string (or L{PMKeywordMatcher}s).
 
 		Multiple filters will be AND-ed together. Same applies for .filter()
 		called multiple times. You should, however, avoid passing multiple
 		atoms as it is not supported by all PMs.
 
-		This function can raise KeyError when a keyword argument does reference
-		an incorrect metadata key.
+		@param args: list of package matchers
+		@type args: list(L{PMPackageMatcher},L{PMAtom})
+		@param kwargs: dict of keyword matchers
+		@type kwargs: dict(string -> L{PMKeywordMatcher})
+		@return: filtered package set
+		@rtype: L{PMFilteredPackageSet}
+		@raise KeyError: when invalid metadata key is referenced in kwargs
 		"""
 
 		return PMFilteredPackageSet(self, args, kwargs)
@@ -40,8 +48,12 @@ class PMPackageSet(ABCObject):
 	@property
 	def best(self):
 		"""
-		Return the best-matching package in the set (i.e. flatten it, sort
-		the results and return the first one).
+		Return the best-matching package in the set (the newest one).
+
+		@type: L{PMPackage}
+		@raise EmptyPackageSetError: when no packages match the condition
+		@raise AmbiguousPackageSetError: when packages with different keys
+			match the condition
 		"""
 
 		l = sorted(self, reverse = True)
@@ -58,8 +70,19 @@ class PMPackageSet(ABCObject):
 	def select(self, *args, **kwargs):
 		"""
 		Select a single package matching keys in positional and keyword
-		arguments. This is a convenience wrapper for filter(*args,
-		**kwargs).best.
+		arguments. This is a convenience wrapper for C{filter(*args,
+		**kwargs).best}.
+
+		@param args: list of package matchers
+		@type args: list(L{PMPackageMatcher},L{PMAtom})
+		@param kwargs: dict of keyword matchers
+		@type kwargs: dict(string -> L{PMKeywordMatcher})
+		@return: filtered package set
+		@rtype: L{PMFilteredPackageSet}
+		@raise KeyError: when invalid metadata key is referenced in kwargs
+		@raise EmptyPackageSetError: when no packages match the condition
+		@raise AmbiguousPackageSetError: when packages with different keys
+			match the condition
 		"""
 		try:
 			return self.filter(*args, **kwargs).best
@@ -70,12 +93,17 @@ class PMPackageSet(ABCObject):
 
 	def __getitem__(self, filt):
 		"""
-		Select a single package matching an atom (or filter). Unlike .select(),
+		Select a single package matching an atom (or filter). Unlike L{select()},
 		this one doesn't choose the best match but requires the filter to match
 		exactly one package.
 
-		Raises KeyError when no package matches. Raises ValueError if more than
-		a single package matches.
+		@param filt: a package matcher or an atom
+		@type filt: L{PMPackageMatcher}/L{PMAtom}
+		@return: matching package
+		@rtype: L{PMPackage}
+		@raise EmptyPackageSetError: when no packages match the condition
+		@raise AmbiguousPackageSetError: when packages with different keys
+			match the condition
 		"""
 
 		it = iter(self.filter(filt))
@@ -97,6 +125,11 @@ class PMPackageSet(ABCObject):
 		"""
 		Check whether the package set contains at least a single package
 		matching the filter or package atom passed as an argument.
+
+		@param arg: a package matcher or an atom
+		@type arg: L{PMPackageMatcher}/L{PMAtom}
+		@return: True if at least a single package matched
+		@rtype: bool
 		"""
 
 		i = iter(self.filter(arg))
@@ -119,7 +152,7 @@ class PMFilteredPackageSet(PMPackageSet):
 
 class PMPackage(ABCObject):
 	"""
-	An abstract class representing a single, uniquely-keyed package
+	An abstract class representing a single, uniquely-identified package
 	in the package tree.
 	"""
 
@@ -129,7 +162,13 @@ class PMPackage(ABCObject):
 		method may not be called at all if PM is capable of a more efficient
 		filtering.
 
-		If kwargs reference incorrect metadata keys, a KeyError will be raised.
+		@param args: list of package matchers
+		@type args: list(L{PMPackageMatcher},L{PMAtom})
+		@param kwargs: dict of keyword matchers
+		@type kwargs: dict(string -> L{PMKeywordMatcher})
+		@return: True if package matches
+		@rtype: bool
+		@raise KeyError: when invalid metadata key is referenced in kwargs
 		"""
 
 		for f in args:
@@ -156,8 +195,11 @@ class PMPackage(ABCObject):
 	@abstractproperty
 	def key(self):
 		"""
-		Return the key identifying the package. This is used by .best, to check
-		whether the set doesn't reference more than one package.
+		Return the key identifying the package. This is used by
+		L{PMPackageSet.best}, to check whether the set doesn't reference more
+		than one package.
+
+		@type: string
 		"""
 		pass
 
@@ -165,6 +207,8 @@ class PMPackage(ABCObject):
 	def id(self):
 		"""
 		Return an unique identifier for the package.
+
+		@type: string
 		"""
 		pass
 
@@ -173,13 +217,17 @@ class PMPackage(ABCObject):
 		"""
 		Return path to the ebuild file (or vardb entry) if appropriate.
 		If not available, just return None.
+
+		@type: string/None
 		"""
 		pass
 
 	@abstractproperty
 	def metadata(self):
 		"""
-		Return PMPackageMetadata object for the package.
+		Return the metadata accessor object for the package.
+
+		@type: L{PMPackageMetadata}
 		"""
 		pass
 

diff --git a/gentoopm/basepm/repo.py b/gentoopm/basepm/repo.py
index 87d0825..87b9c3d 100644
--- a/gentoopm/basepm/repo.py
+++ b/gentoopm/basepm/repo.py
@@ -25,6 +25,12 @@ class PMRepositoryDict(ABCObject):
 
 		By default, iterates over the repository list. Can be replaced with
 		something more optimal.
+
+		@param key: repository name or path
+		@type key: string
+		@return: matching repository
+		@rtype: L{PMEbuildRepository}
+		@raise KeyError: when no repository matches the key
 		"""
 		bypath = os.path.isabs(key)
 
@@ -42,6 +48,9 @@ class PMRepositoryDict(ABCObject):
 	def __iter__(self):
 		"""
 		Iterate over the repository list.
+
+		@return: iterator over repositories
+		@rtype: iter(L{PMEbuildRepository})
 		"""
 		pass
 
@@ -64,6 +73,8 @@ class PMEbuildRepository(PMRepository):
 		"""
 		Return the repository name (either from the repo_name file or PM
 		fallback name).
+
+		@type: string
 		"""
 		pass
 
@@ -71,6 +82,8 @@ class PMEbuildRepository(PMRepository):
 	def path(self):
 		"""
 		Return the canonical path to the ebuild repository.
+
+		@type: string
 		"""
 		pass
 

diff --git a/gentoopm/basepm/stack.py b/gentoopm/basepm/stack.py
index ab13dd3..be79749 100644
--- a/gentoopm/basepm/stack.py
+++ b/gentoopm/basepm/stack.py
@@ -6,6 +6,10 @@
 from gentoopm.basepm.repo import PMRepository
 
 class PMRepoStackWrapper(PMRepository):
+	"""
+	A wrapper class providing access to all packages in all repositories.
+	"""
+
 	def __init__(self, repos):
 		self._repos = repos