Adds possible support for tabular tab completion results.

Author: anselor

cmd2/argparse_completer.py

@@ -59,6 +59,7 @@ def my_completer(text: str, line: str, begidx: int, endidx:int, extra_param: str
 
 import argparse
 from colorama import Fore
+import os
 import sys
 from typing import List, Dict, Tuple, Callable, Union
 
@@ -78,6 +79,15 @@ def my_completer(text: str, line: str, begidx: int, endidx:int, extra_param: str
 ACTION_SUPPRESS_HINT = 'suppress_hint'
 
 
+class CompletionItem(str):
+    def __new__(cls, o, desc='', *args, **kwargs):
+        return str.__new__(cls, o, *args, **kwargs)
+
+    # noinspection PyMissingConstructor,PyUnusedLocal
+    def __init__(self, o, desc='', *args, **kwargs):
+        self.description = desc
+
+
 class _RangeAction(object):
     def __init__(self, nargs: Union[int, str, Tuple[int, int], None]):
         self.nargs_min = None
@@ -413,6 +423,8 @@ def consume_positional_argument() -> None:
                 completion_results = self._complete_for_arg(flag_action, text, line, begidx, endidx, consumed)
                 if not completion_results:
                     self._print_action_help(flag_action)
+                elif len(completion_results) > 1:
+                    completion_results = self._format_completions(flag_action, completion_results)
 
         # ok, we're not a flag, see if there's a positional argument to complete
         else:
@@ -422,9 +434,37 @@ def consume_positional_argument() -> None:
                 completion_results = self._complete_for_arg(pos_action, text, line, begidx, endidx, consumed)
                 if not completion_results:
                     self._print_action_help(pos_action)
+                elif len(completion_results) > 1:
+                    completion_results = self._format_completions(pos_action, completion_results)
 
         return completion_results
 
+    def _format_completions(self, action, completions: List[Union[str, CompletionItem]]):
+        if completions and len(completions) > 1 and \
+                isinstance(completions[0], CompletionItem):
+
+            token_width = len(action.dest)
+            completions_with_desc = []
+
+            for item in completions:
+                if len(item) > token_width:
+                    token_width = len(item)
+
+            term_size = os.get_terminal_size()
+            fill_width = int(term_size.columns * .6) - (token_width + 2)
+            for item in completions:
+                entry = '{: <{token_width}}{: <{fill_width}}'.format(item, item.description,
+                                                                     token_width=token_width+2,
+                                                                     fill_width=fill_width)
+                completions_with_desc.append(entry)
+
+            header = '\n{: <{token_width}}{}'.format(action.dest, action.desc_header, token_width=token_width+2)
+            print(header)
+
+            self._cmd2_app.display_matches = completions_with_desc
+
+        return completions
+
     def complete_command_help(self, tokens: List[str], text: str, line: str, begidx: int, endidx: int) -> List[str]:
         """Supports the completion of sub-commands for commands through the cmd2 help command."""
         for idx, token in enumerate(tokens):

examples/tab_autocompletion.py

@@ -109,6 +109,18 @@ def instance_query_actors(self) -> List[str]:
         """Simulating a function that queries and returns a completion values"""
         return actors
 
+    def instance_query_movie_ids(self) -> List[str]:
+        """Demonstrates showing tabular hinting of tab completion information"""
+        completions_with_desc = []
+
+        for movie_id, movie_entry in self.MOVIE_DATABASE.items():
+            completions_with_desc.append(argparse_completer.CompletionItem(movie_id, movie_entry['title']))
+
+        setattr(self.vid_delete_movie_id, 'desc_header', 'Title')
+        setattr(self.movies_delete_movie_id, 'desc_header', 'Title')
+
+        return completions_with_desc
+
     # This demonstrates a number of customizations of the AutoCompleter version of ArgumentParser
     #  - The help output will separately group required vs optional flags
     #  - The help output for arguments with multiple flags or with append=True is more concise
@@ -253,6 +265,8 @@ def _do_vid_media_shows(self, args) -> None:
             ('path_complete', [False, False]))
 
     vid_movies_delete_parser = vid_movies_commands_subparsers.add_parser('delete')
+    vid_delete_movie_id = vid_movies_delete_parser.add_argument('movie_id', help='Movie ID')
+    setattr(vid_delete_movie_id, argparse_completer.ACTION_ARG_CHOICES, instance_query_movie_ids)
 
     vid_shows_parser = video_types_subparsers.add_parser('shows')
     vid_shows_parser.set_defaults(func=_do_vid_media_shows)
@@ -328,6 +342,8 @@ def _do_media_shows(self, args) -> None:
     movies_add_parser.add_argument('actor', help='Actors', nargs='*')
 
     movies_delete_parser = movies_commands_subparsers.add_parser('delete')
+    movies_delete_movie_id = movies_delete_parser.add_argument('movie_id', help='Movie ID')
+    setattr(movies_delete_movie_id, argparse_completer.ACTION_ARG_CHOICES, 'instance_query_movie_ids')
 
     movies_load_parser = movies_commands_subparsers.add_parser('load')
     movie_file_action = movies_load_parser.add_argument('movie_file', help='Movie database')
@@ -362,7 +378,7 @@ def complete_media(self, text, line, begidx, endidx):
                    'director': TabCompleteExample.static_list_directors,  # static list
                    'movie_file': (self.path_complete, [False, False])
                    }
-        completer = argparse_completer.AutoCompleter(TabCompleteExample.media_parser, arg_choices=choices)
+        completer = argparse_completer.AutoCompleter(TabCompleteExample.media_parser, arg_choices=choices, cmd2_app=self)
 
         tokens, _ = self.tokens_for_completion(line, begidx, endidx)
         results = completer.complete_command(tokens, text, line, begidx, endidx)