Merge pull request #892 from python-cmd2/completion_updates

Completion updates

Author: tleonhardt

CHANGELOG.md

@@ -13,8 +13,12 @@
         * `__name__`: __main__
         * `__file__`: script path (as typed, ~ will be expanded)
     * Only tab complete after redirection tokens if redirection is allowed
+    * Made `CompletionError` exception available to non-argparse tab completion
+    * Added `apply_style` to `CompletionError` initializer. It defaults to True, but can be set to False if
+    you don't want the error text to have `ansi.style_error()` applied to it when printed.
 * Other
     * Removed undocumented `py run` command since it was replaced by `run_pyscript` a while ago
+    * Renamed `AutoCompleter` to `ArgparseCompleter` for clarity
 
 ## 0.10.0 (February 7, 2020)
 * Enhancements

cmd2/__init__.py

@@ -11,7 +11,7 @@
     pass
 
 from .ansi import style, fg, bg
-from .argparse_custom import Cmd2ArgumentParser, CompletionError, CompletionItem, set_default_argument_parser
+from .argparse_custom import Cmd2ArgumentParser, CompletionItem, set_default_argument_parser
 
 # Check if user has defined a module that sets a custom value for argparse_custom.DEFAULT_ARGUMENT_PARSER
 import argparse
@@ -27,4 +27,4 @@
 from .decorators import categorize, with_argument_list, with_argparser, with_argparser_and_unknown_args, with_category
 from .parsing import Statement
 from .py_bridge import CommandResult
-from .utils import Settable
+from .utils import CompletionError, Settable

cmd2/argparse_completer.py

@@ -26,7 +26,7 @@ class called Cmd2ArgumentParser which improves error and help output over normal
         parser.add_argument('-f', nargs=(3, 5))
 
 Tab Completion:
-    cmd2 uses its AutoCompleter class to enable argparse-based tab completion on all commands that use the
+    cmd2 uses its ArgparseCompleter class to enable argparse-based tab completion on all commands that use the
     @with_argparse wrappers. Out of the box you get tab completion of commands, subcommands, and flag names,
     as well as instructive hints about the current argument that print when tab is pressed. In addition,
     you can add tab completion for each argument's values using parameters passed to add_argument().
@@ -53,7 +53,7 @@ def my_choices_function():
 
     choices_method
         This is exactly like choices_function, but the function needs to be an instance method of a cmd2-based class.
-        When AutoCompleter calls the method, it will pass the app instance as the self argument. This is good in
+        When ArgparseCompleter calls the method, it will pass the app instance as the self argument. This is good in
         cases where the list of choices being generated relies on state data of the cmd2-based app
 
         Example:
@@ -74,7 +74,7 @@ def my_completer_function(text, line, begidx, endidx):
 
     completer_method
         This is exactly like completer_function, but the function needs to be an instance method of a cmd2-based class.
-        When AutoCompleter calls the method, it will pass the app instance as the self argument. cmd2 provides
+        When ArgparseCompleter calls the method, it will pass the app instance as the self argument. cmd2 provides
         a few completer methods for convenience (e.g., path_complete, delimiter_complete)
 
         Example:
@@ -113,21 +113,14 @@ 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
+    ArgparseCompleter 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.
 
-CompletionError Class:
-    Raised during tab completion operations to report any sort of error you want printed by the AutoCompleter
-
-    Example use cases
-    - Reading a database to retrieve a tab completion data set failed
-    - A previous command line argument that determines the data set being completed is invalid
-
 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
-    instead of a regular string for completion results will signal the AutoCompleter to output the completion
+    instead of a regular string for completion results will signal the ArgparseCompleter to output the completion
     results in a table of completion tokens with descriptions instead of just a table of tokens.
 
     Instead of this:
@@ -229,17 +222,6 @@ def generate_range_error(range_min: int, range_max: Union[int, float]) -> str:
     return err_str
 
 
