From e80e7c1ac9ae98679b67784e34194c87ad84b685 Mon Sep 17 00:00:00 2001 From: Tim Moody Date: Wed, 4 Dec 2019 09:18:56 -0500 Subject: [PATCH] found a bug and added docstrings --- roles/2-common/templates/iiab_lib.py | 62 +++++++++++++++++++++++----- 1 file changed, 52 insertions(+), 10 deletions(-) diff --git a/roles/2-common/templates/iiab_lib.py b/roles/2-common/templates/iiab_lib.py index 09ab5150c..71b71be2f 100644 --- a/roles/2-common/templates/iiab_lib.py +++ b/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 /library/zims) + ''' + Read zim properties from library.xml + Returns dict of library.xml and map of zim id to zim file name (under /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: