Merge branch 'master' into command_help_noflag

Author: kmvanbrunt

CHANGELOG.md

@@ -9,6 +9,11 @@
     for formatting help/description text
     * Aliases are now sorted alphabetically
     * The **set** command now tab-completes settable parameter names
+* Deletions
+    * The ``preparse``, ``postparsing_precmd``, and ``postparsing_postcmd`` methods *deprecated* in the previous release 
+    have been deleted
+        * The new application lifecycle hook system allows for registration of callbacks to be called at various points
+        in the lifecycle and is more powerful and flexible than the previous system
 
 ## 0.9.4 (August 21, 2018)
 * Bug Fixes

README.md

@@ -14,8 +14,8 @@ applications.  It provides a simple API which is an extension of Python's built-
 of cmd to make your life easier and eliminates much of the boilerplate code which would be necessary
 when using cmd.
 
-[![Screenshot](cmd2.png)](https://github.com/python-cmd2/cmd2/blob/master/cmd2.png)
-
+Click on image below to watch a short video demonstrating the capabilities of cmd2:
+[![Screenshot](cmd2.png)](https://youtu.be/DDU_JH6cFsA)
 
 Main Features
 -------------

cmd2.png

@@ -1649,58 +1649,6 @@ def precmd(self, statement: Statement) -> Statement:
         """
         return statement
 
-    # -----  Methods which are cmd2-specific lifecycle hooks which are not present in cmd -----
-
-    # noinspection PyMethodMayBeStatic
-    def preparse(self, raw: str) -> str:
-        """Hook method executed before user input is parsed.
-
-        WARNING: If it's a multiline command, `preparse()` may not get all the
-        user input. _complete_statement() really does two things: a) parse the
-        user input, and b) accept more input in case it's a multiline command
-        the passed string doesn't have a terminator. `preparse()` is currently
-        called before we know whether it's a multiline command, and before we
-        know whether the user input includes a termination character.
-
-        If you want a reliable pre parsing hook method, register a postparsing
-        hook, modify the user input, and then reparse it.
-
-        :param raw: raw command line input :return: potentially modified raw command line input
-        :return: a potentially modified version of the raw input string
-        """
-        return raw
-
-    # noinspection PyMethodMayBeStatic
-    def postparsing_precmd(self, statement: Statement) -> Tuple[bool, Statement]:
-        """This runs after parsing the command-line, but before anything else; even before adding cmd to history.
-
-        NOTE: This runs before precmd() and prior to any potential output redirection or piping.
-
-        If you wish to fatally fail this command and exit the application entirely, set stop = True.
-
-        If you wish to just fail this command you can do so by raising an exception:
-
-        - raise EmptyStatement - will silently fail and do nothing
-        - raise <AnyOtherException> - will fail and print an error message
-
-        :param statement: the parsed command-line statement as a Statement object
-        :return: (stop, statement) containing a potentially modified version of the statement object
-        """
-        stop = False
-        return stop, statement
-
-    # noinspection PyMethodMayBeStatic
-    def postparsing_postcmd(self, stop: bool) -> bool:
-        """This runs after everything else, including after postcmd().
-
-        It even runs when an empty line is entered.  Thus, if you need to do something like update the prompt due
-        to notifications from a background thread, then this is the method you want to override to do it.
-
-        :param stop: True implies the entire application should exit.
-        :return: True implies the entire application should exit.
-        """
-        return stop
-
     def parseline(self, line: str) -> Tuple[str, str, str]:
         """Parse the line into a command name and a string containing the arguments.
 
@@ -1740,9 +1688,6 @@ def onecmd_plus_hooks(self, line: str) -> bool:
                 data = func(data)
                 if data.stop:
                     break
-            # postparsing_precmd is deprecated
-            if not data.stop:
-                (data.stop, data.statement) = self.postparsing_precmd(data.statement)
             # unpack the data object
             statement = data.statement
             stop = data.stop
@@ -1807,9 +1752,7 @@ def _run_cmdfinalization_hooks(self, stop: bool, statement: Optional[Statement])
                 data = func(data)
             # retrieve the final value of stop, ignoring any
             # modifications to the statement
-            stop = data.stop
-            # postparsing_postcmd is deprecated
-            return self.postparsing_postcmd(stop)
+            return data.stop
         except Exception as ex:
             self.perror(ex)
 
@@ -1863,9 +1806,6 @@ def _complete_statement(self, line: str) -> Statement:
         pipe runs out. We can't refactor it because we need to retain
         backwards compatibility with the standard library version of cmd.
         """
-        # preparse() is deprecated, use self.register_postparsing_hook() instead
-        line = self.preparse(line)
-
         while True:
             try:
                 statement = self.statement_parser.parse(line)
@@ -2220,7 +2160,7 @@ def _cmdloop(self) -> bool:
     def do_alias(self, statement: Statement) -> None:
         """Define or display aliases
 
-Usage:  Usage: alias [name] | [<name> <value>]
+    Usage: alias [name] | [<name> <value>]
     Where:
         name - name of the alias being looked up, added, or replaced
         value - what the alias will be resolved to (if adding or replacing)
@@ -2248,7 +2188,8 @@ def do_alias(self, statement: Statement) -> None:
 
         # If no args were given, then print a list of current aliases
         if not alias_arg_list:
-            for cur_alias in self.aliases:
+            sorted_aliases = utils.alphabetical_sort(list(self.aliases))
+            for cur_alias in sorted_aliases:
                 self.poutput("alias {} {}".format(cur_alias, self.aliases[cur_alias]))
             return
 
@@ -2282,9 +2223,6 @@ def do_alias(self, statement: Statement) -> None:
                 # Set the alias
                 self.aliases[name] = value
                 self.poutput("Alias {!r} created".format(name))
-
-                # Keep aliases in alphabetically sorted order
-                self.aliases = collections.OrderedDict(sorted(self.aliases.items()))
             else:
                 errmsg = "Aliases can not contain: {}".format(invalidchars)
                 self.perror(errmsg, traceback_war=False)
@@ -2305,7 +2243,7 @@ def complete_alias(self, text: str, line: str, begidx: int, endidx: int) -> List
     def do_unalias(self, arglist: List[str]) -> None:
         """Unsets aliases
 
-Usage:  Usage: unalias [-a] name [name ...]
+    Usage: unalias [-a] name [name ...]
     Where:
         name - name of the alias being unset
 
@@ -2454,13 +2392,17 @@ def _print_topics(self, header: str, cmds: List[str], verbose: bool) -> None:
                     doc_block = []
                     found_first = False
                     for doc_line in doc.splitlines():
-                        str(doc_line).strip()
-                        if len(doc_line.strip()) > 0:
-                            doc_block.append(doc_line.strip())
-                            found_first = True
-                        else:
+                        stripped_line = doc_line.strip()
+
+                        # Don't include :param type lines
+                        if stripped_line.startswith(':'):
                             if found_first:
                                 break
+                        elif stripped_line:
+                            doc_block.append(stripped_line)
+                            found_first = True
+                        elif found_first:
+                            break
 
                     for doc_line in doc_block:
                         self.stdout.write('{: <{col_width}}{doc}\n'.format(command,
@@ -2686,9 +2628,11 @@ def do_py(self, arg: str) -> bool:
         Non-python commands can be issued with ``pyscript_name("your command")``.
         Run python code from external script files with ``run("script.py")``
         """
-        from .pyscript_bridge import PyscriptBridge
+        from .pyscript_bridge import PyscriptBridge, CommandResult
         if self._in_py:
-            self.perror("Recursively entering interactive Python consoles is not allowed.", traceback_war=False)
+            err = "Recursively entering interactive Python consoles is not allowed."
+            self.perror(err, traceback_war=False)
+            self._last_result = CommandResult('', err)
             return False
         self._in_py = True
 

cmd2/cmd2.py

@@ -12,15 +12,15 @@
 import sys
 from typing import List, Callable
 
+from .argparse_completer import _RangeAction
+from .utils import namedtuple_with_defaults, StdSim
+
 # Python 3.4 require contextlib2 for temporarily redirecting stderr and stdout
 if sys.version_info < (3, 5):
     from contextlib2 import redirect_stdout, redirect_stderr
 else:
     from contextlib import redirect_stdout, redirect_stderr
 
