Adding documentation to tools/file_utils.py

tools/file_utils.py

@@ -8,11 +8,23 @@ import logging
 from os.path import join as opj
 
 def create_dir(dir_path):
+    """Returns the directory **dir_path** and create it if path does not exist.
+
+    Args:
+        dir_path (str): Path to the directory that will be created
+    """
     if not os.path.exists(dir_path):
         os.makedirs(dir_path)
     return dir_path
 
-def get_workflow_path(dir_path):
+def get_workflow_path(workflow_path):
+    """Return the directory **workflow_path** and create it if workflow_path
+    does not exist. If **workflow_path** exists a consecutive numerical suffix
+    is added to the end of the **workflow_path** and is returned.
+
+    Args:
+        workflow_path (str): Path to the workflow results
+    """
     if not os.path.exists(dir_path):
         return dir_path
 
@@ -43,6 +55,12 @@ def zip_top(top_file, zip_file):
         zip.write(top_file, arcname=os.path.basename(top_file))
 
 def zip_list(zip_file, file_list):
+    """ Compress all files listed in **file_list** into **zip_file** zip file.
+
+    Args:
+        zip_file: Output compressed zip file.
+        file_list: Input list of files to be compressed.
+    """
     with zipfile.ZipFile(zip_file, 'w') as zip:
         for f in file_list:
             zip.write(f, arcname=os.path.basename(f))
@@ -59,39 +77,61 @@ def unzip_top(zip_file, dest_dir=None, top_file=None):
     return zip_name
 
 
-def get_logs(path, prefix=None, step=None, console=False, level='INFO'):
-    out_log_path = create_name(name='log.out', step=step, prefix=prefix, path=path)
-    err_log_path = create_name(name='log.err', step=step, prefix=prefix, path=path)
+def get_logs(path=None, prefix=None, step=None, console=False, level='INFO'):
+    """ Get the error and and out Python Logger objects.
+
+    Args:
+        path (str): (current working directory) Path to the log file directory.
+        prefix (str): Prefix added to the name of the log file.
+        step (str):  String added between the **prefix** arg and the name of the log file.
+        console (bool): (False) If True, show log in the execution terminal.
+        level (str): ('INFO') Set Logging level. ['CRITICAL','ERROR','WARNING','INFO','DEBUG','NOTSET']
+    """
+    path = path if path else os.getcwd()
+    out_log_path = create_name(path=path, prefix=prefix, step=step, name='log.out')
+    err_log_path = create_name(path=path, prefix=prefix, step=step, name='log.err')
+
+    # Create logging format
     logFormatter = logging.Formatter("%(asctime)s [%(threadName)-12.12s] [%(levelname)-5.5s]  %(message)s")
+
+    # Create logging objects
     out_Logger = logging.getLogger(out_log_path)
-    out_Logger.setLevel(level)
     err_Logger = logging.getLogger(err_log_path)
-    err_Logger.setLevel(level)
 
-    #Creating and formating FileHandler
+
+    #Create FileHandler
     out_fileHandler = logging.FileHandler(out_log_path, mode='a', encoding=None, delay=False)
     err_fileHandler = logging.FileHandler(err_log_path, mode='a', encoding=None, delay=False)
+
+    # Asign format to FileHandler
     out_fileHandler.setFormatter(logFormatter)
     err_fileHandler.setFormatter(logFormatter)
 
-    #Asign FileHandler
+    #Asign FileHandler to logging object
     out_Logger.addHandler(out_fileHandler)
     err_Logger.addHandler(err_fileHandler)
 
-    #Creating and formating consoleHandler
+    # Create consoleHandler
     consoleHandler = logging.StreamHandler()
+    # Asign format to consoleHandler
     consoleHandler.setFormatter(logFormatter)
 
-    # Adding console aditional output
+    # Asign consoleHandler to logging objects as aditional output
     if console:
         out_Logger.addHandler(consoleHandler)
         err_Logger.addHandler(consoleHandler)
 
-    out_Logger.setLevel(10)
-    err_Logger.setLevel(10)
+    # Set logging level level
+    out_Logger.setLevel(level)
+    err_Logger.setLevel(level)
     return out_Logger, err_Logger
 
 def human_readable_time(time_ps):
+    """Transform **time_ps** to a human readable string.
+
+    Args:
+        time_ps (int): Time in pico seconds.
+    """
     time_units = ['femto seconds','pico seconds','nano seconds','micro seconds','mili seconds']
     time = time_ps * 1000
     for tu in time_units:
@@ -101,7 +141,15 @@ def human_readable_time(time_ps):
             time = time/1000
     return str(time_ps)
 
-def create_name(name=None, step=None, prefix=None, path=None):
+def create_name(path=None, prefix=None, step=None, name=None):
+    """ Return file name.
+
+    Args:
+        path (str): Path to the file directory.
+        prefix (str): Prefix added to the name of the file.
+        step (str):  String added between the **prefix** arg and the **name** arg of the file.
+        name (str): Name of the file.
+    """
     name = '' if name is None else name.strip()
     if step:
         if name: