found a bug and added docstrings

roles/2-common/templates/iiab_lib.py

@@ -1,7 +1,7 @@
-# iiab_lib.py
-# common functions for IIAB
-# Admin Console functions are in adm_lib.py
-
+'''
+Common functions for IIAB
+Admin Console functions are in adm_lib.py
+'''
 import os
 import json
 import subprocess
@@ -12,9 +12,19 @@ import iiab.iiab_const as CONST
 lang_codes = {}
 
 def get_zim_list(path):
+    '''
+    Get a list of installed zims in the passed path
+
+    Args:
+      path (str): The path to search
+
+    Returns:
+      files_processed (dict): A dict all zims found and any index directory (now obsolete)
+      zim_versions (dict): A dict that translates generic zim names to physically installed
+    '''
+
     files_processed = {}
     zim_versions = {} # we don't need this unless adm cons is installed, but easier to compute now
-    zim_list = []
     content = path + "/content/"
     index = path + "/index/"
     flist = os.listdir(content)
@@ -45,7 +55,18 @@ def get_zim_list(path):
     return files_processed, zim_versions
 
 def read_library_xml(lib_xml_file, kiwix_exclude_attr=[""]): # duplicated from iiab-cmdsrv
-    # returns dict of library.xml and map of zim id to zim file name (under <dev>/library/zims)
+    '''
+    Read zim properties from library.xml
+    Returns dict of library.xml and map of zim id to zim file name (under <dev>/library/zims)
+
+    Args:
+      lib_xml_file (str): Path to file to read. Can be on removable device
+      kiwix_exclude_attr (list): Zim properties to exclude from return
+
+    Returns:
+      zims_installed (dict): A dictionary holding all installed zims and their attributes
+      path_to_id_map (dict): A dictionary that translates zim ids to physical names
+    '''
 
     kiwix_exclude_attr.append("id") # don't include id
     kiwix_exclude_attr.append("favicon") # don't include large favicon
@@ -54,9 +75,7 @@ def read_library_xml(lib_xml_file, kiwix_exclude_attr=[""]): # duplicated from i
     try:
         tree = ET.parse(lib_xml_file)
         root = tree.getroot()
-        xml_item_no = 0
         for child in root:
-            #xml_item_no += 1 # hopefully this is the array number
             attributes = {}
             if 'id' not in child.attrib: # is this necessary? implies there are records with no book id which would break index for removal
                 print("xml record missing Book Id")
@@ -71,6 +90,14 @@ def read_library_xml(lib_xml_file, kiwix_exclude_attr=[""]): # duplicated from i
     return zims_installed, path_to_id_map
 
 def rem_libr_xml(zim_id, kiwix_library_xml):
+    '''
+    Remove a zim from library.xml
+
+    Args:
+      zim_id (uuid): Id of the zim to remove
+      lib_xml_file (str): Path to file to read. Can be on removable device
+    '''
+
     command = CONST.kiwix_manage + " " + kiwix_library_xml + " remove " + zim_id
     #print command
     args = shlex.split(command)
@@ -81,7 +108,17 @@ def rem_libr_xml(zim_id, kiwix_library_xml):
             print(outp)
 
 def add_libr_xml(kiwix_library_xml, zim_path, zimname, zimidx):
-    command = CONST.kiwix_manage + " " + kiwix_library_xml + " add " + CONST.zim_path + "/" + zimname
+    '''
+    Add a zim to library.xml
+
+    Args:
+      kiwix_library_xml (str): Name (path) of library.xml file
+      zim_path (str): Path to zim file to add
+      zimname (str): Name of zim file to add
+      zimidx (str): Path to separate idx directory (obsolete)
+
+    '''
+    command = CONST.kiwix_manage + " " + kiwix_library_xml + " add " + zim_path + "/" + zimname
     if zimidx:
         command += " -i " + zim_path + "/" + zimidx
     #print command
@@ -94,6 +131,8 @@ def add_libr_xml(kiwix_library_xml, zim_path, zimname, zimidx):
         pass
 
 def read_lang_codes():
+    '''Populate the global lang_codes dictionary from CONST.lang_codes_path json file'''
+
     global lang_codes
     with open(CONST.lang_codes_path, "r") as f:
         reads = f.read()
@@ -103,6 +142,7 @@ def read_lang_codes():
 # there is a different algorithm in get_zim_list above
 
 def calc_perma_ref(uri):
+    '''Given a path or url return the generic zim name'''
     url_slash = uri.split('/')
     url_end = url_slash[-1] # last element
     file_ref = url_end.split('.zim')[0] # true for both internal and external index
@@ -116,9 +156,11 @@ def calc_perma_ref(uri):
     return perma_ref
 
 def kiwix_lang_to_iso2(zim_lang_code):
+    '''Lookup the iso2 equivalent of a zim language code'''
     return lang_codes[zim_lang_code]['iso2']
 
 def human_readable(num):
+    '''Convert a number to a human readable string'''
     # return 3 significant digits and unit specifier
     # TFM 7/15/2019 change to factor of 1024, not 1000 to match similar calcs elsewhere
     num = float(num)
@@ -135,7 +177,7 @@ def human_readable(num):
 # Environment Functions
 
 def get_iiab_env(name):
-    """ read iiab.env file for a value, return "" if does not exist. return all value for *"""
+    ''' read iiab.env file for a value, return "" if does not exist. return all value for *'''
     iiab_env = {}
     iiab_env_var = ''
     try: