Merge branch 'master' into black

# Conflicts:
#	cmd2/__init__.py
#	cmd2/argparse_completer.py
#	cmd2/argparse_custom.py
#	cmd2/cmd2.py
#	cmd2/decorators.py
#	cmd2/exceptions.py
#	cmd2/utils.py
#	examples/arg_decorators.py
#	examples/argparse_completion.py
#	examples/modular_commands_main.py
#	tests/test_argparse_completer.py
#	tests/test_argparse_custom.py
#	tests/test_cmd2.py
#	tests/test_completion.py
#	tests/test_history.py

1 files changed, 24 insertions, 0 deletions

diff --git a/cmd2/exceptions.py b/cmd2/exceptions.py
index c5a08202..b6e18856 100644
--- a/cmd2/exceptions.py
+++ b/cmd2/exceptions.py
@@ -36,6 +36,30 @@ class CommandSetRegistrationError(Exception):
     pass
 
 
+class CompletionError(Exception):
+    """
+    Raised during tab completion operations to report any sort of error you want printed. This can also be used
+    just to display a message, even if it's not an error. For instance, 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)
+
 ############################################################################################################
 # The following exceptions are NOT part of the public API and are intended for internal use only.
 ############################################################################################################