From 1e3a06322ecb967b92c80ef83f0fe2c341f8adb9 Mon Sep 17 00:00:00 2001
From: Aaron LI <aaronly.me@outlook.com>
Date: Mon, 17 Oct 2016 14:41:19 +0800
Subject: utils/logging.py: Small updates to the docstrings and comments

---
 fg21sim/utils/logging.py | 30 ++++++++++++++++--------------
 1 file changed, 16 insertions(+), 14 deletions(-)

(limited to 'fg21sim/utils')

diff --git a/fg21sim/utils/logging.py b/fg21sim/utils/logging.py
index bc827fc..d2bfa1f 100644
--- a/fg21sim/utils/logging.py
+++ b/fg21sim/utils/logging.py
@@ -12,6 +12,7 @@ from logging import FileHandler, StreamHandler
 
 def setup_logging(dict_config=None, level=None, stream=None, logfile=None):
     """Setup the logging.
+
     This will override the logging configurations in the config file
     if specified (e.g., by command line arguments).
 
@@ -20,30 +21,30 @@ def setup_logging(dict_config=None, level=None, stream=None, logfile=None):
     dict_config : dict
         Dict of logging configurations specified in the config file.
         If this parameter specified, the logging will be reconfigured.
-    level : string;
+    level : str;
         Override the existing log level
     stream : string; "stderr", "stdout", or ""
         This controls where the log messages go to.
         If not None, then override the old ``StreamHandler`` settings;
         if ``stream=""``, then disable the ``StreamHandler``.
-    logfile : string
+    logfile : str
         Specify the file where the log messages go to.
         If ``logfile=""``, then disable the ``FileHandler``.
 
     NOTE
     ----
     If the logging already has ``StreamHandler`` or ``FileHandler``
-    configured, then the old handler will be *replaced* (i.e., remove
+    configured, then the old handler will be **replaced** (i.e., remove
     the old one, then add the new one).
     """
-    # default file open mode for logging to file
+    # Default file open mode for logging to file
     filemode = "a"
     root_logger = logging.getLogger()
     #
     if dict_config:
-        # XXX:
-        # "basicConfig()" does NOT accept paramter "filemode" if the
-        # corresponding parameter "filename" NOT specified.
+        # XXX/NOTE:
+        # ``basicConfig()`` does NOT accept parameter ``filemode`` if the
+        # corresponding parameter ``filename`` NOT specified.
         filemode = dict_config.pop("filemode", filemode)
         # Clear existing handlers, otherwise further "basicConfig" calls
         # will be ignored
@@ -55,15 +56,16 @@ def setup_logging(dict_config=None, level=None, stream=None, logfile=None):
         # the handlers to the "root" logger.
         logging.basicConfig(**dict_config)
     #
-    # Configured logging has at least one handler with configured formatter.
-    # Keep the existing formatter to keep the configured format styles.
-    formatter = root_logger.handlers[0].formatter
     if level is not None:
         level_int = getattr(logging, level.upper(), None)
         if not isinstance(level_int, int):
             raise ValueError("invalid log level: %s" % level)
         root_logger.setLevel(level_int)
     #
+    # Configured logging has at least one handler with configured formatter.
+    # Store the existing formatter to preserve the configured format styles.
+    formatter = root_logger.handlers[0].formatter
+    #
     if stream is None:
         pass
     elif stream in ["", "stderr", "stdout"]:
@@ -73,10 +75,10 @@ def setup_logging(dict_config=None, level=None, stream=None, logfile=None):
                 handler.close()
                 root_logger.removeHandler(handler)
         if stream == "":
-            # disable ``StreamHandler``
+            # ``StreamHandler`` already disabled
             pass
         else:
-            # add new ``StreamHandler``
+            # Add new ``StreamHandler``
             handler = StreamHandler(getattr(sys, stream))
             handler.setFormatter(formatter)
             root_logger.addHandler(handler)
@@ -91,10 +93,10 @@ def setup_logging(dict_config=None, level=None, stream=None, logfile=None):
                 handler.close()
                 root_logger.removeHandler(handler)
         if logfile == "":
-            # disable ``FileHandler``
+            # ``FileHandler`` already disabled
             pass
         else:
-            # add new ``FileHandler``
+            # Add new ``FileHandler``
             handler = FileHandler(logfile, mode=filemode)
             handler.setFormatter(formatter)
             root_logger.addHandler(handler)
-- 
cgit v1.2.2