commented client code

7 files changed, 123 insertions, 3 deletions

diff --git a/client/gentoostats/environment.py b/client/gentoostats/environment.py
index 80e717b..79313e1 100644
--- a/client/gentoostats/environment.py
+++ b/client/gentoostats/environment.py
@@ -6,17 +6,32 @@ import portage
 from _emerge.actions import relative_profile_path
 
 class Environment(object):
+    """
+    A class encapsulating all environment and portage variable providers
+    """
 
     def __init__(self):
+        """
+        Initialize the class and portdir
+        """
         self.portdir = portage.settings['PORTDIR']
 
     def getVar(self, myvar):
+        """
+        Return the value of a portage variable
+        """
         return portage.settings[myvar]
 
     def getPlatform(self):
+        """
+        Return host platform
+        """
         return platform.platform(aliased=1)
 
     def getLastSync(self):
+        """
+        Return portage tree last sync time
+        """
         lastsync = None
         try:
             lastsync = portage.grabfile(os.path.join(self.portdir, 'metadata', 'timestamp.chk'))
@@ -27,6 +42,9 @@ class Environment(object):
         return lastsync[0]
 
     def getProfile(self):
+        """
+        Return selected portage profile
+        """
         profilever = None
         profile = portage.settings.profile_path
         if profile:
diff --git a/client/gentoostats/list.py b/client/gentoostats/list.py
index 6ee62cb..78ec0e4 100644
--- a/client/gentoostats/list.py
+++ b/client/gentoostats/list.py
@@ -1,13 +1,19 @@
 
-import utils
+from gentoostats import utils
 
 def pprint(title, object):
+    """
+    Pretty printer for the decoded json data
+    """
     # TODO: write a custom pretty printer here
     import pprint
     print title
     pprint.pprint(object)
 
 def add_parser(subparsers):
+    """
+    Setup argparse parsers
+    """
     # TODO: add help and descriptions for all opts
     list_parser = subparsers.add_parser('list')
     list_subparsers = list_parser.add_subparsers()
@@ -37,26 +43,44 @@ def add_parser(subparsers):
     parser.add_argument('--use')
 
 def list_arch(args):
+    """
+    /arch
+    """
     data = list(args.server, args.url, '/arch', utils.headers)
     pprint('Arch', data)
 
 def list_feature(args):
+    """
+    /feature
+    """
     data = list(args.server, args.url, '/feature', utils.headers)
     pprint('Feature', data)
 
 def list_lang(args):
+    """
+    /lang
+    """
     data = list(args.server, args.url, '/lang', utils.headers)
     pprint('Lang', data)
 
 def list_mirror(args):
+    """
+    /mirror
+    """
     data = list(args.server, args.url, '/mirror', utils.headers)
     pprint('Mirror', data)
 
 def list_repo(args):
+    """
+    /repo
+    """
     data = list(args.server, args.url, '/repo', utils.headers)
     pprint('Repo', data)
 
 def list_package(args):
+    """
+    /package
+    """
     url_top = ''
     if args.top:
         url_top = '?top=' + str(args.top)
@@ -77,6 +101,9 @@ def list_package(args):
     pprint(title, data)
 
 def list_use(args):
+    """
+    /use
+    """
     url_use = '/use'
     title = 'Useflags'
     if args.use:
@@ -88,6 +115,9 @@ def list_use(args):
 
 
 def list(server, url_base, url_extra, headers):
+    """
+    Get and decode json from url
+    """
     get_data = utils.GET(server=server, url=url_base+url_extra, headers=headers)
     data = utils.deserialize(get_data)
     return data
diff --git a/client/gentoostats/metadata.py b/client/gentoostats/metadata.py
index 7d13a4f..33f7bf9 100644
--- a/client/gentoostats/metadata.py
+++ b/client/gentoostats/metadata.py
@@ -5,8 +5,14 @@ from gentoolkit.enalyze.lib import FlagAnalyzer
 from gentoolkit.enalyze.lib import KeywordAnalyser
 
 class Metadata(object):
+    """
+    A class encapsulating all package metadata
+    """
 
     def __init__(self, cpv):
+        """
+        Initialize the class with the cpv. All metadata are read from portage
+        """
         self.repo, self.counter, self.build_time, self.size = VARDB.aux_get(cpv, ['repository', 'COUNTER', 'BUILD_TIME', 'SIZE'])
 
         system_use = portage.settings['USE'].split()
@@ -19,27 +25,51 @@ class Metadata(object):
         self.keyword = ka.get_inst_keyword_cpv(cpv)
 
     def getPlusFlags(self):
+        """
+        Return list of enabled useflags
+        """
         return list(self.flags[0])
 
     def getMinusFlags(self):
+        """
+        Return list of disabled useflags
+        """
         return list(self.flags[1])
 
     def getUnsetFlags(self):
+        """
+        Return list of unset useflags
+        """
         return list(self.flags[2])
 
     def getKeyword(self):
