diff options
| -rwxr-xr-x | cmd2/cmd2.py | 10 | ||||
| -rw-r--r-- | cmd2/transcript.py | 29 | ||||
| -rw-r--r-- | cmd2/utils.py | 13 |
3 files changed, 41 insertions, 11 deletions
diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index f4ed8d08..f480b3ae 100755 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -22,7 +22,13 @@ is used in place of `print`. 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 platform import re import shlex import sys -from typing import Callable, List, Optional, Union, Tuple +from typing import Callable, List, Union, Tuple import pyperclip diff --git a/cmd2/transcript.py b/cmd2/transcript.py index 7cf15d7d..8a9837a6 100644 --- a/cmd2/transcript.py +++ b/cmd2/transcript.py @@ -1,5 +1,14 @@ # # -*- 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 @@ -7,9 +16,14 @@ 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 @@ class Cmd2TestCase(unittest.TestCase): 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 @@ class Cmd2TestCase(unittest.TestCase): @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 @@ class Cmd2TestCase(unittest.TestCase): 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 = '' diff --git a/cmd2/utils.py b/cmd2/utils.py index a61fd5fd..07969ff1 100644 --- a/cmd2/utils.py +++ b/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 |