From 20d80ccc03a1850c47f74526f5445be6375220c3 Mon Sep 17 00:00:00 2001
From: "Jason M. Gates" <jmgate@sandia.gov>
Date: Thu, 5 Aug 2021 16:21:16 -0600
Subject: [PATCH] Reformat ShellLogger.py

* Mostly type hinting and docstrings.
* The occasional reorganization of a function.
---
 .idea/ShellLogger.iml          |   4 +-
 .idea/misc.xml                 |   3 +
 src/shelllogger/ShellLogger.py | 853 ++++++++++++++++++++-------------
 3 files changed, 531 insertions(+), 329 deletions(-)

diff --git a/.idea/ShellLogger.iml b/.idea/ShellLogger.iml
index 7abdf59..8ca6856 100644
--- a/.idea/ShellLogger.iml
+++ b/.idea/ShellLogger.iml
@@ -8,8 +8,8 @@
     <orderEntry type="sourceFolder" forTests="false" />
   </component>
   <component name="PyDocumentationSettings">
-    <option name="format" value="PLAIN" />
-    <option name="myDocStringFormat" value="Plain" />
+    <option name="format" value="GOOGLE" />
+    <option name="myDocStringFormat" value="Google" />
   </component>
   <component name="TestRunnerService">
     <option name="PROJECT_TEST_RUNNER" value="py.test" />
diff --git a/.idea/misc.xml b/.idea/misc.xml
index c3334de..6c66106 100644
--- a/.idea/misc.xml
+++ b/.idea/misc.xml
@@ -1,4 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
   <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.8 (base)" project-jdk-type="Python SDK" />
+  <component name="PythonCompatibilityInspectionAdvertiser">
+    <option name="version" value="3" />
+  </component>
 </project>
\ No newline at end of file
diff --git a/src/shelllogger/ShellLogger.py b/src/shelllogger/ShellLogger.py
index 091d3e6..202ba00 100644
--- a/src/shelllogger/ShellLogger.py
+++ b/src/shelllogger/ShellLogger.py
@@ -1,20 +1,24 @@
 #!/usr/bin/env python3
 
-from .classes import Shell, Trace, StatsCollector, trace_collector, stats_collectors
-from .util import nested_SimpleNamespace_to_dict, opening_html_text, closing_html_text, append_html, html_message_card, message_card, command_card, child_logger_card, parent_logger_card_html
+from __future__ import annotations
+from .classes import (Shell, Trace, StatsCollector, trace_collector,
+                      stats_collectors)
+from .util import (nested_SimpleNamespace_to_dict, opening_html_text,
+                   closing_html_text, append_html, html_message_card,
+                   message_card, command_card, child_logger_card,
+                   parent_logger_card_html)
 from collections.abc import Iterable, Mapping
-import datetime
-import distutils.dir_util as dir_util
+from datetime import datetime, timedelta
+from typing import List, Optional, Union
+from distutils import dir_util
 import json
 import os
 from pathlib import Path
 try:
     import psutil
-except:
+except ModuleNotFoundError:
     psutil = None
 import random
-import re
-import select
 import shutil
 import string
 import tempfile
@@ -24,93 +28,98 @@
 
 class ShellLoggerEncoder(json.JSONEncoder):
     """
-    This is a helper class to make the :class:`ShellLogger` class JSON serializable.
-    This particular class is used in the process of saving :class:`ShellLogger`
-    objects to JSON.
+    This is a helper class to make the :class:`ShellLogger` class JSON
+    serializable.  This particular class is used in the process of
+    saving :class:`ShellLogger` objects to JSON.
 
     Usage::
 
         import json
         with open('path_to_json_file', 'w') as jf:
             json.dump(data, jf, cls=ShellLoggerEncoder)
-
     """
-    def default(self, obj):
+
+    def default(self, obj: object) -> object:
+        """
+        Serialize an object; that is, encode it in a string format.
+
+        Args:
+            obj:  Any Python object.
+
+        Returns:
+            The JSON serialization of the given object.
+        """
         if isinstance(obj, ShellLogger):
-            logger = {
-                **{'__type__': 'ShellLogger'},
-                **{k:self.default(v) for k, v in obj.__dict__.items()}
-            }
-            return logger
+            return {**{'__type__': 'ShellLogger'},
+                    **{k: self.default(v) for k, v in obj.__dict__.items()}}
         elif isinstance(obj, (int, float, str, bytes)):
             return obj
         elif isinstance(obj, Mapping):
-            return {k:self.default(v) for k,v in obj.items()}
+            return {k: self.default(v) for k, v in obj.items()}
         elif isinstance(obj, tuple):
-            tup = {
-                '__type__': 'tuple',
-                'items': obj
-            }
-            return tup
+            return {'__type__': 'tuple',
+                    'items': obj}
         elif isinstance(obj, Iterable):
-            return [ self.default(x) for x in obj ]
-        elif isinstance(obj, datetime.datetime):
-            time = {
-                '__type__': 'datetime',
-                'value': obj.strftime('%Y-%m-%d_%H:%M:%S:%f'),
-                'format': '%Y-%m-%d_%H:%M:%S:%f'
-            }
-            return time
+            return [self.default(x) for x in obj]
+        elif isinstance(obj, datetime):
+            return {'__type__': 'datetime',
+                    'value': obj.strftime('%Y-%m-%d_%H:%M:%S:%f'),
+                    'format': '%Y-%m-%d_%H:%M:%S:%f'}
         elif isinstance(obj, Path):
-            path = {
-                '__type__': 'Path',
-                'value': str(obj)
-            }
-            return path
+            return {'__type__': 'Path',
+                    'value': str(obj)}
         elif obj is None:
             return None
         elif isinstance(obj, Shell):
-            shell = {
-                '__type__': 'Shell',
-                'pwd': obj.pwd()
-            }
-            return shell
+            return {'__type__': 'Shell',
+                    'pwd': obj.pwd()}
         else:
-            # Call JSONEncoder's implementation
             return json.JSONEncoder.default(self, obj)
 
 
 class ShellLoggerDecoder(json.JSONDecoder):
     """
-    This is a helper class to make the :class:`ShellLogger` class JSON serializable.
-    This particular class is used in the process of retrieving :class:`ShellLogger`
-    objects from JSON.
+    This is a helper class to make the :class:`ShellLogger` class JSON
+    serializable.  This particular class is used in the process of
+    retrieving :class:`ShellLogger` objects from JSON.
 
     Usage::
 
         import json
         with open('path_to_json_file', 'r') as jf:
             logger = json.load(jf, cls=ShellLoggerDecoder)
-
     """
+
     def __init__(self):
+        """
+        Initialize the decoder.
+        """
         json.JSONDecoder.__init__(self, object_hook=self.dict_to_object)
 
-    def dict_to_object(self, obj):
+    @staticmethod
+    def dict_to_object(obj: dict) -> object:
         """
-        This converts data dictionaries given by the JSONDecoder into objects
-        of type :class:`ShellLogger`, :class:`datetime.datetime`, etc.
+        This converts data dictionaries given by the JSONDecoder into
+        objects of type :class:`ShellLogger`,
+        :class:`datetime`, etc.
+
+        Args:
+            obj:  The JSON-serialized representation of an object.
+
+        Returns:
+            The object represented by the JSON serialization.
         """
         if '__type__' not in obj:
             return obj
         elif obj['__type__'] == 'ShellLogger':
             logger = ShellLogger(obj['name'], obj['log_dir'],
-                                 obj['strm_dir'], obj['html_file'], obj['indent'],
-                                 obj['log_book'], obj['init_time'],
-                                 obj['done_time'], obj['duration'])
+                                 obj['stream_dir'], obj['html_file'],
+                                 obj['indent'], obj['log_book'],
+                                 obj['init_time'], obj['done_time'],
+                                 obj['duration'])
             return logger
         elif obj['__type__'] == 'datetime':
-            return datetime.datetime.strptime(obj['value'], obj['format'])
+            return datetime.strptime(obj['value'], obj['format'])
         elif obj['__type__'] == 'Path':
             return Path(obj['value'])
         elif obj['__type__'] == 'tuple':
@@ -121,11 +130,12 @@ def dict_to_object(self, obj):
 
 class ShellLogger:
     """
-    This class will keep track of commands run in the shell, their durations,
-    descriptions, ``stdout``, ``stderr``, and ``return_code``.  When the
-    :func:`finalize` method is called, the :class:`ShellLogger` object will
-    aggregate all the data from its commands and child :class:`ShellLogger` objects
-    (see example below) into both JSON and HTML files.
+    This class will keep track of commands run in the shell, their
+    durations, descriptions, ``stdout``, ``stderr``, and
+    ``return_code``.  When the :func:`finalize` method is called, the
+    :class:`ShellLogger` object will aggregate all the data from its
+    commands and child :class:`ShellLogger` objects (see example below)
+    into both JSON and HTML files.
 
     Example::
 
@@ -141,215 +151,260 @@ class ShellLogger:
         etc...
 
     Note:
-        Because some ``stdout``/``stderr`` streams can be quite long, they will
-        be written to files in a temporary directory
-        (``log_dir/tmp/YYYY-MM-DD_hh:mm:ss/``).  Once the :func:`finalize`
-        method is called, they will be aggregated in an HTML file
-        (``log_dir/html_file``).  The JSON file (``log_dir/json_file``) will
-        contain references to the ``stdout``/``stderr`` files so that an HTML
-        file can be recreated again later if needed.
+        Because some ``stdout``/``stderr`` streams can be quite long,
+        they will be written to files in a temporary directory
+        (``log_dir/tmp/YYYY-MM-DD_hh:mm:ss/``).  Once the
+        :func:`finalize` method is called, they will be aggregated in an
+        HTML file (``log_dir/html_file``).  The JSON file
+        (``log_dir/json_file``) will contain references to the
+        ``stdout``/``stderr`` files so that an HTML file can be
+        recreated again later if needed.
 
     Attributes:
-        done_time (datetime):  The time this :class:`ShellLogger` object is done
-            with its commands/messages.
-        duration (str):  String formatted duration of this :class:`ShellLogger`,
-            updated when the :func:`finalize` method is called.
-        init_time (datetime):  The time this :class:`ShellLogger` object was
-            created.
-        log (list):  A list containing log entries and child.
-            :class:`ShellLogger` objects in the order they were created.
-        log_dir (Path):  Path to where the logs are stored for the parent
-            :class:`ShellLogger` and all its children.
         name (str):  The name of the :class:`ShellLogger` object.
-        strm_dir (Path):  Path to directory where ``stdout``/``stderr`` stream
-            logs are stored.
+        log_dir (Path):  Path to where the logs are stored for the
+            parent :class:`ShellLogger` and all its children.
+        stream_dir (Path):  Path to directory where
+            ``stdout``/``stderr`` stream logs are stored.
         html_file (Path):  Path to main HTML file for the parent and
             children :class:`ShellLogger` objects.
-        indent (int):  The indentation level of this :class:`ShellLogger` object.
-            The parent has a level 0. Each successive child's indent is
-            increased by 1.
+        indent (int):  The indentation level of this
+            :class:`ShellLogger` object.  The parent has a level 0.
+            Each successive child's indent is increased by 1.
+        log_book (list):  A list containing log entries and child
+            :class:`ShellLogger` objects in the order they were created.
+        init_time (datetime):  The time this :class:`ShellLogger` object
+            was created.
+        done_time (datetime):  The time this :class:`ShellLogger` object
+            is done with its commands/messages.
+        duration (str):  String formatted duration of this
+            :class:`ShellLogger`, updated when the :func:`finalize`
+            method is called.
+        shell (Shell):  The :class:`Shell` in which all commands will be
+            run when logging.
     """
 