+        """
+        Return keyword used to install package
+        """
         return self.keyword
 
     def getRepoName(self):
+        """
+        Return the repository the package was installed from
+        """
         if self.repo:
             return self.repo
         return 'Unknown'
 
     def getCounter(self):
+        """
+        Return the package install counter. How's this useful ?
+        """
         return self.counter
 
     def getBuildTime(self):
+        """
+        Return the time package was built
+        """
         return self.build_time
 
     def getSize(self):
+        """
+        Return the size of the installed package
+        """
         return self.size
diff --git a/client/gentoostats/packages.py b/client/gentoostats/packages.py
index 39bbde9..6d75ccc 100644
--- a/client/gentoostats/packages.py
+++ b/client/gentoostats/packages.py
@@ -1,17 +1,25 @@
 
-import logging
 import portage
 from gentoostats.dbapi import VARDB
 
 class Packages(object):
+    """
+    A class encapsulating providers for reading installed packages from portage
+    """
 
     def getInstalledCPs(self, sort=False):
+        """
+        Read installed packages as category/packagename
+        """
         installed_cps = VARDB.cp_all()
         if sort:
             return sorted(installed_cps)
         return installed_cps
 
     def getInstalledCPVs(self, sort=False):
+        """
+        Read installed packages as category/packagename-version
+        """
         installed_cpvs = VARDB.cpv_all()
         if sort:
             return sorted(installed_cpvs)
diff --git a/client/gentoostats/payload.py b/client/gentoostats/payload.py
index 1e98b75..b2c459f 100644
--- a/client/gentoostats/payload.py
+++ b/client/gentoostats/payload.py
@@ -7,8 +7,14 @@ from gentoostats.packages import Packages
 from gentoostats.metadata import Metadata
 
 class Payload(object):
+    """
+    A class that encapsulates payload operations
+    """
 
     def __init__(self, configfile):
+        """
+        Initialize the payload using the config file
+        """
         self.config = ConfigParser.ConfigParser()
         if len(self.config.read(configfile)) == 0:
             sys.stderr.write('Cannot read ' + configfile)
@@ -19,6 +25,9 @@ class Payload(object):
         self.update()
 
     def __masked(self, section, item):
+        """
+        Check the mask status of payload
+        """
         try:
             return not self.config.getboolean(section, item)
         except ConfigParser.NoOptionError:
@@ -28,6 +37,9 @@ class Payload(object):
             sys.exit(1)
 
     def update(self):
+        """
+        Read and update the payload
+        """
         env = Environment()
         self.payload['PLATFORM'] = 'Unknown' if self.__masked('ENV', 'PLATFORM') else env.getPlatform()
         self.payload['LASTSYNC'] = 'Unknown' if self.__masked('ENV', 'LASTSYNC') else env.getLastSync()
@@ -55,9 +67,15 @@ class Payload(object):
             self.payload['PACKAGES'][cpv] = p
 
     def get(self):
+        """
+        Return currently read payload
+        """
         return self.payload
 
     def dump(self, human=False):
+        """
+        Dump payload
+        """
         if human:
             pprint.pprint(self.payload)
         else:
diff --git a/client/gentoostats/search.py b/client/gentoostats/search.py
index 4bb040b..dfc4b29 100644
--- a/client/gentoostats/search.py
+++ b/client/gentoostats/search.py
@@ -1,13 +1,19 @@
 
-import utils
+from gentoostats import utils
 
 def pprint(title, object):
+    """
+    Pretty printer for the decoded json data
+    """
     # TODO: write a custom pretty printer here
     import pprint
     print title
     pprint.pprint(object)
 
 def add_parser(subparsers):
+    """
+    Setup argparse parsers
+    """
     # TODO: add help and descriptions for all opts
     search_parser = subparsers.add_parser('search')
     search_parser.add_argument('-c', '--category')
@@ -19,6 +25,9 @@ def add_parser(subparsers):
     search_parser.set_defaults(func=search)
 
 def search(args):
+    """
+    /search
+    """
     url_base = '/search'
     url_extra = ''
 
diff --git a/client/gentoostats/utils.py b/client/gentoostats/utils.py
index 98f8375..43a3c73 100644
--- a/client/gentoostats/utils.py
+++ b/client/gentoostats/utils.py
@@ -2,9 +2,13 @@
 import json
 import httplib
 
+# json headers for gentoostats-cli
 headers = {'Accept': 'application/json'}
 
 def GET(server, url, headers, https=True):
+    """
+    Get url from server using headers 
+    """
     if https:
         conn = httplib.HTTPSConnection(server)
     else:
@@ -17,6 +21,9 @@ def GET(server, url, headers, https=True):
     return data
 
 def deserialize(object):
+    """
+    Decode json object
+    """
     try:
         decoded = json.JSONDecoder().decode(object)
     except (ValueError, TypeError):