Refine code structure and add function descriptions

A futile attempt at making the code more readable.

diff --git a/emerge-timer.py b/emerge-timer.py
index e9b0235b0f11d843f90e6b34235ed7b6c2506ea0..68e9815933043a5d9031f51e4222b0c1b641cbf4 100755 (executable)
--- a/emerge-timer.py
+++ b/emerge-timer.py
@@ -7,12 +7,15 @@ import sys, datetime, os
 PORTDIR = "/usr/portage/"
 LOGFILE = "/var/log/emerge.log"
 
+
 green_start = "\033[32m"
 color_stop = "\033[m"
 
+
 packages = []
 
 
+
 class package:
     def __init__(self, name, version=0):
         self.name = name
@@ -20,12 +23,14 @@ class package:
         self.versions = []
         self.emerge_time = 12*3600
 
-    def add_version(self, version, emerge_time, emerge_date):
 
+    def add_version(self, version, emerge_time, emerge_date):
+        """Add version to the class version list"""
         self.versions.append((version, emerge_time, emerge_date))
 
 
     def average_time(self):
+        """Return average time from class version list"""
         total_time = 0
         for i in self.versions:
             total_time += i[1]
@@ -34,7 +39,9 @@ class package:
 
         return average_time
 
+
     def total_time(self):
+        """Return total time from class version list"""
         total_time = 0
         for i in self.versions:
             total_time += i[1]
@@ -43,18 +50,21 @@ class package:
 
 
     def max_time(self):
+        """Return maximum time from class version list"""
         self.versions.sort()
 
         return self.versions[len(self.versions)-1][1]
 
 
     def min_time(self):
+        """Return minimum time from class version list"""
         self.versions.sort()
 
         return self.versions[0][1]
 
 
     def print_current_emerge(self):
+        """Function used to print all the current emerge stuff"""
 
         print("\t" + green_start + self.name + '-' + self.version +
               color_stop + "\n\t current time: " + self.time(self.emerge_time) +
@@ -78,17 +88,25 @@ class package:
 
 
     def print_versions(self):
+        """This prints the emerge times for different versions in the
+        normal operating mode of the script"""
+
         for p in self.versions:
+
             print('-'*90 + "\n" +
                   green_start + self.name + p[0] + color_stop + "  >>>  " +
                   self.time(p[1]) + "  >>>  " +
                   self.date(p[2]))
+
         print('-'*90 + "\n" + "Package " + green_start +
               self.name + color_stop + " emerged " +
               str(len(self.versions)) + " times.")
+
         print
 
+
     def print_pretended_times(self):
+        """This is used the print all the pretended times"""
         print("\t" + green_start + self.name + '-' + self.version + color_stop),
 
         if len(self.versions) > 1:
@@ -109,8 +127,9 @@ class package:
               "\nIn total spent " + self.time(total) +
               " emerging " + green_start + self.name + color_stop)
 
-    def time(self, time):
 
+    def time(self, time):
+        """Converts time in seconds to human readable form"""
         days = time/(3600*24)
         hours = (days - int(days))*24
         minutes = (hours - int(hours))*60
@@ -157,6 +176,7 @@ class package:
 
 
     def date(self, emerge_date):
+        """Returns a date string from a standard POSIX time"""
         date = datetime.datetime.fromtimestamp(emerge_date)
 
         date = "{:%d.%m.%Y %H:%M:%S}".format(date)
@@ -179,12 +199,15 @@ def open_log():
 
 
 def search_log_for_package(package_class):
+    """Searchs emerge log for given package and adds all found
+    versions with their emerge times to the class"""
 
     log = open_log()
 
     for line in log:
         if ((">>>" in line) and ("emerge" in line)):
             if package_class.name in line:
+
                 version = line.partition(package_class.name)[2].partition(' ')[0]
                 digit = version.strip('-')[0].isdigit()
 
@@ -193,6 +216,7 @@ def search_log_for_package(package_class):
                     start_time = float(time_string[0].strip().strip(':'))
 
         elif ((":::" in line) and ("completed emerge" in line)):
+
             if package_class.name in line:
                 if digit:
                     time_string = line.partition(":::")
@@ -203,6 +227,7 @@ def search_log_for_package(package_class):
                     package_class.add_version(version, emerge_time, start_time)
 
 
+
 def get_package(name):
     """Take the user-input package name and search for it
     in PORTDIR. """
@@ -253,7 +278,12 @@ def get_package(name):
     sys.exit(1)
 
 
+
 def list_pretended():
+    """List all the pretended packages given by emerge -p
+    output. Create a class out of each of those packages and add them
+    to the list."""
+
     log = open_log()
 
     for line in sys.stdin:
@@ -268,6 +298,7 @@ def list_pretended():
             packages.append(package(package_name, version))
 
 
+
 def list_emerge_processes():
     """Look for the ebuild process with ps. If the process is found parse
     the command for the package. With this package search the LOGFILE for
@@ -311,9 +342,8 @@ def list_emerge_processes():
 
 
 
-
-
 def main(status, user_package=None):
+    """Main function. Hanlde all the different modes of operation."""
 
     if status == "package":
         user_package = get_package(user_package)
@@ -346,6 +376,7 @@ def main(status, user_package=None):
             print
 
 
+
 def usage():
     usage = """Usage: emerge-timer.py [package] [options]
 
@@ -369,6 +400,7 @@ if __name__ == "__main__":
     mode = "package"
     input_package = None
 
+
     for arg in sys.argv[1:]:
 
         if arg == "-p" or arg == "--pretended":