Merge pull request #703 from python-cmd2/public_api

Minimize public API of cmd2.Cmd class

Author: tleonhardt

CHANGELOG.md

@@ -1,13 +1,18 @@
-## 0.9.14 (TBD, 2019
+## 0.9.14 (TBD, 2019)
 * Enhancements
     * Added support for and testing with Python 3.8, starting with 3.8 beta
+    * Improved information displayed during transcript testing
 * Breaking Changes
     * Python 3.4 reached its [end of life](https://www.python.org/dev/peps/pep-0429/) on March 18, 2019 and is no longer supported by `cmd2`
+        * If you need to use Python 3.4, you should pin your requirements to use `cmd2` 0.9.13
+    * Made lots of changes to minimize the public API of the `cmd2.Cmd` class
+        * Attributes and methods we do not intend to be public now all begin with an underscore
+        * We make no API stability guarantees about these internal functions
 * **Renamed Commands Notice**
     * The following commands have been renamed. The old names will be supported until the next release. 
-        * load --> run_script
-        * _relative_load --> _relative_run_script
-        * pyscript --> run_pyscript
+        * `load` --> `run_script`
+        * `_relative_load` --> `_relative_run_script`
+        * `pyscript` --> `run_pyscript`
 
 ## 0.9.13 (June 14, 2019)
 * Bug Fixes

README.md

@@ -241,7 +241,7 @@ class CmdLineApp(cmd2.Cmd):
 
     def __init__(self):
         self.maxrepeats = 3
-        shortcuts = dict(self.DEFAULT_SHORTCUTS)
+        shortcuts = dict(cmd2.DEFAULT_SHORTCUTS)
         shortcuts.update({'&': 'speak'})
 
         # Set use_ipython to True to enable the "ipy" command which embeds and interactive IPython shell

cmd2/__init__.py

@@ -12,4 +12,5 @@
 
 from .cmd2 import Cmd, Statement, EmptyStatement, categorize
 from .cmd2 import with_argument_list, with_argparser, with_argparser_and_unknown_args, with_category
+from .constants import DEFAULT_SHORTCUTS
 from .pyscript_bridge import CommandResult

cmd2/cmd2.py

@@ -24,3 +24,5 @@
 COLORS_NEVER = 'Never'
 COLORS_TERMINAL = 'Terminal'
 COLORS_ALWAYS = 'Always'
+
+DEFAULT_SHORTCUTS = {'?': 'help', '!': 'shell', '@': 'run_script', '@@': '_relative_run_script'}

cmd2/constants.py

@@ -324,7 +324,7 @@ def is_valid_command(self, word: str) -> Tuple[bool, str]:
         This string is suitable for inclusion in an error message of your
         choice:
 
-        valid, errmsg = statement_parser.is_valid_command('>')
+        valid, errmsg = _statement_parser.is_valid_command('>')
         if not valid:
             errmsg = "Alias {}".format(errmsg)
         """

cmd2/parsing.py

@@ -23,7 +23,7 @@ class CommandResult(namedtuple_with_defaults('CommandResult', ['stdout', 'stderr
 
     Any combination of these fields can be used when developing a scripting API for a given command.
     By default stdout, stderr, and stop will be captured for you. If there is additional command specific data,
-    then write that to cmd2's _last_result member. That becomes the data member of this tuple.
+    then write that to cmd2's last_result member. That becomes the data member of this tuple.
 
     In some cases, the data member may contain everything needed for a command and storing stdout
     and stderr might just be a duplication of data that wastes memory. In that case, the StdSim can
@@ -88,7 +88,7 @@ def __call__(self, command: str, echo: Optional[bool] = None) -> CommandResult:
         # This will be used to capture sys.stderr
         copy_stderr = StdSim(sys.stderr, echo)
 
-        self._cmd2_app._last_result = None
+        self._cmd2_app.last_result = None
 
         stop = False
         try:
@@ -105,5 +105,5 @@ def __call__(self, command: str, echo: Optional[bool] = None) -> CommandResult:
         result = CommandResult(stdout=copy_cmd_stdout.getvalue(),
                                stderr=copy_stderr.getvalue() if copy_stderr.getvalue() else None,
                                stop=stop,
-                               data=self._cmd2_app._last_result)
+                               data=self._cmd2_app.last_result)
         return result

cmd2/pyscript_bridge.py

@@ -6,8 +6,8 @@
 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()
+This file contains the class necessary to make that work. This
+class is used in cmd2.py::run_transcript_tests()
 """
 import re
 import unittest
@@ -27,27 +27,32 @@ class Cmd2TestCase(unittest.TestCase):
     """
     cmdapp = None
 
-    def fetchTranscripts(self):
-        self.transcripts = {}
-        for fname in self.cmdapp.testfiles:
-            tfile = open(fname)
-            self.transcripts[fname] = iter(tfile.readlines())
-            tfile.close()
-
     def setUp(self):
         if self.cmdapp:
-            self.fetchTranscripts()
+            self._fetchTranscripts()
 
             # Trap stdout
             self._orig_stdout = self.cmdapp.stdout
             self.cmdapp.stdout = utils.StdSim(self.cmdapp.stdout)
 
+    def tearDown(self):
+        if self.cmdapp:
+            # Restore stdout
+            self.cmdapp.stdout = self._orig_stdout
+
     def runTest(self):  # was testall
         if self.cmdapp:
             its = sorted(self.transcripts.items())
             for (fname, transcript) in its:
                 self._test_transcript(fname, transcript)
 
+    def _fetchTranscripts(self):
+        self.transcripts = {}
+        for fname in self.cmdapp.testfiles:
+            tfile = open(fname)
+            self.transcripts[fname] = iter(tfile.readlines())
+            tfile.close()
+
     def _test_transcript(self, fname: str, transcript):
         line_num = 0
         finished = False
@@ -205,8 +210,3 @@ def _escaped_find(regex: str, s: str, start: int, in_regex: bool) -> Tuple[str,
                     # slash is not escaped, this is what we are looking for
                     break
         return regex, pos, start
-
-    def tearDown(self):
-        if self.cmdapp:
-            # Restore stdout
-            self.cmdapp.stdout = self._orig_stdout

cmd2/transcript.py

@@ -5,6 +5,7 @@
 import glob
 import os
 import re
+import shutil
 import subprocess
 import sys
 import threading
@@ -348,6 +349,50 @@ def files_from_glob_patterns(patterns: List[str], access=os.F_OK) -> List[str]:
     return files
 
 
+def get_exes_in_path(starts_with: str) -> List[str]:
+    """Returns names of executables in a user's path
+
+    :param starts_with: what the exes should start with. leave blank for all exes in path.
+    :return: a list of matching exe names
+    """
+    # Purposely don't match any executable containing wildcards
+    wildcards = ['*', '?']
+    for wildcard in wildcards:
+        if wildcard in starts_with:
+            return []
+
+    # Get a list of every directory in the PATH environment variable and ignore symbolic links
+    paths = [p for p in os.getenv('PATH').split(os.path.pathsep) if not os.path.islink(p)]
+
+    # Use a set to store exe names since there can be duplicates
+    exes_set = set()
+
+    # Find every executable file in the user's path that matches the pattern
+    for path in paths:
+        full_path = os.path.join(path, starts_with)
+        matches = files_from_glob_pattern(full_path + '*', access=os.X_OK)
+
+        for match in matches:
+            exes_set.add(os.path.basename(match))
+
+    return list(exes_set)
+
+
+def center_text(msg: str, *, pad: str = ' ') -> str:
+    """Centers text horizontally for display within the current terminal, optionally padding both sides.
+
+    :param msg: message to display in the center
+    :param pad: (optional) if provided, the first character will be used to pad both sides of the message
+    :return: centered message, optionally padded on both sides with pad_char
+    """
+    term_width = shutil.get_terminal_size().columns
+    surrounded_msg = ' {} '.format(msg)
+    if not pad:
+        pad = ' '
+    fill_char = pad[:1]
+    return surrounded_msg.center(term_width, fill_char)
+
+
 class StdSim(object):
     """
     Class to simulate behavior of sys.stdout or sys.stderr.

cmd2/utils.py

@@ -267,7 +267,7 @@ Here's what it looks like::
         if unknown:
             self.perror("dir does not take any positional arguments:", traceback_war=False)
             self.do_help('dir')
-            self._last_result = CommandResult('', 'Bad arguments')
+            self.last_result = CommandResult('', 'Bad arguments')
             return
 
         # Get the contents as a list