Added use of CompletionError to basic completion example

Author: kmvanbrunt

examples/basic_completion.py

@@ -2,18 +2,21 @@
 # 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
+from cmd2 import ansi
 
 # List of strings used with completion functions
 food_item_strs = ['Pizza', 'Ham', 'Ham Sandwich', 'Potato']
@@ -42,7 +45,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 +68,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 +87,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(ansi.style_error("This is how a CompletionError behaves"))
+
 
 if __name__ == '__main__':
     import sys