-    def append(path):
-        path = Path(path)
+    @staticmethod
+    def append(path: Path) -> ShellLogger:
+        """
+        Create a :class:`ShellLogger` to append to the HTML log file
+        generated by a prior :class:`ShellLogger`.
+
+        Args:
+            path:  The location of the prior :class:`ShellLogger` 's
+                output, either the log directory, or the HTML log file
+                itself.
+
+        Returns:
+            A new :class:`ShellLogger` populated with the data from the
+            prior one.
+        """
+
+        # Ensure the given `path` is valid.
         if path.is_dir():
             try:
                 path = next(path.glob("*.html"))
-            except:
-                raise RuntimeError(f"{path} does not have an html file")
+            except StopIteration:
+                raise RuntimeError(f"{path} does not have an html file.")
         if path.is_symlink():
             path = path.resolve(strict=True)
-        if path.is_file() and path.name[-5:] ==".html":
+        if path.is_file() and path.name[-5:] == ".html":
             path = path.parent / (path.name[:-5] + ".json")
+
+        # Deserialize the corresponding JSON object into a ShellLogger.
         with open(path, "r") as jf:
             loaded_logger = json.load(jf, cls=ShellLoggerDecoder)
         return loaded_logger
 
-    def __init__(self, name, log_dir=Path.cwd(), strm_dir=None, html_file=None,
-                 indent=0, log=None, init_time=None, done_time=None,
-                 duration=None):
+    def __init__(
+            self,
+            name: str,
+            log_dir: Path = Path.cwd(),
+            stream_dir: Optional[Path] = None,
+            html_file: Optional[Path] = None,
+            indent: int = 0,
+            log: Optional[List[object]] = None,
+            init_time: Optional[datetime] = None,
+            done_time: Optional[datetime] = None,
+            duration: Optional[str] = None
+    ) -> None:
         """
+        Initialize a :class:`ShellLogger` object.
+
         Parameters:
-            name (str):  Name to give to this ShellLogger object.
-            log_dir (Path):  Path to directory where log files will be stored.
-            strm_dir (Path):  Path to directory where ``stdout``/``stderr``
-                stream logs are stored.  This is helpful for parent ShellLogger
-                objects to give to child ShellLogger objects in order to keep things
-                in the same directory.
-            html_file (Path):  Path to main HTML file for the parent and
-                children ShellLogger objects. If ``None`` (default), this is the
-                parent ShellLogger object, and it will need to create the file.
-            indent (int):  The indentation level of this ShellLogger object. The
-                parent has a level 0. Each successive child's indent is
-                increased by 1.
-            log (list):  Optionally provide an existing log list to the
-                :class:`ShellLogger` object.  This is mainly used when importing
-                :class:`ShellLogger` objects from a JSON file, and can generally be
-                left at the default value - an empty list.
-            init_time (datetime):  Optionally provide an init_time to the
-                :class:`ShellLogger` object.  This is mainly used when importing
-                :class:`ShellLogger` objects from a JSON file, and can generally be
-                left at the default value - the current time.
-            done_time (datetime):  Optionally provide a done_time to the
-                :class:`ShellLogger` object.  This is mainly used when importing
-                :class:`ShellLogger` objects from a JSON file, and can generally be
-                left at the default value - the current time.
-        """
-
-        # Misc
-        # ----
+            name:  The name to give to this :class:`ShellLogger` object.
+            log_dir:  Where to store the log files.
+            stream_dir:  Where the ``stdout``/``stderr`` stream logs are
+                stored.  This is helpful for parent :class:`ShellLogger`
+                objects to give to child :class:`ShellLogger` objects in
+                order to keep things in the same directory.
+            html_file:  The path to the main HTML file for the parent
+                and children :class:`ShellLogger` objects.  If omitted,
+                this is the parent :class:`ShellLogger` object, and it
+                will need to create the file.
+            indent:  The indentation level of this :class:`ShellLogger`
+                object.  The parent has a level 0.  Each successive
+                child's indent is increased by 1.
+            log:  Optionally provide an existing log list to the
+                :class:`ShellLogger` object.
+            init_time:  Optionally specify when this
+                :class:`ShellLogger` was initialized.
+            done_time:  Optionally specify when this
+                :class:`ShellLogger` was finalized.
+            duration:  A string representation of the total duration of
+                the :class:`ShellLogger`.
+
+        Note:
+            The ``log``, ``init_time``, ``done_time``, and ``duration``
+            parameters are mainly used when importing
+            :class:`ShellLogger` objects from a JSON file, and can
+            generally be omitted.
+        """
         self.name = name
-        self.log_book = log if log is not None else []
-        self.init_time = datetime.datetime.now() if not init_time else init_time
-        self.done_time = datetime.datetime.now() if not done_time else done_time
+        self.log_book: List[Union[dict, ShellLogger]] = (
+            log if log is not None else []
+        )
+        self.init_time = datetime.now() if init_time is None else init_time
+        self.done_time = datetime.now() if done_time is None else done_time
         self.duration = duration
         self.indent = indent
-        self.is_parent = True if self.indent == 0 else False
         self.shell = Shell(Path.cwd())
 
-        # log_dir
-        # -------
+        # Create the log directory, if needed.
         self.log_dir = log_dir.resolve()
-        if not log_dir.exists():
-            log_dir.mkdir(parents=True, exist_ok=True)
-
-        # strm_dir
-        # -------
-        # If there isn't a strm_dir given by the parent ShellLogger, this is the
-        # parent. Create the strm_dir.
-        if strm_dir is None:
-            now = self.init_time.strftime("%Y-%m-%d_%H.%M.%S.%f_")
-            self.strm_dir = Path(tempfile.mkdtemp(dir=self.log_dir,
-                                                  prefix=now))
+        if not self.log_dir.exists():
+            self.log_dir.mkdir(parents=True, exist_ok=True)
+
+        # If there isn't a `stream_dir` given by the parent ShellLogger, this
+        # is the parent; create the `stream_dir`.
+        if stream_dir is None:
+            self.stream_dir = Path(tempfile.mkdtemp(
+                dir=self.log_dir,
+                prefix=self.init_time.strftime("%Y-%m-%d_%H.%M.%S.%f_")
+            )).resolve()
         else:
-            self.strm_dir = strm_dir.resolve()
+            self.stream_dir = stream_dir.resolve()
 
-        # html_file
-        # ---------
-        if html_file is not None:
-            self.html_file = html_file.resolve()
+        # Create (or append to) the HTML log file.
+        if html_file is None:
+            self.html_file = self.stream_dir / (self.name.replace(' ', '_')
+                                                + '.html')
         else:
-            self.html_file = self.strm_dir / (name.replace(' ', '_') + '.html')
-
-        if self.is_parent:
+            self.html_file = html_file.resolve()
+        if self.is_parent():
             if self.html_file.exists():
                 with open(self.html_file, 'a') as f:
-                    f.write(f"<!-- {self.init_time:} Append to log started -->")
+                    f.write(f"<!-- {self.init_time:} Append to log started "
+                            "-->")
             else:
                 self.html_file.touch()
 
+    def is_parent(self) -> bool:
+        """
+        Determine whether or not this is the parent :class:`ShellLogger`
+        object, as indicated by the object's :attr:`indent` attribute.
 
