Merge branch 'master' into doc_additions

Author: tleonhardt

CHANGELOG.md

@@ -4,6 +4,11 @@
     * Fixed a bug when running a cmd2 application on Linux without Gtk libraries installed
 * Enhancements
     * No longer treating empty text scripts as an error condition
+    * Allow dynamically extending a `cmd2.Cmd` object instance with a `do_xxx` method at runtime
+    * Choices/Completer functions can now be passed a dictionary that maps command-line tokens to their
+    argparse argument. This is helpful when one argument determines what is tab completed for another argument.
+    If these functions have an argument called `arg_tokens`, then AutoCompleter will automatically pass this
+    dictionary to them.
 
 ## 0.9.16 (August 7, 2019)
 * Bug Fixes

cmd2/argparse_completer.py

@@ -44,7 +44,7 @@ class called Cmd2ArgumentParser which improves error and help output over normal
         generated when the user hits tab.
 
         Example:
-            def my_choices_function):
+            def my_choices_function():
                 ...
                 return my_generated_list
 
@@ -102,6 +102,20 @@ def my_completer_function(text, line, begidx, endidx):
         set_completer_function(action, func)
         set_completer_method(action, method)
 
+    There are times when what's being tab completed is determined by a previous argument on the command line.
+    In theses cases, Autocompleter can pass a dictionary that maps the command line tokens up through the one
+    being completed to their argparse argument name. To receive this dictionary, your choices/completer function
+    should have an argument called arg_tokens.
+
+        Example:
+            def my_choices_method(self, arg_tokens)
+            def my_completer_method(self, text, line, begidx, endidx, arg_tokens)
+
+    All values of the arg_tokens dictionary are lists, even if a particular argument expects only 1 token. Since
+    AutoCompleter is for tab completion, it does not convert the tokens to their actual argument types or validate
+    their values. All tokens are stored in the dictionary as the raw strings provided on the command line. It is up to
+    the developer to determine if the user entered the correct argument type (e.g. int) and validate their values.
+
 CompletionItem Class:
     This class was added to help in cases where uninformative data is being tab completed. For instance,
     tab completing ID numbers isn't very helpful to a user without context. Returning a list of CompletionItems
@@ -138,7 +152,7 @@ def my_completer_function(text, line, begidx, endidx):
     To use CompletionItems, just return them from your choices or completer functions.
 
     To avoid printing a ton of information to the screen at once when a user presses tab, there is
-    a maximum threshold for the number of CompletionItems that will be shown. It's value is defined
+    a maximum threshold for the number of CompletionItems that will be shown. Its value is defined
     in cmd2.Cmd.max_completion_items. It defaults to 50, but can be changed. If the number of completion
     suggestions exceeds this number, they will be displayed in the typical columnized format and will
     not include the description value of the CompletionItems.
@@ -159,10 +173,9 @@ def my_completer_function(text, line, begidx, endidx):
 import argparse
 import re
 import sys
-
 # noinspection PyUnresolvedReferences,PyProtectedMember
 from argparse import ZERO_OR_MORE, ONE_OR_MORE, ArgumentError, _
-from typing import Any, Callable, Iterable, List, Optional, Tuple, Union
+from typing import Callable, Optional, Tuple, Union
 
 from .ansi import ansi_aware_write, style_error
 
