Merge pull request #203 from trz42/code_polishing_8

[v0.1] code polishing: tools/__init__.py

tools/__init__.py

@@ -12,29 +12,39 @@
 #
 # license: GPLv2
 #
+
+# Standard library imports
 import os
 import subprocess
 
+# Third party imports (anything installed into the local Python environment)
 from pyghee.utils import log
 
 
+# TODO do we really need two functions (run_cmd and run_subprocess) for
+# running a command?
 def run_cmd(cmd, log_msg='', working_dir=None, log_file=None, raise_on_error=True):
-    """Runs a command in the shell, raising an error if one occurs.
+    """
+    Runs a command in the shell and raises an error if one occurs.
 
     Args:
         cmd (string): command to run
-        log_msg (string): purpose of the command
-        working_dir (string): location of arch_job_dir
+        log_msg (string): message describing the purpose of the command
+        working_dir (string): location of the job's working directory
         log_file (string): path to log file
-        raise_on_error (bool): raise an exception in case of error
+        raise_on_error (bool): if True raise an exception in case of error
 
     Returns:
         tuple of 3 elements containing
         - stdout (string): stdout of the process
         - stderr (string): stderr of the process
         - exit_code (string): exit code of the process
-    """
 
+    Raises:
+        RuntimeError: raises a RuntimeError if exit code was not zero and
+            raise_on_error is True
+    """
+    # TODO use common method for logging function name in log messages
     stdout, stderr, exit_code = run_subprocess(cmd, log_msg, working_dir, log_file)
 
     if exit_code != 0:
@@ -57,12 +67,13 @@ def run_cmd(cmd, log_msg='', working_dir=None, log_file=None, raise_on_error=Tru
 
 
 def run_subprocess(cmd, log_msg, working_dir, log_file):
-    """Runs a command in the shell. No error is raised if the command fails, the exit code is returned in all scenarios.
+    """
+    Runs a command in the shell. No error is raised if the command fails.
 
     Args:
         cmd (string): command to run
         log_msg (string): purpose of the command
-        working_dir (string): location of arch_job_dir
+        working_dir (string): location of the job's working directory
         log_file (string): path to log file
 
     Returns:
@@ -71,7 +82,7 @@ def run_subprocess(cmd, log_msg, working_dir, log_file):
         - stderr (string): stderr of the process
         - exit_code (string): exit code of the process
     """
-
+    # TODO use common method for logging function name in log messages
     if working_dir is None:
         working_dir = os.getcwd()