Wrote examples for CompletionError and CompletionItem

Author: kmvanbrunt

examples/argparse_completion.py

@@ -6,25 +6,16 @@
 import argparse
 from typing import List
 
-from cmd2 import Cmd, Cmd2ArgumentParser, with_argparser
+from cmd2 import Cmd, Cmd2ArgumentParser, with_argparser, CompletionError, CompletionItem
 from cmd2.utils import basic_complete
 
+# Data source for argparse.choices
 food_item_strs = ['Pizza', 'Ham', 'Ham Sandwich', 'Potato']
 
-# This data is used to demonstrate delimiter_complete
-file_strs = \
-    [
-        '/home/user/file.db',
-        '/home/user/file space.db',
-        '/home/user/another.db',
-        '/home/other user/maps.db',
-        '/home/other user/tests.db'
-    ]
-
 
 def choices_function() -> List[str]:
     """Choices functions are useful when the choice list is dynamically generated (e.g. from data in a database)"""
-    return ['a', 'dynamic', 'list']
+    return ['a', 'dynamic', 'list', 'goes', 'here']
 
 
 def completer_function(text: str, line: str, begidx: int, endidx: int) -> List[str]:
@@ -33,7 +24,18 @@ def completer_function(text: str, line: str, begidx: int, endidx: int) -> List[s
     need to modify cmd2's instance variables related to tab completion, it will be rare to need a completer
     function. completer_method should be used in those cases.
     """
-    return basic_complete(text, line, begidx, endidx, food_item_strs)
+    match_against = ['a', 'dynamic', 'list', 'goes', 'here']
+    return basic_complete(text, line, begidx, endidx, match_against)
+
+
+def choices_completion_item() -> List[CompletionItem]:
+    """Return CompletionItem instead of strings. These give more context to what's being tab completed."""
+    items = {
+                1: "My item",
+                2: "Another item",
+                3: "Yet another item"
+            }
+    return [CompletionItem(item_id, description) for item_id, description in items.items()]
 
 
 class ArgparseCompletion(Cmd):
@@ -45,6 +47,18 @@ def choices_method(self) -> List[str]:
         """Choices methods are useful when the choice list is based on instance data of your application"""
         return self.sport_item_strs
 
+    def choices_completion_error(self) -> 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
+        """
+        if self.debug:
+            return self.sport_item_strs
+        raise CompletionError("Debug must be true")
+
     # Parser for complete command
     complete_parser = Cmd2ArgumentParser(description="Command demonstrating tab completion with argparse\n"
                                                      "Notice even the flags of this command tab complete")
@@ -61,6 +75,13 @@ def choices_method(self) -> List[str]:
     complete_parser.add_argument('--completer_function', completer_function=completer_function)
     complete_parser.add_argument('--completer_method', completer_method=Cmd.path_complete)
 
+    # Demonstrate raising a CompletionError while tab completing
+    complete_parser.add_argument('--completion_error', choices_method=choices_completion_error)
+
+    # Demonstrate returning CompletionItems instead of strings
+    complete_parser.add_argument('--completion_item', choices_function=choices_completion_item, metavar="ITEM_ID",
+                                 descriptive_header="Description")
+
     @with_argparser(complete_parser)
     def do_complete(self, _: argparse.Namespace) -> None:
         """The complete command"""