@@ -272,24 +285,22 @@ def _set_choices_callable(action: argparse.Action, choices_callable: ChoicesCall
     setattr(action, ATTR_CHOICES_CALLABLE, choices_callable)
 
 
-def set_choices_function(action: argparse.Action, choices_function: Callable[[], Iterable[Any]]) -> None:
+def set_choices_function(action: argparse.Action, choices_function: Callable) -> None:
     """Set choices_function on an argparse action"""
     _set_choices_callable(action, ChoicesCallable(is_method=False, is_completer=False, to_call=choices_function))
 
 
-def set_choices_method(action: argparse.Action, choices_method: Callable[[Any], Iterable[Any]]) -> None:
+def set_choices_method(action: argparse.Action, choices_method: Callable) -> None:
     """Set choices_method on an argparse action"""
     _set_choices_callable(action, ChoicesCallable(is_method=True, is_completer=False, to_call=choices_method))
 
 
-def set_completer_function(action: argparse.Action,
-                           completer_function: Callable[[str, str, int, int], List[str]]) -> None:
+def set_completer_function(action: argparse.Action, completer_function: Callable) -> None:
     """Set completer_function on an argparse action"""
     _set_choices_callable(action, ChoicesCallable(is_method=False, is_completer=True, to_call=completer_function))
 
 
-def set_completer_method(action: argparse.Action,
-                         completer_method: Callable[[Any, str, str, int, int], List[str]]) -> None:
+def set_completer_method(action: argparse.Action, completer_method: Callable) -> None:
     """Set completer_method on an argparse action"""
     _set_choices_callable(action, ChoicesCallable(is_method=True, is_completer=True, to_call=completer_method))
 
@@ -305,10 +316,10 @@ def set_completer_method(action: argparse.Action,
 
 def _add_argument_wrapper(self, *args,
                           nargs: Union[int, str, Tuple[int], Tuple[int, int], None] = None,
-                          choices_function: Optional[Callable[[], Iterable[Any]]] = None,
-                          choices_method: Optional[Callable[[Any], Iterable[Any]]] = None,
-                          completer_function: Optional[Callable[[str, str, int, int], List[str]]] = None,
-                          completer_method: Optional[Callable[[Any, str, str, int, int], List[str]]] = None,
+                          choices_function: Optional[Callable] = None,
+                          choices_method: Optional[Callable] = None,
+                          completer_function: Optional[Callable] = None,
+                          completer_method: Optional[Callable] = None,
                           suppress_tab_hint: bool = False,
                           descriptive_header: Optional[str] = None,
                           **kwargs) -> argparse.Action:

cmd2/argparse_custom.py

@@ -119,6 +119,9 @@
 # The argparse parser for the command
 CMD_ATTR_ARGPARSER = 'argparser'
 
+# Whether or not tokens are unquoted before sending to argparse
+CMD_ATTR_PRESERVE_QUOTES = 'preserve_quotes'
+
 
 def categorize(func: Union[Callable, Iterable[Callable]], category: str) -> None:
     """Categorize a function.
@@ -225,8 +228,9 @@ def cmd_wrapper(cmd2_app, statement: Union[Statement, str]):
         # Set the command's help text as argparser.description (which can be None)
         cmd_wrapper.__doc__ = argparser.description
 
-        # Mark this function as having an argparse ArgumentParser
+        # Set some custom attributes for this command
         setattr(cmd_wrapper, CMD_ATTR_ARGPARSER, argparser)
+        setattr(cmd_wrapper, CMD_ATTR_PRESERVE_QUOTES, preserve_quotes)
 
         return cmd_wrapper
 
@@ -283,8 +287,9 @@ def cmd_wrapper(cmd2_app, statement: Union[Statement, str]):
         # Set the command's help text as argparser.description (which can be None)
         cmd_wrapper.__doc__ = argparser.description
 
-        # Mark this function as having an argparse ArgumentParser
+        # Set some custom attributes for this command
         setattr(cmd_wrapper, CMD_ATTR_ARGPARSER, argparser)
+        setattr(cmd_wrapper, CMD_ATTR_PRESERVE_QUOTES, preserve_quotes)
 
         return cmd_wrapper
 
@@ -1431,7 +1436,8 @@ def _completion_for_command(self, text: str, line: str, begidx: int,
                 if func is not None and argparser is not None:
                     import functools
                     compfunc = functools.partial(self._autocomplete_default,
-                                                 argparser=argparser)
+                                                 argparser=argparser,
+                                                 preserve_quotes=getattr(func, CMD_ATTR_PRESERVE_QUOTES))
                 else:
                     compfunc = self.completedefault
 
@@ -1588,13 +1594,21 @@ def complete(self, text: str, state: int) -> Optional[str]:
             self.pexcept(e)
             return None
 
-    def _autocomplete_default(self, text: str, line: str, begidx: int, endidx: int,
-                              argparser: argparse.ArgumentParser) -> List[str]:
+    def _autocomplete_default(self, text: str, line: str, begidx: int, endidx: int, *,
+                              argparser: argparse.ArgumentParser, preserve_quotes: bool) -> List[str]:
         """Default completion function for argparse commands"""
         from .argparse_completer import AutoCompleter
         completer = AutoCompleter(argparser, self)
-        tokens, _ = self.tokens_for_completion(line, begidx, endidx)
-        return completer.complete_command(tokens, text, line, begidx, endidx)
+        tokens, raw_tokens = self.tokens_for_completion(line, begidx, endidx)
+
+        # To have tab-completion parsing match command line parsing behavior,
+        # use preserve_quotes to determine if we parse the quoted or unquoted tokens.
+        tokens_to_parse = raw_tokens if preserve_quotes else tokens
+        return completer.complete_command(tokens_to_parse, text, line, begidx, endidx)
+
+    def get_names(self):
+        """Return an alphabetized list of names comprising the attributes of the cmd2 class instance."""
+        return dir(self)
 
     def get_all_commands(self) -> List[str]:
         """Return a list of all commands"""
@@ -2384,7 +2398,8 @@ def _alias_list(self, args: argparse.Namespace) -> None:
     alias_parser = Cmd2ArgumentParser(description=alias_description, epilog=alias_epilog, prog='alias')
 
     # Add subcommands to alias
-    alias_subparsers = alias_parser.add_subparsers()
+    alias_subparsers = alias_parser.add_subparsers(dest='subcommand')
+    alias_subparsers.required = True
 
     # alias -> create
     alias_create_help = "create or overwrite an alias"
@@ -2439,13 +2454,9 @@ def _alias_list(self, args: argparse.Namespace) -> None:
     @with_argparser(alias_parser, preserve_quotes=True)
     def do_alias(self, args: argparse.Namespace) -> None:
         """Manage aliases"""
-        func = getattr(args, 'func', None)
-        if func is not None:
-            # Call whatever subcommand function was selected
-            func(self, args)
-        else:
-            # noinspection PyTypeChecker
-            self.do_help('alias')
+        # Call whatever subcommand function was selected
+        func = getattr(args, 'func')
+        func(self, args)
 
     # -----  Macro subcommand functions -----
 
@@ -2564,7 +2575,8 @@ def _macro_list(self, args: argparse.Namespace) -> None:
     macro_parser = Cmd2ArgumentParser(description=macro_description, epilog=macro_epilog, prog='macro')
 
     # Add subcommands to macro
-    macro_subparsers = macro_parser.add_subparsers()
+    macro_subparsers = macro_parser.add_subparsers(dest='subcommand')
+    macro_subparsers.required = True
 
     # macro -> create
     macro_create_help = "create or overwrite a macro"
@@ -2641,13 +2653,9 @@ def _macro_list(self, args: argparse.Namespace) -> None:
     @with_argparser(macro_parser, preserve_quotes=True)
     def do_macro(self, args: argparse.Namespace) -> None:
         """Manage macros"""
-        func = getattr(args, 'func', None)
-        if func is not None:
-            # Call whatever subcommand function was selected
-            func(self, args)
-        else:
-            # noinspection PyTypeChecker
-            self.do_help('macro')
+        # Call whatever subcommand function was selected
+        func = getattr(args, 'func')
+        func(self, args)
 
     def complete_help_command(self, text: str, line: str, begidx: int, endidx: int) -> List[str]:
         """Completes the command argument of help"""
@@ -2658,49 +2666,34 @@ def complete_help_command(self, text: str, line: str, begidx: int, endidx: int)
         strs_to_match = list(topics | visible_commands)
         return utils.basic_complete(text, line, begidx, endidx, strs_to_match)
 
-    def complete_help_subcommand(self, text: str, line: str, begidx: int, endidx: int) -> List[str]:
-        """Completes the subcommand argument of help"""
-
-        # Get all tokens through the one being completed
-        tokens, _ = self.tokens_for_completion(line, begidx, endidx)
-
-        if not tokens:
-            return []
-
-        # Must have at least 3 args for 'help command subcommand'
-        if len(tokens) < 3:
-            return []
+    def complete_help_subcommands(self, text: str, line: str, begidx: int, endidx: int,
+                                  arg_tokens: Dict[str, List[str]]) -> List[str]:
+        """Completes the subcommands argument of help"""
 
-        # Find where the command is by skipping past any flags
-        cmd_index = 1
-        for cur_token in tokens[cmd_index:]:
-            if not cur_token.startswith('-'):
-                break
-            cmd_index += 1
-
-        if cmd_index >= len(tokens):
+        # Make sure we have a command whose subcommands we will complete
+        command = arg_tokens['command'][0]
+        if not command:
             return []
 
-        command = tokens[cmd_index]
-        matches = []
-
         # Check if this command uses argparse
         func = self.cmd_func(command)
         argparser = getattr(func, CMD_ATTR_ARGPARSER, None)
+        if func is None or argparser is None:
+            return []
 
-        if func is not None and argparser is not None:
-            from .argparse_completer import AutoCompleter
-            completer = AutoCompleter(argparser, self)
-            matches = completer.complete_command_help(tokens[cmd_index:], text, line, begidx, endidx)
+        # Combine the command and its subcommand tokens for the AutoCompleter
+        tokens = [command] + arg_tokens['subcommands']
 
-        return matches
+        from .argparse_completer import AutoCompleter
+        completer = AutoCompleter(argparser, self)
+        return completer.complete_subcommand_help(tokens, text, line, begidx, endidx)
 
     help_parser = Cmd2ArgumentParser(description="List available commands or provide "
                                                  "detailed help for a specific command")
     help_parser.add_argument('command', nargs=argparse.OPTIONAL, help="command to retrieve help for",
                              completer_method=complete_help_command)
-    help_parser.add_argument('subcommand', nargs=argparse.REMAINDER, help="subcommand to retrieve help for",
-                             completer_method=complete_help_subcommand)
+    help_parser.add_argument('subcommands', nargs=argparse.REMAINDER, help="subcommand(s) to retrieve help for",
+                             completer_method=complete_help_subcommands)
     help_parser.add_argument('-v', '--verbose', action='store_true',
                              help="print a list of all commands with descriptions of each")
 
@@ -2724,7 +2717,7 @@ def do_help(self, args: argparse.Namespace) -> None:
             if func is not None and argparser is not None:
                 from .argparse_completer import AutoCompleter
                 completer = AutoCompleter(argparser, self)
-                tokens = [args.command] + args.subcommand
+                tokens = [args.command] + args.subcommands
 
                 # Set end to blank so the help output matches how it looks when "command -h" is used
                 self.poutput(completer.format_help(tokens), end='')
@@ -2959,14 +2952,11 @@ def enable_completion():
                 choice = int(response)
                 if choice < 1:
                     raise IndexError
-                result = fulloptions[choice - 1][0]
-                break
+                return fulloptions[choice - 1][0]
             except (ValueError, IndexError):
                 self.poutput("{!r} isn't a valid choice. Pick a number between 1 and {}:".format(
                     response, len(fulloptions)))
 
-        return result
-
     def _get_read_only_settings(self) -> str:
         """Return a summary report of read-only settings which the user cannot modify at runtime.
 
@@ -4121,8 +4111,7 @@ def disable_category(self, category: str, message_to_print: str) -> None:
             if getattr(func, CMD_ATTR_HELP_CATEGORY, None) == category:
                 self.disable_command(cmd_name, message_to_print)
 
-    # noinspection PyUnusedLocal
-    def _report_disabled_command_usage(self, *args, message_to_print: str, **kwargs) -> None:
+    def _report_disabled_command_usage(self, *_args, message_to_print: str, **_kwargs) -> None:
         """
         Report when a disabled command has been run or had help called on it
         :param args: not used

cmd2/cmd2.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+# coding=utf-8
+"""A simple example demonstrating how do_* commands can be created in a loop.
+"""
+import functools
+import cmd2
+COMMAND_LIST = ['foo', 'bar', 'baz']
+
+
+class CommandsInLoop(cmd2.Cmd):
+    """Example of dynamically adding do_* commands."""
+    def __init__(self):
+        super().__init__(use_ipython=True)
+
+    def send_text(self, args: cmd2.Statement, *, text: str):
+        """Simulate sending text to a server and printing the response."""
+        self.poutput(text.capitalize())
+
+    def text_help(self, *, text: str):
+        """Deal with printing help for the dynamically added commands."""
+        self.poutput("Simulate sending {!r} to a server and printing the response".format(text))
+
+
+for command in COMMAND_LIST:
+    setattr(CommandsInLoop, 'do_{}'.format(command), functools.partialmethod(CommandsInLoop.send_text, text=command))
+    setattr(CommandsInLoop, 'help_{}'.format(command), functools.partialmethod(CommandsInLoop.text_help, text=command))
+
+
+if __name__ == '__main__':
+    app = CommandsInLoop()
+    app.cmdloop()