-from .argparse_completer import _RangeAction
-from .utils import namedtuple_with_defaults
-
 
 class CommandResult(namedtuple_with_defaults('CommandResult', ['stdout', 'stderr', 'data'])):
     """Encapsulates the results from a command.
@@ -38,37 +38,12 @@ def __bool__(self):
         return not self.stderr and self.data is not None
 
 
-class CopyStream(object):
-    """Copies all data written to a stream"""
-    def __init__(self, inner_stream, echo: bool = False) -> None:
-        self.buffer = ''
-        self.inner_stream = inner_stream
-        self.echo = echo
-
-    def write(self, s):
-        self.buffer += s
-        if self.echo:
-            self.inner_stream.write(s)
-
-    def read(self):
-        raise NotImplementedError
-
-    def clear(self):
-        self.buffer = ''
-
-    def __getattr__(self, item: str):
-        if item in self.__dict__:
-            return self.__dict__[item]
-        else:
-            return getattr(self.inner_stream, item)
-
-
 def _exec_cmd(cmd2_app, func: Callable, echo: bool):
     """Helper to encapsulate executing a command and capturing the results"""
-    copy_stdout = CopyStream(sys.stdout, echo)
-    copy_stderr = CopyStream(sys.stderr, echo)
+    copy_stdout = StdSim(sys.stdout, echo)
+    copy_stderr = StdSim(sys.stderr, echo)
 
-    copy_cmd_stdout = CopyStream(cmd2_app.stdout, echo)
+    copy_cmd_stdout = StdSim(cmd2_app.stdout, echo)
 
     cmd2_app._last_result = None
 
@@ -81,9 +56,9 @@ def _exec_cmd(cmd2_app, func: Callable, echo: bool):
         cmd2_app.stdout = copy_cmd_stdout.inner_stream
 
     # if stderr is empty, set it to None
-    stderr = copy_stderr.buffer if copy_stderr.buffer else None
+    stderr = copy_stderr.getvalue() if copy_stderr.getvalue() else None
 
-    outbuf = copy_cmd_stdout.buffer if copy_cmd_stdout.buffer else copy_stdout.buffer
+    outbuf = copy_cmd_stdout.getvalue() if copy_cmd_stdout.getvalue() else copy_stdout.getvalue()
     result = CommandResult(stdout=outbuf, stderr=stderr, data=cmd2_app._last_result)
     return result
 

cmd2/pyscript_bridge.py

@@ -44,7 +44,7 @@ def setUp(self):
 
             # Trap stdout
             self._orig_stdout = self.cmdapp.stdout
-            self.cmdapp.stdout = OutputTrap()
+            self.cmdapp.stdout = utils.StdSim(self.cmdapp.stdout)
 
     def runTest(self):  # was testall
         if self.cmdapp:
@@ -203,24 +203,3 @@ def tearDown(self):
         if self.cmdapp:
             # Restore stdout
             self.cmdapp.stdout = self._orig_stdout
-
-class OutputTrap(object):
-    """Instantiate an OutputTrap to divert/capture ALL stdout output.
-    For use in transcript testing.
-    """
-
-    def __init__(self):
-        self.contents = ''
-
-    def write(self, txt: str):
-        """Add text to the internal contents."""
-        self.contents += txt
-
-    def read(self) -> str:
-        """Read from the internal contents and then clear them out.
-
-        :return: str - text from the internal contents
-        """
-        result = self.contents
-        self.contents = ''
-        return result

cmd2/transcript.py

@@ -246,3 +246,61 @@ def natural_sort(list_to_sort: List[str]) -> List[str]:
     :return: the list sorted naturally
     """
     return sorted(list_to_sort, key=natural_keys)
+
+
+class StdSim(object):
+    """Class to simulate behavior of sys.stdout or sys.stderr.
+
+    Stores contents in internal buffer and optionally echos to the inner stream it is simulating.
+    """
+    class ByteBuf(object):
+        """Inner class which stores an actual bytes buffer and does the actual output if echo is enabled."""
+        def __init__(self, inner_stream, echo: bool = False) -> None:
+            self.byte_buf = b''
+            self.inner_stream = inner_stream
+            self.echo = echo
+
+        def write(self, b: bytes) -> None:
+            """Add bytes to internal bytes buffer and if echo is True, echo contents to inner stream."""
+            if not isinstance(b, bytes):
+                raise TypeError('a bytes-like object is required, not {}'.format(type(b)))
+            self.byte_buf += b
+            if self.echo:
+                self.inner_stream.buffer.write(b)
+
+    def __init__(self, inner_stream, echo: bool = False) -> None:
+        self.buffer = self.ByteBuf(inner_stream, echo)
+        self.inner_stream = inner_stream
+
+    def write(self, s: str) -> None:
+        """Add str to internal bytes buffer and if echo is True, echo contents to inner stream."""
+        if not isinstance(s, str):
+            raise TypeError('write() argument must be str, not {}'.format(type(s)))
+        b = s.encode()
+        self.buffer.write(b)
+
+    def getvalue(self) -> str:
+        """Get the internal contents as a str.
+
+        :return string from the internal contents
+        """
+        return self.buffer.byte_buf.decode()
+
+    def read(self) -> str:
+        """Read from the internal contents as a str and then clear them out.
+
+        :return: string from the internal contents
+        """
+        result = self.getvalue()
+        self.clear()
+        return result
+
+    def clear(self) -> None:
+        """Clear the internal contents."""
+        self.buffer.byte_buf = b''
+
+    def __getattr__(self, item: str):
+        if item in self.__dict__:
+            return self.__dict__[item]
+        else:
+            return getattr(self.inner_stream, item)