Merge remote-tracking branch 'origin/master' into argparse_remainder

Author: anselor

CHANGELOG.md

@@ -41,7 +41,7 @@
     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
-    * ``alias`` is now a command with subcommands to create, list, and delete aliases. Therefore its syntax
+    * ``alias`` is now a command with sub-commands to create, list, and delete aliases. Therefore its syntax
       has changed. All current alias commands in startup scripts or transcripts will break with this release.
     * `unalias` was deleted since ``alias delete`` replaced it
 

cmd2/argparse_completer.py

@@ -965,6 +965,13 @@ def set_custom_message(self, custom_message: str='') -> None:
         self._custom_error_message = custom_message
     # End cmd2 customization
 
+    def add_subparsers(self, **kwargs):
+        """Custom override. Sets a default title if one was not given."""
+        if 'title' not in kwargs:
+            kwargs['title'] = 'sub-commands'
+
+        return super().add_subparsers(**kwargs)
+
     def error(self, message: str) -> None:
         """Custom error override. Allows application to control the error being displayed by argparse"""
         if len(self._custom_error_message) > 0:

cmd2/cmd2.py

@@ -548,8 +548,8 @@ def __init__(self, completekey: str='tab', stdin=None, stdout=None, persistent_h
         self.exit_code = None
 
         # This lock should be acquired before doing any asynchronous changes to the terminal to
-        # ensure the updates to the terminal don't interfere with the input being typed. It can be
-        # acquired any time there is a readline prompt on screen.
+        # ensure the updates to the terminal don't interfere with the input being typed or output
+        # being printed by a command.
         self.terminal_lock = threading.RLock()
 
     # -----  Methods related to presenting output to the user -----
@@ -2204,7 +2204,7 @@ def _cmdloop(self) -> bool:
 
             return stop
 
-    # -----  Alias subcommand functions -----
+    # -----  Alias sub-command functions -----
 
     def alias_create(self, args: argparse.Namespace):
         """Create or overwrite an alias"""
@@ -2267,8 +2267,8 @@ def alias_list(self, args: argparse.Namespace):
                     "  macro")
     alias_parser = ACArgumentParser(description=alias_description, epilog=alias_epilog, prog='alias')
 
-    # Add subcommands to alias
-    alias_subparsers = alias_parser.add_subparsers(title='sub-commands')
+    # Add sub-commands to alias
+    alias_subparsers = alias_parser.add_subparsers()
 
     # alias -> create
     alias_create_help = "create or overwrite an alias"
@@ -2326,13 +2326,13 @@ def do_alias(self, args: argparse.Namespace):
         """Manage aliases"""
         func = getattr(args, 'func', None)
         if func is not None:
-            # Call whatever subcommand function was selected
+            # Call whatever sub-command function was selected
             func(self, args)
         else:
-            # No subcommand was provided, so call help
+            # No sub-command was provided, so call help
             self.do_help('alias')
 
-    # -----  Macro subcommand functions -----
+    # -----  Macro sub-command functions -----
 
     def macro_create(self, args: argparse.Namespace):
         """Create or overwrite a macro"""
@@ -2445,8 +2445,8 @@ def macro_list(self, args: argparse.Namespace):
                     "  alias")
     macro_parser = ACArgumentParser(description=macro_description, epilog=macro_epilog, prog='macro')
 
-    # Add subcommands to macro
-    macro_subparsers = macro_parser.add_subparsers(title='sub-commands')
+    # Add sub-commands to macro
+    macro_subparsers = macro_parser.add_subparsers()
 
     # macro -> create
     macro_create_help = "create or overwrite a macro"
@@ -2527,10 +2527,10 @@ def do_macro(self, args: argparse.Namespace):
         """Manage macros"""
         func = getattr(args, 'func', None)
         if func is not None:
-            # Call whatever subcommand function was selected
+            # Call whatever sub-command function was selected
             func(self, args)
         else:
-            # No subcommand was provided, so call help
+            # No sub-command was provided, so call help
             self.do_help('macro')
 
     def complete_help_command(self, text: str, line: str, begidx: int, endidx: int) -> List[str]:
@@ -2551,7 +2551,7 @@ def complete_help_subcommand(self, text: str, line: str, begidx: int, endidx: in
         if not tokens:
             return []
 
-        # Must have at least 3 args for 'help command subcommand'
+        # Must have at least 3 args for 'help command sub-command'
         if len(tokens) < 3:
             return []
 
@@ -2580,7 +2580,7 @@ def complete_help_subcommand(self, text: str, line: str, begidx: int, endidx: in
 
     setattr(help_parser.add_argument('command', help="command to retrieve help for", nargs="?"),
             ACTION_ARG_CHOICES, ('complete_help_command',))
-    setattr(help_parser.add_argument('subcommand', help="subcommand to retrieve help for",
+    setattr(help_parser.add_argument('subcommand', help="sub-command to retrieve help for",
                                      nargs=argparse.REMAINDER),
             ACTION_ARG_CHOICES, ('complete_help_subcommand',))
     help_parser.add_argument('-v', '--verbose', action='store_true',
@@ -3481,12 +3481,13 @@ def _clear_input_lines_str(self) -> str:  # pragma: no cover
 
     def async_alert(self, alert_msg: str, new_prompt: Optional[str] = None) -> None:  # pragma: no cover
         """
-        Used to display an important message to the user while they are at the prompt in between commands.
+        Display an important message to the user while they are at the prompt in between commands.
         To the user it appears as if an alert message is printed above the prompt and their current input
         text and cursor location is left alone.
 
-        IMPORTANT: Do not call this unless you have acquired self.terminal_lock
-                   first, which ensures a prompt is onscreen
+        IMPORTANT: This function will not print an alert unless it can acquire self.terminal_lock to ensure
+                   a prompt is onscreen.  Therefore it is best to acquire the lock before calling this function
+                   to guarantee the alert prints.
 
         :param alert_msg: the message to display to the user
         :param new_prompt: if you also want to change the prompt that is displayed, then include it here
@@ -3525,34 +3526,48 @@ def async_alert(self, alert_msg: str, new_prompt: Optional[str] = None) -> None:
 
     def async_update_prompt(self, new_prompt: str) -> None:  # pragma: no cover
         """
-        Updates the prompt while the user is still typing at it. This is good for alerting the user to system
+        Update the prompt while the user is still typing at it. This is good for alerting the user to system
         changes dynamically in between commands. For instance you could alter the color of the prompt to indicate
         a system status or increase a counter to report an event. If you do alter the actual text of the prompt,
         it is best to keep the prompt the same width as what's on screen. Otherwise the user's input text will
         be shifted and the update will not be seamless.
 
-        IMPORTANT: Do not call this unless you have acquired self.terminal_lock
-                   first, which ensures a prompt is onscreen
+        IMPORTANT: This function will not update the prompt unless it can acquire self.terminal_lock to ensure
+                   a prompt is onscreen.  Therefore it is best to acquire the lock before calling this function
+                   to guarantee the prompt changes.
 
         :param new_prompt: what to change the prompt to
+        :raises RuntimeError if called while another thread holds terminal_lock
         """
         self.async_alert('', new_prompt)
 
-    @staticmethod
-    def set_window_title(title: str) -> None:  # pragma: no cover
+    def set_window_title(self, title: str) -> None:  # pragma: no cover
         """
-        Sets the terminal window title
+        Set the terminal window title
+
+        IMPORTANT: This function will not set the title unless it can acquire self.terminal_lock to avoid
+                   writing to stderr while a command is running. Therefore it is best to acquire the lock
+                   before calling this function to guarantee the title changes.
+
         :param title: the new window title
+        :raises RuntimeError if called while another thread holds terminal_lock
         """
         if not vt100_support:
             return
 
-        import colorama.ansi as ansi
-        try:
-            sys.stderr.write(ansi.set_title(title))
-        except AttributeError:
-            # Debugging in Pycharm has issues with setting terminal title
-            pass
+        # Sanity check that can't fail if self.terminal_lock was acquired before calling this function
+        if self.terminal_lock.acquire(blocking=False):
+            try:
+                import colorama.ansi as ansi
+                sys.stderr.write(ansi.set_title(title))
+            except AttributeError:
+                # Debugging in Pycharm has issues with setting terminal title
+                pass
+
+            self.terminal_lock.release()
+
+        else:
+            raise RuntimeError("another thread holds terminal_lock")
 
     def cmdloop(self, intro: Optional[str]=None) -> None:
         """This is an outer wrapper around _cmdloop() which deals with extra features provided by cmd2.

cmd2/pyscript_bridge.py

@@ -33,9 +33,16 @@ class CommandResult(namedtuple_with_defaults('CommandResult', ['stdout', 'stderr
 
     NOTE: Named tuples are immutable.  So the contents are there for access, not for modification.
     """
-    def __bool__(self):
-        """If stderr is None and data is not None the command is considered a success"""
-        return not self.stderr and self.data is not None
+    def __bool__(self) -> bool:
+        """Returns True if the command succeeded, otherwise False"""
+
+        # If data has a __bool__ method, then call it to determine success of command
+        if self.data is not None and callable(getattr(self.data, '__bool__', None)):
+            return bool(self.data)
+
+        # Otherwise check if stderr was filled out
+        else:
+            return not self.stderr
 
 
 def _exec_cmd(cmd2_app, func: Callable, echo: bool) -> CommandResult:
@@ -91,7 +98,7 @@ def __dir__(self):
         return commands
 
     def __getattr__(self, item: str):
-        """Search for a subcommand matching this item and update internal state to track the traversal"""
+        """Search for a sub-command matching this item and update internal state to track the traversal"""
         # look for sub-command under the current command/sub-command layer
         for action in self.__current_subcommand_parser._actions:
             if not action.option_strings and isinstance(action, argparse._SubParsersAction):

examples/subcommands.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
 # coding=utf-8
-"""A simple example demonstrating how to use Argparse to support subcommands.
+"""A simple example demonstrating how to use Argparse to support sub-commands.
 
 
-This example shows an easy way for a single command to have many subcommands, each of which takes different arguments
+This example shows an easy way for a single command to have many sub-commands, each of which takes different arguments
 and provides separate contextual help.
 """
 import argparse
@@ -13,15 +13,15 @@
 
 # create the top-level parser for the base command
 base_parser = argparse.ArgumentParser(prog='base')
-base_subparsers = base_parser.add_subparsers(title='subcommands', help='subcommand help')
+base_subparsers = base_parser.add_subparsers(title='sub-commands', help='sub-command help')
 
-# create the parser for the "foo" subcommand
+# create the parser for the "foo" sub-command
 parser_foo = base_subparsers.add_parser('foo', help='foo help')
 parser_foo.add_argument('-x', type=int, default=1, help='integer')
 parser_foo.add_argument('y', type=float, help='float')
 parser_foo.add_argument('input_file', type=str, help='Input File')
 
-# create the parser for the "bar" subcommand
+# create the parser for the "bar" sub-command
 parser_bar = base_subparsers.add_parser('bar', help='bar help')
 
 bar_subparsers = parser_bar.add_subparsers(title='layer3', help='help for 3rd layer of commands')
@@ -31,7 +31,7 @@
 bar_subparsers.add_parser('artichoke', help='artichoke help')
 bar_subparsers.add_parser('cranberries', help='cranberries help')
 
-# create the parser for the "sport" subcommand
+# create the parser for the "sport" sub-command
 parser_sport = base_subparsers.add_parser('sport', help='sport help')
 sport_arg = parser_sport.add_argument('sport', help='Enter name of a sport')
 setattr(sport_arg, 'arg_choices', sport_item_strs)
@@ -40,15 +40,15 @@
 # create the top-level parser for the alternate command
 # The alternate command doesn't provide its own help flag
 base2_parser = argparse.ArgumentParser(prog='alternate', add_help=False)
-base2_subparsers = base2_parser.add_subparsers(title='subcommands', help='subcommand help')
+base2_subparsers = base2_parser.add_subparsers(title='sub-commands', help='sub-command help')
 
-# create the parser for the "foo" subcommand
+# create the parser for the "foo" sub-command
 parser_foo2 = base2_subparsers.add_parser('foo', help='foo help')
 parser_foo2.add_argument('-x', type=int, default=1, help='integer')
 parser_foo2.add_argument('y', type=float, help='float')
 parser_foo2.add_argument('input_file', type=str, help='Input File')
 
-# create the parser for the "bar" subcommand
+# create the parser for the "bar" sub-command
 parser_bar2 = base2_subparsers.add_parser('bar', help='bar help')
 
 bar2_subparsers = parser_bar2.add_subparsers(title='layer3', help='help for 3rd layer of commands')
@@ -58,34 +58,34 @@
 bar2_subparsers.add_parser('artichoke', help='artichoke help')
 bar2_subparsers.add_parser('cranberries', help='cranberries help')
 
-# create the parser for the "sport" subcommand
+# create the parser for the "sport" sub-command
 parser_sport2 = base2_subparsers.add_parser('sport', help='sport help')
 sport2_arg = parser_sport2.add_argument('sport', help='Enter name of a sport')
 setattr(sport2_arg, 'arg_choices', sport_item_strs)
 
 
 class SubcommandsExample(cmd2.Cmd):
     """
-    Example cmd2 application where we a base command which has a couple subcommands
-    and the "sport" subcommand has tab completion enabled.
+    Example cmd2 application where we a base command which has a couple sub-commands
+    and the "sport" sub-command has tab completion enabled.
     """
     def __init__(self):
         super().__init__()
 
-    # subcommand functions for the base command
+    # sub-command functions for the base command
     def base_foo(self, args):
-        """foo subcommand of base command"""
+        """foo sub-command of base command"""
         self.poutput(args.x * args.y)
 
     def base_bar(self, args):
-        """bar subcommand of base command"""
+        """bar sub-command of base command"""
         self.poutput('((%s))' % args.z)
 
     def base_sport(self, args):
-        """sport subcommand of base command"""
+        """sport sub-command of base command"""
         self.poutput('Sport is {}'.format(args.sport))
 
-    # Set handler functions for the subcommands
+    # Set handler functions for the sub-commands
     parser_foo.set_defaults(func=base_foo)
     parser_bar.set_defaults(func=base_bar)
     parser_sport.set_defaults(func=base_sport)
@@ -95,21 +95,21 @@ def do_base(self, args):
         """Base command help"""
         func = getattr(args, 'func', None)
         if func is not None:
-            # Call whatever subcommand function was selected
+            # Call whatever sub-command function was selected
             func(self, args)
         else:
-            # No subcommand was provided, so call help
+            # No sub-command was provided, so call help
             self.do_help('base')
 
     @cmd2.with_argparser(base2_parser)
     def do_alternate(self, args):
         """Alternate command help"""
         func = getattr(args, 'func', None)
         if func is not None:
-            # Call whatever subcommand function was selected
+            # Call whatever sub-command function was selected
             func(self, args)
         else:
-            # No subcommand was provided, so call help
+            # No sub-command was provided, so call help
             self.do_help('alternate')
 
 

examples/tab_autocomp_dynamic.py

@@ -25,7 +25,7 @@ def query_actors() -> List[str]:
 
 
 class TabCompleteExample(cmd2.Cmd):
-    """ Example cmd2 application where we a base command which has a couple subcommands."""
+    """ Example cmd2 application where we a base command which has a couple sub-commands."""
 
     CAT_AUTOCOMPLETE = 'AutoComplete Examples'
 
@@ -225,7 +225,7 @@ def _do_vid_media_shows(self, args) -> None:
     @cmd2.with_category(CAT_AUTOCOMPLETE)
     @cmd2.with_argparser(video_parser)
     def do_video(self, args):
-        """Video management command demonstrates multiple layers of subcommands being handled by AutoCompleter"""
+        """Video management command demonstrates multiple layers of sub-commands being handled by AutoCompleter"""
         func = getattr(args, 'func', None)
         if func is not None:
             # Call whatever subcommand function was selected