-class CompletionError(Exception):
-    """
-    Raised during tab completion operations to report any sort of error you want printed by the AutoCompleter
-
-    Example use cases
-    - Reading a database to retrieve a tab completion data set failed
-    - A previous command line argument that determines the data set being completed is invalid
-    """
-    pass
-
-
 class CompletionItem(str):
     """
     Completion item with descriptive text attached
@@ -353,15 +335,15 @@ def _add_argument_wrapper(self, *args,
     :param nargs: extends argparse nargs functionality by allowing tuples which specify a range (min, max)
                   to specify a max value with no upper bound, use a 1-item tuple (min,)
 
-    # Added args used by AutoCompleter
+    # Added args used by ArgparseCompleter
     :param choices_function: function that provides choices for this argument
     :param choices_method: cmd2-app method that provides choices for this argument
     :param completer_function: tab completion function that provides choices for this argument
     :param completer_method: cmd2-app tab completion method that provides choices for this argument
-    :param suppress_tab_hint: when AutoCompleter has no results to show during tab completion, it displays the current
-                              argument's help text as a hint. Set this to True to suppress the hint. If this argument's
-                              help text is set to argparse.SUPPRESS, then tab hints will not display regardless of the
-                              value passed for suppress_tab_hint. Defaults to False.
+    :param suppress_tab_hint: when ArgparseCompleter has no results to show during tab completion, it displays the
+                              current argument's help text as a hint. Set this to True to suppress the hint. If this
+                              argument's help text is set to argparse.SUPPRESS, then tab hints will not display
+                              regardless of the value passed for suppress_tab_hint. Defaults to False.
     :param descriptive_header: if the provided choices are CompletionItems, then this header will display
                                during tab completion. Defaults to None.
 

cmd2/argparse_custom.py

@@ -47,13 +47,13 @@
 from . import constants
 from . import plugin
 from . import utils
-from .argparse_custom import CompletionError, CompletionItem, DEFAULT_ARGUMENT_PARSER
+from .argparse_custom import CompletionItem, DEFAULT_ARGUMENT_PARSER
 from .clipboard import can_clip, get_paste_buffer, write_to_paste_buffer
 from .decorators import with_argparser
 from .history import History, HistoryItem
 from .parsing import StatementParser, Statement, Macro, MacroArg, shlex_split
 from .rl_utils import rl_type, RlType, rl_get_point, rl_set_prompt, vt100_support, rl_make_safe_prompt, rl_warning
-from .utils import Settable
+from .utils import CompletionError, Settable
 
 # Set up readline
 if rl_type == RlType.NONE:  # pragma: no cover
@@ -1416,17 +1416,27 @@ def complete(self, text: str, state: int) -> Optional[str]:
             except IndexError:
                 return None
 
+        except CompletionError as ex:
+            # Don't print error and redraw the prompt unless the error has length
+            err_str = str(ex)
+            if err_str:
+                if ex.apply_style:
+                    err_str = ansi.style_error(err_str)
+                ansi.style_aware_write(sys.stdout, '\n' + err_str + '\n')
+                rl_force_redisplay()
+            return None
         except Exception as e:
             # Insert a newline so the exception doesn't print in the middle of the command line being tab completed
             self.perror()
             self.pexcept(e)
+            rl_force_redisplay()
             return None
 
     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)
+        from .argparse_completer import ArgparseCompleter
+        completer = ArgparseCompleter(argparser, self)
         tokens, raw_tokens = self.tokens_for_completion(line, begidx, endidx)
 
         # To have tab-completion parsing match command line parsing behavior,
@@ -2560,11 +2570,11 @@ def complete_help_subcommands(self, text: str, line: str, begidx: int, endidx: i
         if func is None or argparser is None:
             return []
 
-        # Combine the command and its subcommand tokens for the AutoCompleter
+        # Combine the command and its subcommand tokens for the ArgparseCompleter
         tokens = [command] + arg_tokens['subcommands']
 
-        from .argparse_completer import AutoCompleter
-        completer = AutoCompleter(argparser, self)
+        from .argparse_completer import ArgparseCompleter
+        completer = ArgparseCompleter(argparser, self)
         return completer.complete_subcommand_help(tokens, text, line, begidx, endidx)
 
     help_parser = DEFAULT_ARGUMENT_PARSER(description="List available commands or provide "
@@ -2576,7 +2586,7 @@ def complete_help_subcommands(self, text: str, line: str, begidx: int, endidx: i
     help_parser.add_argument('-v', '--verbose', action='store_true',
                              help="print a list of all commands with descriptions of each")
 
-    # Get rid of cmd's complete_help() functions so AutoCompleter will complete the help command
+    # Get rid of cmd's complete_help() functions so ArgparseCompleter will complete the help command
     if getattr(cmd.Cmd, 'complete_help', None) is not None:
         delattr(cmd.Cmd, 'complete_help')
 
@@ -2594,8 +2604,8 @@ def do_help(self, args: argparse.Namespace) -> None:
 
             # If the command function uses argparse, then use argparse's help
             if func is not None and argparser is not None:
-                from .argparse_completer import AutoCompleter
-                completer = AutoCompleter(argparser, self)
+                from .argparse_completer import ArgparseCompleter
+                completer = ArgparseCompleter(argparser, self)
                 tokens = [args.command] + args.subcommands
 
                 # Set end to blank so the help output matches how it looks when "command -h" is used
@@ -2838,8 +2848,8 @@ def complete_set_value(self, text: str, line: str, begidx: int, endidx: int,
                                      completer_function=settable.completer_function,
                                      completer_method=settable.completer_method)
 
-        from .argparse_completer import AutoCompleter
-        completer = AutoCompleter(settable_parser, self)
+        from .argparse_completer import ArgparseCompleter
+        completer = ArgparseCompleter(settable_parser, self)
 
         # Use raw_tokens since quotes have been preserved
         _, raw_tokens = self.tokens_for_completion(line, begidx, endidx)
@@ -2860,7 +2870,7 @@ def complete_set_value(self, text: str, line: str, begidx: int, endidx: int,
     set_parser = DEFAULT_ARGUMENT_PARSER(parents=[set_parser_parent])
 
     # Suppress tab-completion hints for this field. The completer method is going to create an
-    # AutoCompleter based on the actual parameter being completed and we only want that hint printing.
+    # ArgparseCompleter based on the actual parameter being completed and we only want that hint printing.
     set_parser.add_argument('value', nargs=argparse.OPTIONAL, help='new value for settable',
                             completer_method=complete_set_value, suppress_tab_hint=True)
 

cmd2/cmd2.py

@@ -72,6 +72,31 @@ def str_to_bool(val: str) -> bool:
     raise ValueError("must be True or False (case-insensitive)")
 
 
+class CompletionError(Exception):
+    """
+    Raised during tab completion operations to report any sort of error you want printed by the ArgparseCompleter
+    This can also be used just to display a message, even if it's not an error. ArgparseCompleter raises
+    CompletionErrors to display tab completion hints and sets apply_style to False so hints aren't colored
+    like error text.
+
+    Example use cases
+    - Reading a database to retrieve a tab completion data set failed
+    - A previous command line argument that determines the data set being completed is invalid
+    - Tab completion hints
+    """
+    def __init__(self, *args, apply_style: bool = True, **kwargs):
+        """
+        Initializer for CompletionError
+        :param apply_style: If True, then ansi.style_error will be applied to the message text when printed.
+                            Set to False in cases where the message text already has the desired style.
+                            Defaults to True.
+        """
+        self.apply_style = apply_style
+
+        # noinspection PyArgumentList
+        super().__init__(*args, **kwargs)
+
+
 class Settable:
     """Used to configure a cmd2 instance member to be settable via the set command in the CLI"""
     def __init__(self, name: str, val_type: Callable, description: str, *,
@@ -109,8 +134,8 @@ def __init__(self, name: str, val_type: Callable, description: str, *,
                                  for this argument (See note below)
 
         Note:
-        For choices_method and completer_method, do not set them to a bound method. This is because AutoCompleter
-        passes the self argument explicitly to these functions.
+        For choices_method and completer_method, do not set them to a bound method. This is because
+        ArgparseCompleter passes the self argument explicitly to these functions.
 
         Therefore instead of passing something like self.path_complete, pass cmd2.Cmd.path_complete.
         """