+        Returns:
+            ``True`` if this is the parent; ``False`` otherwise.
+        """
+        return self.indent == 0
 
-    def update_done_time(self):
+    def update_done_time(self) -> None:
         """
-        Allows the ``done_time`` to be updated before
+        Allows the :attr:`done_time` to be updated before
         :func:`finalize` is called.  This is especially useful for child
-        :class:`ShellLogger` objects who might finish their commands before the
-        parent finalizes everything.
+        :class:`ShellLogger` objects who might finish their commands
+        before the parent finalizes everything.
         """
-        self.done_time = datetime.datetime.now()
+        self.done_time = datetime.now()
 
-    def __update_duration(self):
+    def __update_duration(self) -> None:
         """
-        Updates the `duration` attribute with the time from the beginning of
-        the :class:`ShellLogger` object's creation until now.
+        Updates the :attr:`duration` attribute with the time from the
+        beginning of the :class:`ShellLogger` object's creation until
+        now.
         """
         self.update_done_time()
-        dur = self.done_time - self.init_time
-        self.duration = self.strfdelta(dur, "{hrs}h {min}m {sec}s")
+        self.duration = self.strfdelta(self.done_time - self.init_time,
+                                       "{hrs}h {min}m {sec}s")
 
-    def check_duration(self):
+    def check_duration(self) -> str:
         """
-        Returns the current duration from the beginning of the :class:`ShellLogger`
-        object's creation until now.
+        Get the current duration from the beginning of the
+        :class:`ShellLogger` object's creation until now.
 
         Returns:
-            str:  Duration from this object's creation until now as a string.
+            A string representation of the total duration.
         """
-        now = datetime.datetime.now()
-        dur = now - self.init_time
-        return self.strfdelta(dur, "{hrs}h {min}m {sec}s")
+        return self.strfdelta(datetime.now() - self.init_time,
+                              "{hrs}h {min}m {sec}s")
 
-    def change_log_dir(self, new_log_dir):
+    def change_log_dir(self, new_log_dir: Path) -> None:
         """
-        Change the :attr:`log_dir` of this :class:`ShellLogger` object and all
-        children recursively.
-
-        Warning:
-            Only run this method on the top-level parent :class:`ShellLogger`
-            object!  Otherwise, parents and children in a tree will have
-            different :attr:`log_dir` 's and things will break.
+        Change the :attr:`log_dir` of this :class:`ShellLogger` object
+        and all children recursively.
 
         Parameters:
             new_log_dir (Path):  Path to the new :attr:`log_dir`.
+
+        Raises:
+            RuntimeError:  If this is called on a child
+                :class:`ShellLogger`.
         """
+        if not self.is_parent():
+            raise RuntimeError("You should not change the log directory of a "
+                               "child `ShellLogger`; only that of the parent.")
 
-        # This only gets executed once by the top-level parent ShellLogger object.
+        # This only gets executed once by the top-level parent
+        # `ShellLogger` object.
         if self.log_dir.exists():
-            dir_util.copy_tree(self.log_dir, new_log_dir)
+            dir_util.copy_tree(str(self.log_dir), str(new_log_dir))
             shutil.rmtree(self.log_dir)
 
-        # Change the strm_dir, html_file, and log_dir for every child ShellLogger
-        # recursively.
-        self.strm_dir = new_log_dir / self.strm_dir.relative_to(self.log_dir)
+        # Change the `stream_dir`, `html_file`, and `log_dir` for every
+        # child `ShellLogger` recursively.
+        self.stream_dir = (new_log_dir
+                           / self.stream_dir.relative_to(self.log_dir))
         self.html_file = new_log_dir / self.html_file.relative_to(self.log_dir)
         self.log_dir = new_log_dir.resolve()
         for log in self.log_book:
             if isinstance(log, ShellLogger):
                 log.change_log_dir(self.log_dir)
 
-    def add_child(self, child_name):
+    def add_child(self, child_name: str) -> ShellLogger:
         """
-        Creates and returns a 'child' :class:`ShellLogger` object. This will be one
-        step indented in the tree of the output log (see example in class
-        docstring). The total time for this child will be recorded when the
-        :func:`finalize` method is called in the child object.
+        Creates and returns a 'child' :class:`ShellLogger` object.  This
+        will be one step indented in the tree of the output log (see
+        the example in the class docstring).  The total time for this
+        child will be recorded when the :func:`finalize` method is
+        called in the child object.
 
         Parameters:
