Merge pull request #892 from python-cmd2/completion_updates

Completion updates

1 files changed, 27 insertions, 2 deletions

diff --git a/cmd2/utils.py b/cmd2/utils.py
index e324c2f1..6a67c43f 100644
--- a/cmd2/utils.py
+++ b/cmd2/utils.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 @@ class Settable:
                                  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.
         """