Documented CompletionError class

Author: kmvanbrunt

cmd2/utils.py

@@ -74,12 +74,12 @@ def str_to_bool(val: str) -> bool:
 
 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.
+    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

docs/features/completion.rst

@@ -34,6 +34,24 @@ similar to the following to your class which inherits from :class:`cmd2.Cmd`::
     complete_bar = functools.partialmethod(cmd2.Cmd.path_complete, path_filter=os.path.isdir)
 
 
+Raising exceptions during completion
+------------------------------------
+There are times when tab completion fails and a message needs to be reported to
+the user. These include the following example 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
+
+``cmd2`` provides the :class:`cmd2.utils.CompletionError` exception class for
+this capability. If an error occurs in which it is more desirable to display
+a message than a stack trace, then raise a ``CompletionError``. By default, the
+message displays in red like an error. However, ``CompletionError`` has a
+member called ``apply_style``. Set this False if the error style should not be
+applied. For instance, ``ArgparseCompleter`` sets it to False when displaying
+completion hints.
+
 Tab Completion Using Argparse Decorators
 ----------------------------------------