-            child_name (str):  Name of the child :class:`ShellLogger` object.
+            child_name:  The name of the child :class:`ShellLogger`
+                object.
 
         Returns:
-            ShellLogger:  Child :class:`ShellLogger` object.
+            ShellLogger:  A child :class:`ShellLogger` object.
         """
 
         # Create the child object and add it to the list of children.
-        child = ShellLogger(child_name, self.log_dir, self.strm_dir, self.html_file,
-                            self.indent + 1)
+        child = ShellLogger(child_name, self.log_dir, self.stream_dir,
+                            self.html_file, self.indent + 1)
         self.log_book.append(child)
-
         return child
 
-    def strfdelta(self, tdelta, fmt):
+    @staticmethod
+    def strfdelta(tdelta: timedelta, fmt: str) -> str:
         """
-        Format a time delta object.
+        Format a time delta object.  Use this like you would
+        :func:`datetime.strftime`.
 
         Parameters:
-            tdelta (datetime.datetime.timedelta): Time delta object.
-            fmt (str): Delta format string. Use like
-                       :func:`datetime.datetime.strftime`.
+            tdelta:  The time delta object.
+            fmt (str):  The delta format string.
 
         Returns:
-            str: String with the formatted time delta.
+            A string representation of the time delta.
         """
 
         # Dictionary to hold time delta info.
@@ -365,90 +420,81 @@ def strfdelta(self, tdelta, fmt):
         # String template to help with recognizing the format.
         return fmt.format(**d)
 
-    def print(self, msg, end='\n'):
+    def print(self, msg: str, end: str = '\n') -> None:
         """
         Print a message and save it to the log.
 
         Parameters:
-            msg (str):  Message to print and save to the log.
+            msg:  The message to print and save to the log.
+            end:  The string appended after the message:
         """
-
         print(msg, end=end)
         log = {
             'msg': msg,
-            'timestamp': str(datetime.datetime.now()),
+            'timestamp': str(datetime.now()),
             'cmd': None
         }
         self.log_book.append(log)
 
-    def html_print(self, msg, msg_title="HTML Message"):
+    def html_print(self, msg: str, msg_title: str = "HTML Message") -> None:
         """
-        Save a message to the log but don't print it in the console.
+        Save a message to the log but, don't print it in the console.
 
         Parameters:
-            msg (str):        Message to save to the log.
-            msg_title (str):  Title of the message to save to the log.
+            msg:  Message to save to the log.
+            msg_title:  Title of the message to save to the log.
         """
-
         log = {
             'msg': msg,
             'msg_title': msg_title,
-            'timestamp': str(datetime.datetime.now()),
+            'timestamp': str(datetime.now()),
             'cmd': None
         }
         self.log_book.append(log)
 
-
-    def to_html(self):
-        """
-        This method iterates through each entry in this :class:`ShellLogger`
-        object's log list and appends corresponding HTML text to the main HTML
-        file. For each entry, the ``stdout``/``stderr`` are copied from their
-        respective files in the ``strm_dir``.
+    def to_html(self) -> List[object]:
         """
+        This method iterates through each entry in this
+        :class:`ShellLogger` object's log list and builds up a list of
+        corresponding HTML snippets.  For each entry, the
+        ``stdout``/``stderr`` are copied from their respective files in
+        the :attr:`stream_dir`.
 
+        Returns:
+            Todo:  Figure this out.
+        """
         html = []
-
         for log in self.log_book:
-            # Child ShellLogger
-            # ------------
+
+            # If this is a child ShellLogger...
             if isinstance(log, ShellLogger):
-                # Update the duration of this ShellLogger's commands
+
+                # Update the duration of this ShellLogger's commands.
                 if log.duration is None:
                     log.__update_duration()
                 html.append(child_logger_card(log))
 
-                # Skip the regular log entry stuff
-                continue
-
-            # Message Log Entry
-            # -----------------
-            if log["cmd"] is None:
+            # Otherwise, if this is a message being logged...
+            elif log["cmd"] is None:
                 if log.get("msg_title") is None:
                     html.append(message_card(log))
                 else:
                     html.append(html_message_card(log))
-                # Skip the regular log entry stuff
-                continue
-
-            # Command Log Entry
-            # -----------------
-            # Write the top part of the HTML entry
-            html.append(command_card(log, self.strm_dir))
 
-        if self.is_parent:
+            # Otherwise, if this is a command being logged...
+            else:
+                html.append(command_card(log, self.stream_dir))
+        if self.is_parent():
             return parent_logger_card_html(self.name, html)
         else:
             return html
 
-    def finalize(self):
+    def finalize(self) -> None:
         """
-        This method iterates through each entry in this :class:`ShellLogger`
-        object's log list and appends corresponding HTML text to the main HTML
-        file. For each entry, the ``stdout``/``stderr`` are copied from their
-        respective files in the ``strm_dir``.
+        Finalize the :class:`ShellLogger` object by writing the HTML log
+        file.
         """
-        if self.is_parent:
+        if self.is_parent():
             html_text = opening_html_text() + "\n"
             with open(self.html_file, 'w') as f:
                 f.write(html_text)
@@ -456,101 +502,118 @@ def finalize(self):
         for element in self.to_html():
             append_html(element, output=self.html_file)
 
-        # Final steps (Only for the parent)
-        # ---------------------------------
-        if self.is_parent:
+        if self.is_parent():
             with open(self.html_file, 'a') as html:
                 html.write(closing_html_text())
                 html.write('\n')
