Numerous improvements and fixes

Documented most of the functions and classes.

Added an option to fetch a package into a specified directory.

Added a merge_into method to the Package class, which would merge it
into a directory, and refactored repo::merge_package to use that.

Extended the package class to store category, version and slot metadata.

Added tests of the portage package source module.

2 files changed, 26 insertions, 1 deletions

diff --git a/pomu/source/manager.py b/pomu/source/manager.py
index f36eb90..9d3e2de 100644
--- a/pomu/source/manager.py
+++ b/pomu/source/manager.py
@@ -37,12 +37,22 @@ class PackageDispatcher():
         self.handlers = []
 
     def source(self, cls):
+        """
+        A decorator to mark package source modules
+        It would register all the methods of the class marked by @handler
+        with the dispatcher.
+        """
         for m, obj in inspect.getmembers(cls):
             if isinstance(obj, self.handler._handler):
                 self.register_package_handler(cls, obj.handler, obj.priority)
         return cls
 
     class handler():
+        """
+        A decorator to denote package source module handler, which
+        should attempt to parse a package descriptor. If it succeeds,
+        the result would be passed to the module for further processing.
+        """
         class _handler():
             def __init__(self, handler):
                 self.handler = handler
@@ -58,6 +68,10 @@ class PackageDispatcher():
             return x
 
     def register_package_handler(self, source, handler, priority):
+        """
+        Register a package handler for a specified source.
+        Handlers with lower priority get called first.
+        """
         i = 0
         for i in range(len(self.handlers)):
             if self.handlers[0][0] > priority:
@@ -65,12 +79,14 @@ class PackageDispatcher():
         self.handlers.insert(i, (priority, source, handler))
 
     def get_package_source(self, uri):
+        """Get a source which accepts the package"""
         for priority, source, handler in self.handlers:
             if handler(uri).is_ok():
                 return source
         return None
 
     def get_package(self, uri):
+        """Fetch a package specified by the descriptor"""
         for priority, source, handler in self.handlers:
             res = handler(uri)
             if res.is_ok():
@@ -78,9 +94,11 @@ class PackageDispatcher():
         return Result.Err('No handler found for package ' + uri)
 
     def install_package(self, uri):
+        """Install a package specified by the descriptor"""
         pkg = self.get_package(uri).unwrap()
         return pomu_active_repo().merge(pkg)
 
     def uninstall_package(self, uri):
+        """Uninstall a package specified by the descriptor"""
         pkg = self.get_package(uri).unwrap()
         return pomu_active_repo().unmerge(pkg)
diff --git a/pomu/source/portage.py b/pomu/source/portage.py
index aaf5c1c..6e58873 100644
--- a/pomu/source/portage.py
+++ b/pomu/source/portage.py
@@ -26,6 +26,7 @@ class PortagePackage():
 
     def fetch(self):
         return Package(self.name, portage_repo_path(self.repo),
+                category=self.category, version=self.version, slot=self.slot,
                 files=[path.join(self.category, self.name, 'metadata.xml'),
                     path.join(self.category, self.name, self.name + '-' + self.version + '.ebuild')])
 
@@ -38,6 +39,7 @@ misc_dirs = ['profiles', 'licenses', 'eclass', 'metadata', 'distfiles', 'package
 
 @dispatcher.source
 class PortageSource():
+    """The source module responsible for fetching portage packages"""
     @dispatcher.handler(priority=5)
     def parse_spec(uri, repo=None):
         # dev-libs/openssl-0.9.8z_p8-r100:0.9.8::gentoo
@@ -77,6 +79,10 @@ class PortageSource():
 
 
 def sanity_check(repo, category, name, vernum, suff, rev, slot):
+    """
+    Checks whether a package descriptor is valid and corresponds
+    to a package in a configured portage repository
+    """
     if not name:
         return False
     if repo and repo not in list(portage_repos()):
@@ -95,10 +101,11 @@ def sanity_check(repo, category, name, vernum, suff, rev, slot):
 
 
 def ver_str(vernum, suff, rev):
+    """Gets the string representation of the version"""
     return vernum + (suff if suff else '') + (rev if rev else '')
 
 def best_ver(repo, category, name, ver=None):
-    """Gets the best (newest) version of a package  in the repo"""
+    """Gets the best (newest) version of a package in the repo"""
     ebuilds = [category + '/' + name + x[len(name):-7] for x in
             os.listdir(path.join(portage_repo_path(repo), category, name))
             if x.endswith('.ebuild')]