Make changes requested in PR #413

Author: kotfu

cmd2/cmd2.py

@@ -22,7 +22,13 @@
 
 Git repository on GitHub at https://github.com/python-cmd2/cmd2
 """
-# many imports are lazy-loaded when they are needed
+# This module has many imports, quite a few of which are only
+# infrequently utilized. To reduce the initial overhead of
+# import this module, many of these imports are lazy-loaded
+# i.e. we only import the module when we use it
+# For example, we don't import the 'traceback' module
+# until the perror() function is called and the debug
+# setting is True
 import argparse
 import cmd
 import collections
@@ -33,7 +39,7 @@
 import re
 import shlex
 import sys
-from typing import Callable, List, Optional, Union, Tuple
+from typing import Callable, List, Union, Tuple
 
 import pyperclip
 

cmd2/transcript.py

@@ -1,15 +1,29 @@
 #
 # -*- coding: utf-8 -*-
+"""Machinery for running and validating transcripts.
+
+If the user wants to run a transcript (see docs/transcript.rst),
+we need a mechanism to run each command in the transcript as
+a unit test, comparing the expected output to the actual output.
+
+This file contains the classess necessary to make that work. These
+classes are used in cmd2.py::run_transcript_tests()
+"""
 import re
 import glob
 import unittest
 
 from . import utils
 
 class Cmd2TestCase(unittest.TestCase):
-    """Subclass this, setting CmdApp, to make a unittest.TestCase class
-       that will execute the commands in a transcript file and expect the results shown.
-       See example.py"""
+    """A unittest class used for transcript testing.
+
+    Subclass this, setting CmdApp, to make a unittest.TestCase class
+    that will execute the commands in a transcript file and expect the
+    results shown.
+
+    See example.py
+    """
     cmdapp = None
 
     def fetchTranscripts(self):
@@ -90,7 +104,7 @@ def _test_transcript(self, fname, transcript):
             self.assertTrue(re.match(expected, result, re.MULTILINE | re.DOTALL), message)
 
     def _transform_transcript_expected(self, s):
-        """parse the string with slashed regexes into a valid regex
+        """Parse the string with slashed regexes into a valid regex.
 
         Given a string like:
 
@@ -138,8 +152,7 @@ def _transform_transcript_expected(self, s):
 
     @staticmethod
     def _escaped_find(regex, s, start, in_regex):
-        """
-        Find the next slash in {s} after {start} that is not preceded by a backslash.
+        """Find the next slash in {s} after {start} that is not preceded by a backslash.
 
         If we find an escaped slash, add everything up to and including it to regex,
         updating {start}. {start} therefore serves two purposes, tells us where to start
@@ -191,7 +204,9 @@ def tearDown(self):
             self.cmdapp.stdout = self._orig_stdout
 
 class OutputTrap(object):
-    """Instantiate an OutputTrap to divert/capture ALL stdout output.  For use in transcript testing."""
+    """Instantiate an OutputTrap to divert/capture ALL stdout output.
+    For use in transcript testing.
+    """
 
     def __init__(self):
         self.contents = ''

cmd2/utils.py

@@ -102,6 +102,14 @@ def cast(current, new):
     return current
 
 def which(editor: str) -> Optional[str]:
+    """Find the full path of a given editor.
+
+    Return the full path of the given editor, or None if the editor can
+    not be found.
+
+    :param editor: filename of the editor to check, ie 'notepad.exe' or 'vi'
+    :return: a full path or None
+    """
     import subprocess
     try:
         editor_path = subprocess.check_output(['which', editor], stderr=subprocess.STDOUT).strip()
@@ -111,9 +119,10 @@ def which(editor: str) -> Optional[str]:
     return editor_path
 
 def is_text_file(file_path):
-    """
-    Returns if a file contains only ASCII or UTF-8 encoded text
+    """Returns if a file contains only ASCII or UTF-8 encoded text
+
     :param file_path: path to the file being checked
+    :return: True if the file is a text file, False if it is binary.
     """
     import codecs