-            # Create a symlink in log_dir to the HTML file in strm_dir.
+
+            # Create a symlink in `log_dir` to the HTML file in
+            # `stream_dir`.
             curr_html_file = self.html_file.name
             new_location = self.log_dir / curr_html_file
             temp_link_name = Path(tempfile.mktemp(dir=self.log_dir))
             temp_link_name.symlink_to(self.html_file)
             temp_link_name.replace(new_location)
 
-            # Save everything to a JSON file in the timestamped strm_dir
-            json_file = self.name.replace(' ', '_') + '.json'
-            json_file = self.strm_dir / json_file
-
+            # Save everything to a JSON file in the timestamped
+            # `stream_dir`.
+            json_file = self.stream_dir / (self.name.replace(' ', '_')
+                                           + '.json')
             with open(json_file, 'w') as jf:
-                json.dump(self, jf, cls=ShellLoggerEncoder, sort_keys=True, indent=4)
-
-    def log(self, msg, cmd, cwd=None, live_stdout=False,
-            live_stderr=False, return_info=False, verbose=False,
-            stdin_redirect=True, **kwargs):
+                json.dump(self, jf, cls=ShellLoggerEncoder, sort_keys=True,
+                          indent=4)
+
+    def log(
+            self,
+            msg: str,
+            cmd: Union[str, List[str]],
+            cwd: Optional[Path] = None,
+            live_stdout: bool = False,
+            live_stderr: bool = False,
+            return_info: bool = False,
+            verbose: bool = False,
+            stdin_redirect: bool = True,
+            **kwargs
+    ) -> dict:
         """
-        Add something to the log. To conserve memory, ``stdout`` and ``stderr``
-        will be written to the files as it is being generated.
+        Add something to the log.  To conserve memory, ``stdout`` and
+        ``stderr`` will be written to the files as they are being
+        generated.
 
         Parameters:
-            msg (str):  Message to be recorded with the command. This could be
-                documentation of what your command is doing and its purpose.
-            cmd (str, list):  Shell command to be executed.
-            cwd (Path):  Path to the working directory of the command to be
-                executed.
-            live_stdout (bool):  Print ``stdout`` as it is being produced as
+            msg:  A message to be recorded with the command. This could
+                be documentation of what your command is doing and why.
+            cmd:  The shell command to be executed.
+            cwd:  Where to execute the command.
+            live_stdout:  Print ``stdout`` as it is being produced, as
                 well as saving it to the file.
-            live_stderr (bool):  Print ``stderr`` as it is being produced as
+            live_stderr:  Print ``stderr`` as it is being produced, as
                 well as saving it to the file.
-            return_info (bool):  If set to ``True``, ``stdout``, ``stderr``,
+            return_info:  If set to ``True``, ``stdout``, ``stderr``,
                 and ``return_code`` will be stored and returned in a
-                dictionary.  Consider leaving this set to ``False`` if you
-                anticipate your command producing large ``stdout``/``stderr``
-                streams that could cause memory issues.
-            verbose (bool):  Print the command before it is executed.
-            stdin_redirect (bool):  Whether or not to redirect ``stdin`` to
-                ``/dev/null``.  We do this by default to handle issues that
-                arise when the ``cmd`` involves mpi; however, in some cases
-                (e.g., involving ``bsub``) the redirect causes problems, and we
-                need the flexibility to revert back to standard behavior.
+                dictionary.  Consider leaving this set to ``False`` if
+                you anticipate your command producing large
+                ``stdout``/``stderr`` streams that could cause memory
+                issues.
+            verbose:  Print the command before it is executed.
+            stdin_redirect:  Whether or not to redirect ``stdin`` to
+                ``/dev/null``.  We do this by default to handle issues
+                that arise when the ``cmd`` involves MPI; however, in
+                some cases (e.g., involving ``bsub``) the redirect
+                causes problems, and we need the flexibility to revert
+                back to standard behavior.
+            **kwargs:  Any other keyword arguments to pass on to
+                :func:`run`.
 
         Returns:
-            dict:  A dictionary containing `stdout`, `stderr`, `trace`, and
-            `return_code` keys.  If `return_info` is set to ``False``,
-            the `stdout` and `stderr` values will be ``None``. If `return_info`
-            is set to ``True`` and `trace` is specified in kwargs, `trace` in
-            the dictionary will contain the output of the specified trace;
+            A dictionary containing ``stdout``, ``stderr``, ``trace``,
+            and ``return_code`` keys.  If ``return_info`` is set to
+            ``False``, the ``stdout`` and ``stderr`` values will be
+            ``None``.  If ``return_info`` is set to ``True`` and
+            ``trace`` is specified in ``kwargs``, ``trace`` in the
+            dictionary will contain the output of the specified trace;
             otherwise, it will be ``None``.
-        """
-
-        start_time = datetime.datetime.now()
-
-        # Create a unique command ID that will be used to find the location
-        # of the stdout/stderr files in the temporary directory during
-        # finalization.
-        cmd_id = 'cmd_' + ''.join(random.choice(string.ascii_lowercase)
-                                  for i in range(9))
 