cmd2/utils.py

@@ -6,8 +6,8 @@
 import argparse
 from typing import Dict, List
 
-from cmd2 import Cmd, Cmd2ArgumentParser, with_argparser, CompletionError, CompletionItem
-from cmd2.utils import basic_complete
+from cmd2 import Cmd, Cmd2ArgumentParser, with_argparser, CompletionItem
+from cmd2.utils import basic_complete, CompletionError
 
 # Data source for argparse.choices
 food_item_strs = ['Pizza', 'Ham', 'Ham Sandwich', 'Potato']

examples/argparse_completion.py

@@ -2,16 +2,18 @@
 # coding=utf-8
 """
 A simple example demonstrating how to enable tab completion by assigning a completer function to do_* commands.
-This also demonstrates capabilities of the following completer methods included with cmd2:
-- delimiter_completer
-- flag_based_complete (see note below)
-- index_based_complete (see note below)
+This also demonstrates capabilities of the following completer features included with cmd2:
+- CompletionError exceptions
+- delimiter_completer()
+- flag_based_complete() (see note below)
+- index_based_complete() (see note below)
 
 flag_based_complete() and index_based_complete() are basic methods and should only be used if you are not
 familiar with argparse. The recommended approach for tab completing positional tokens and flags is to use
 argparse-based completion. For an example integrating tab completion with argparse, see argparse_completion.py
 """
 import functools
+from typing import List
 
 import cmd2
 
@@ -42,7 +44,7 @@ def do_flag_based(self, statement: cmd2.Statement):
         """
         self.poutput("Args: {}".format(statement.args))
 
-    def complete_flag_based(self, text, line, begidx, endidx):
+    def complete_flag_based(self, text, line, begidx, endidx) -> List[str]:
         """Completion function for do_flag_based"""
         flag_dict = \
             {
@@ -65,7 +67,7 @@ def do_index_based(self, statement: cmd2.Statement):
         """Tab completes first 3 arguments using index_based_complete"""
         self.poutput("Args: {}".format(statement.args))
 
-    def complete_index_based(self, text, line, begidx, endidx):
+    def complete_index_based(self, text, line, begidx, endidx) -> List[str]:
         """Completion function for do_index_based"""
         index_dict = \
             {
@@ -84,6 +86,20 @@ def do_delimiter_complete(self, statement: cmd2.Statement):
     complete_delimiter_complete = functools.partialmethod(cmd2.Cmd.delimiter_complete,
                                                           match_against=file_strs, delimiter='/')
 
+    def do_raise_error(self, statement: cmd2.Statement):
+        """Demonstrates effect of raising CompletionError"""
+        self.poutput("Args: {}".format(statement.args))
+
+    def complete_raise_error(self, text, line, begidx, endidx) -> List[str]:
+        """
+        CompletionErrors can be raised if an error occurs while tab completing.
+
+        Example use cases
+            - Reading a database to retrieve a tab completion data set failed
+            - A previous command line argument that determines the data set being completed is invalid
+        """
+        raise cmd2.CompletionError("This is how a CompletionError behaves")
+
 
 if __name__ == '__main__':
     import sys