+        Todo:
+            Deprecate the ability to pass in a ``List[str]`` for the
+            ``cmd``.  We automatically convert the list to a string
+            anyway, and there's no need to maintain a similar interface
+            to ``subprocess.Popen()``.
+        """
+        start_time = datetime.now()
         if isinstance(cmd, list):
-            cmd_str = ' '.join(
-                "'" + str(x).replace("'", "'\"'\"'") + "'" for x in cmd
-            )
-        else:
-            cmd_str = str(cmd)
+            cmd = ' '.join("'" + str(x).replace("'", "'\"'\"'") + "'"
+                           for x in cmd)
 
-        log = {
-            'msg': msg,
-            'duration': None,
-            'timestamp': start_time.strftime("%Y-%m-%d_%H%M%S"),
-            'cmd': cmd_str,
-            'cmd_id': cmd_id,
-            'cwd': cwd,
-            'return_code': 0,
-        }
+        # Create a unique command ID that will be used to find the
+        # location of the `stdout`/`stderr` files in the temporary
+        # directory during finalization.
+        cmd_id = 'cmd_' + ''.join(random.choice(string.ascii_lowercase)
+                                  for _ in range(9))
 
-        # Create & open files for stdout and stderr
+        # Create & open files for `stdout` and `stderr`.
         time_str = start_time.strftime("%Y-%m-%d_%H%M%S")
-        stdout_path = self.strm_dir / f"{time_str}_{cmd_id}_stdout"
-        stderr_path = self.strm_dir / f"{time_str}_{cmd_id}_stderr"
-        trace_path = self.strm_dir / f"{time_str}_{cmd_id}_trace" if kwargs.get("trace") else None
+        stdout_path = self.stream_dir / f"{time_str}_{cmd_id}_stdout"
+        stderr_path = self.stream_dir / f"{time_str}_{cmd_id}_stderr"
+        trace_path = (self.stream_dir / f"{time_str}_{cmd_id}_trace"
+                      if kwargs.get("trace") else None)
 
-        with open(stdout_path, 'a') as out, open(stderr_path, 'a') as err:
-            # Print the command to be executed.
+        # Print the command to be executed.
+        with open(stdout_path, 'a'), open(stderr_path, 'a'):
             if verbose:
-                print(cmd_str)
-
-        result = self.run(cmd_str,
+                print(cmd)
+
+        # Initialize the log information.
+        log = {'msg': msg,
+               'duration': None,
+               'timestamp': start_time.strftime("%Y-%m-%d_%H%M%S"),
+               'cmd': cmd,
+               'cmd_id': cmd_id,
+               'cwd': cwd,
+               'return_code': 0}
+
+        # Execute the command.
+        result = self.run(cmd,
                           quiet_stdout=not live_stdout,
                           quiet_stderr=not live_stderr,
                           stdout_str=return_info,
@@ -563,34 +626,50 @@ def log(self, msg, cmd, cwd=None, live_stdout=False,
                           pwd=cwd,
                           **kwargs)
 
-        hrs = int(result.wall / 3600000)
-        min = int(result.wall / 60000) % 60
-        sec = int(result.wall / 1000) % 60
-        log["duration"] = f"{hrs}h {min}m {sec}s"
+        # Update the log information and save it to the `log_book`.
+        h = int(result.wall / 3600000)
+        m = int(result.wall / 60000) % 60
+        s = int(result.wall / 1000) % 60
+        log["duration"] = f"{h}h {m}m {s}s"
         log["return_code"] = result.returncode
         log = {**log, **nested_SimpleNamespace_to_dict(result)}
-
         self.log_book.append(log)
-
         return {'return_code': log['return_code'],
                 'stdout': result.stdout, 'stderr': result.stderr}
 
-    def run(self, command, **kwargs):
+    def run(self, command: str, **kwargs) -> SimpleNamespace:
+        """
+        Todo:  Fill this out.
+
+        Parameters:
+            command:
+            **kwargs:
+
+        Returns:
+
+        Todo:
+            Finish commenting this function.  Figure out how it works
+            first.
+        """
         completed_process, trace_output = None, None
         for key in ["stdout_str", "stderr_str", "trace_str"]:
             if key not in kwargs:
                 kwargs[key] = True
+
+        # Change to the directory in which to execute the command.
         old_pwd = os.getcwd()
         if kwargs.get("pwd"):
             self.shell.cd(kwargs.get("pwd"))
         aux_info = self.auxiliary_information()
-        # Stats collectors use a multiprocessing manager which creates
-        # unix domain sockets with names determined by tempfile.mktemp
-        # which looks at TMPDIR. If TMPDIR is too long, it may result
-        # in the multiprocessing manager trying to use a too long for
-        # UNIX domain sockets, resulting in OSError: AF_UNIX path too
-        # long. The typical maximum path length on Linux is 108. See:
-        # grep '#define UNIX_PATH_MAX' /usr/include/linux/un.h
+
+        # Stats collectors use a multiprocessing manager that creates
+        # unix domain sockets with names determined by
+        # `tempfile.mktemp`, which looks at `TMPDIR`.  If `TMPDIR` is
+        # too long, it may result in the multiprocessing manager trying
+        # to use a string too long for UNIX domain sockets, resulting in
+        # "OSError: AF_UNIX path too long."  The typical maximum path
+        # length on Linux is 108.  See: `grep '#define UNIX_PATH_MAX'
+        # /usr/include/linux/un.h`.
         old_tmpdir = os.environ.get("TMPDIR")
         os.environ["TMPDIR"] = "/tmp"
         collectors = stats_collectors(**kwargs)
@@ -616,12 +695,20 @@ def run(self, command, **kwargs):
                 setattr(completed_process, "trace", f.read())
         else:
             setattr(completed_process, "trace", None)
+
+        # Change back to the original directory and return the results.
         if kwargs.get("pwd"):
             self.shell.cd(old_pwd)
         return SimpleNamespace(**completed_process.__dict__,
                                **aux_info.__dict__)
 
-    def auxiliary_information(self):
+    def auxiliary_information(self) -> SimpleNamespace:
+        """
+        Todo:  Insert docstring.
+
+        Returns:
+
+        """
         pwd, _ = self.shell.auxiliary_command(posix="pwd", nt="cd", strip=True)
         environment, _ = self.shell.auxiliary_command(posix="env", nt="set")
         umask, _ = self.shell.auxiliary_command(posix="umask", strip=True)
@@ -635,27 +722,36 @@ def auxiliary_information(self):
         shell, _ = self.shell.auxiliary_command(posix="printenv SHELL",
                                                 strip=True)
         ulimit, _ = self.shell.auxiliary_command(posix="ulimit -a")
-        x = SimpleNamespace(
-            pwd=pwd,
-            environment=environment,
-            umask=umask,
-            hostname=hostname,
-            user=user,
-            group=group,
-            shell=shell,
-            ulimit=ulimit
-        )
-        return x
+        return SimpleNamespace(pwd=pwd,
+                               environment=environment,
+                               umask=umask,
+                               hostname=hostname,
+                               user=user,
+                               group=group,
+                               shell=shell,
+                               ulimit=ulimit)
+
 
 @Trace.subclass
 class Strace(Trace):
+    """
+    Todo:  Insert docstring.
+    """
     trace_name = "strace"
+
     def __init__(self, **kwargs):
+        """
+        Todo:  Insert docstring.
+        """
         super().__init__(**kwargs)
         self.summary = True if kwargs.get("summary") else False
         self.expression = kwargs.get("expression")
+
     @property
     def trace_args(self):
+        """
+        Todo:  Insert docstring.
+        """
         args = f"strace -f -o {self.output_path}"
         if self.summary:
             args += " -c"
@@ -663,15 +759,27 @@ def trace_args(self):
             args += f" -e '{self.expression}'"
         return args
 
+
 @Trace.subclass
 class Ltrace(Trace):
+    """
+    Todo:  Insert docstring.
+    """
     trace_name = "ltrace"
+
     def __init__(self, **kwargs):
+        """
+        Todo:  Insert docstring.
+        """
         super().__init__(**kwargs)
         self.summary = True if kwargs.get("summary") else False
         self.expression = kwargs.get("expression")
+
     @property
     def trace_args(self):
+        """
+        Todo:  Insert docstring.
+        """
         args = f"ltrace -C -f -o {self.output_path}"
         if self.summary:
             args += " -c"
@@ -679,11 +787,19 @@ def trace_args(self):
             args += f" -e '{self.expression}'"
         return args
 
+
 if psutil is not None:
     @StatsCollector.subclass
     class DiskStatsCollector(StatsCollector):
+        """
+        Todo:  Insert docstring.
+        """
         stat_name = "disk"
+
         def __init__(self, interval, manager):
+            """
+            Todo:  Insert docstring.
+            """
             super().__init__(interval, manager)
             self.stats = manager.dict()
             self.mountpoints = [
@@ -692,68 +808,151 @@ def __init__(self, interval, manager):
             for location in ["/tmp",
                              "/dev/shm",
                              f"/var/run/user/{os.getuid()}"]:
-                if not location in self.mountpoints and Path(location).exists():
+                if (location not in self.mountpoints
+                        and Path(location).exists()):
                     self.mountpoints.append(location)
             for m in self.mountpoints:
                 self.stats[m] = manager.list()
+
         def collect(self):
+            """
+            Todo:  Insert docstring.
+            """
             timestamp = round(time.time() * 1000)
             for m in self.mountpoints:
                 self.stats[m].append((timestamp, psutil.disk_usage(m).percent))
+
         def unproxied_stats(self):
-            return { k:list(v) for k,v in self.stats.items() }
+            """
+            Todo:  Insert docstring.
+            """
+            return {k: list(v) for k, v in self.stats.items()}
 
     @StatsCollector.subclass
     class CPUStatsCollector(StatsCollector):
+        """
+        Todo:  Insert docstring.
+        """
         stat_name = "cpu"
+
         def __init__(self, interval, manager):
+            """
+            Todo:  Insert docstring.
+            """
             super().__init__(interval, manager)
             self.stats = manager.list()
+
         def collect(self):
+            """
+            Todo:  Insert docstring.
+            """
             timestamp = round(time.time() * 1000)
             self.stats.append((timestamp, psutil.cpu_percent(interval=None)))
+
         def unproxied_stats(self):
+            """
+            Todo:  Insert docstring.
+            """
             return list(self.stats)
 
     @StatsCollector.subclass
     class MemoryStatsCollector(StatsCollector):
+        """
+        Todo:  Insert docstring.
+        """
         stat_name = "memory"
+
         def __init__(self, interval, manager):
+            """
+            Todo:  Insert docstring.
+            """
             super().__init__(interval, manager)
             self.stats = manager.list()
+
         def collect(self):
+            """
+            Todo:  Insert docstring.
+            """
             timestamp = round(time.time() * 1000)
             self.stats.append((timestamp, psutil.virtual_memory().percent))
+
         def unproxied_stats(self):
+            """
+            Todo:  Insert docstring.
+            """
             return list(self.stats)
 else:
     @StatsCollector.subclass
     class DiskStatsCollector(StatsCollector):
+        """
+        Todo:  Insert docstring.
+        """
         stat_name = "disk"
+
         def __init__(self, interval, manager):
+            """
+            Todo:  Insert docstring.
+            """
             super().__init__(interval, manager)
+
         def collect(self):
+            """
+            Todo:  Insert docstring.
+            """
             pass
+
         def unproxied_stats(self):
+            """
+            Todo:  Insert docstring.
+            """
             return None
 
     @StatsCollector.subclass
     class CPUStatsCollector(StatsCollector):
+        """
+        Todo:  Insert docstring.
+        """
         stat_name = "cpu"
+
         def __init__(self, interval, manager):
+            """
+            Todo:  Insert docstring.
+            """
             super().__init__(interval, manager)
+
         def collect(self):
+            """
+            Todo:  Insert docstring.
+            """
             pass
+
         def unproxied_stats(self):
+            """
+            Todo:  Insert docstring.
+            """
             return None
 
     @StatsCollector.subclass
     class MemoryStatsCollector(StatsCollector):
+        """
+        Todo:  Insert docstring.
+        """
         stat_name = "memory"
+
         def __init__(self, interval, manager):
+            """
+            Todo:  Insert docstring.
+            """
             super().__init__(interval, manager)
+
         def collect(self):
+            """
+            Todo:  Insert docstring.
+            """
             pass
+
         def unproxied_stats(self):
+            """
+            Todo:  Insert docstring.
+            """
             return None
-