feat(cmd2): improve completion menu and subcommand handling

Switched PromptSession to CompleteStyle.COLUMN and disabled completion while typing to ensure the menu appears on the first Tab press with descriptions. Updated ArgparseCompleter to return CompletionItems for subcommands and main commands, allowing their descriptions to appear in the prompt-toolkit menu instead of a redundant hint table above the prompt. Restored printing of hint tables for other argument types.

Author: tleonhardt

cmd2/argparse_completer.py

@@ -538,6 +538,12 @@ def _format_completions(self, arg_state: _ArgumentState, completions: list[str]
 
         # Check if there are too many CompletionItems to display as a table
         if len(completions) <= self._cmd2_app.max_completion_items:
+            # Skip generating hint table for subcommands or the main command completion
+            if isinstance(arg_state.action, argparse._SubParsersAction) or (
+                arg_state.action.metavar == "COMMAND" and arg_state.action.dest == "command"
+            ):
+                return cast(list[str], completions)
+
             # If a metavar was defined, use that instead of the dest field
             destination = arg_state.action.metavar if arg_state.action.metavar else arg_state.action.dest
 
@@ -659,9 +665,27 @@ def _complete_arg(
         :raises CompletionError: if the completer or choices function this calls raises one.
         """
         # Check if the arg provides choices to the user
-        arg_choices: list[str] | ChoicesCallable
+        arg_choices: list[str] | list[CompletionItem] | ChoicesCallable
         if arg_state.action.choices is not None:
-            arg_choices = list(arg_state.action.choices)
+            if isinstance(arg_state.action, argparse._SubParsersAction):
+                arg_choices_items: list[CompletionItem] = []
+                # Map parser object to help text using _choices_actions (which contains canonical commands)
+                parser_help = {}
+                for action in arg_state.action._choices_actions:
+                    # Retrieve the parser corresponding to this action
+                    # action.dest is the canonical name
+                    if action.dest in arg_state.action.choices:
+                        subparser = arg_state.action.choices[action.dest]
+                        parser_help[subparser] = action.help if action.help else ''
+
+                # Iterate over all choices (including aliases)
+                for name, subparser in arg_state.action.choices.items():
+                    help_text = parser_help.get(subparser, '')
+                    arg_choices_items.append(CompletionItem(name, [help_text]))
+                arg_choices = arg_choices_items
+            else:
+                arg_choices = list(arg_state.action.choices)
+
             if not arg_choices:
                 return []
 
@@ -716,7 +740,7 @@ def _complete_arg(
         # Otherwise use basic_complete on the choices
         else:
             # Check if the choices come from a function
-            completion_items: list[str] = []
+            completion_items: list[str] | list[CompletionItem] = []
             if isinstance(arg_choices, ChoicesCallable):
                 if not arg_choices.is_completer:
                     choices_func = arg_choices.choices_provider

cmd2/cmd2.py

@@ -445,8 +445,9 @@ def __init__(
             self.session: PromptSession[str] = PromptSession(
                 history=self.history_adapter,
                 completer=self.completer,
-                complete_style=CompleteStyle.READLINE_LIKE,
+                complete_style=CompleteStyle.COLUMN,
                 complete_in_thread=True,
+                complete_while_typing=False,
             )
         except (NoConsoleScreenBufferError, AttributeError, ValueError):
             # Fallback to dummy input/output if PromptSession initialization fails.
@@ -457,8 +458,9 @@ def __init__(
                 completer=self.completer,
                 input=DummyInput(),
                 output=DummyOutput(),
-                complete_style=CompleteStyle.READLINE_LIKE,
+                complete_style=CompleteStyle.COLUMN,
                 complete_in_thread=True,
+                complete_while_typing=False,
             )
 
         # Commands to exclude from the history command
@@ -2519,12 +2521,26 @@ def _get_settable_completion_items(self) -> list[CompletionItem]:
 
         return results
 
-    def _get_commands_aliases_and_macros_for_completion(self) -> list[str]:
+    def _get_commands_aliases_and_macros_for_completion(self) -> list[CompletionItem]:
         """Return a list of visible commands, aliases, and macros for tab completion."""
-        visible_commands = set(self.get_visible_commands())
-        alias_names = set(self.aliases)
-        macro_names = set(self.macros)
-        return list(visible_commands | alias_names | macro_names)
+        results: list[CompletionItem] = []
+
+        # Add commands
+        for command in self.get_visible_commands():
+            # Get the command method
+            func = getattr(self, constants.COMMAND_FUNC_PREFIX + command)
+            description = strip_doc_annotations(func.__doc__).splitlines()[0] if func.__doc__ else ''
+            results.append(CompletionItem(command, [description]))
+
+        # Add aliases
+        for name, value in self.aliases.items():
+            results.append(CompletionItem(name, [f"Alias for: {value}"]))
+
+        # Add macros
+        for name, macro in self.macros.items():
+            results.append(CompletionItem(name, [f"Macro: {macro.value}"]))
+
+        return results
 
     def get_help_topics(self) -> list[str]:
         """Return a list of help topics."""
@@ -3265,6 +3281,8 @@ def get_prompt() -> Any:
                         history=history_to_use,
                         input=self.session.input,
                         output=self.session.output,
+                        complete_style=self.session.complete_style,
+                        complete_while_typing=self.session.complete_while_typing,
                     )
 
                     return temp_session1.prompt(
@@ -3285,6 +3303,8 @@ def get_prompt() -> Any:
             temp_session2: PromptSession[str] = PromptSession(
                 input=self.session.input,
                 output=self.session.output,
+                complete_style=self.session.complete_style,
+                complete_while_typing=self.session.complete_while_typing,
             )
             line = temp_session2.prompt(
                 prompt,
@@ -3298,6 +3318,8 @@ def get_prompt() -> Any:
             temp_session3: PromptSession[str] = PromptSession(
                 input=self.session.input,
                 output=self.session.output,
+                complete_style=self.session.complete_style,
+                complete_while_typing=self.session.complete_while_typing,
             )
             line = temp_session3.prompt(
                 bottom_toolbar=self._bottom_toolbar if self.include_bottom_toolbar else None,

cmd2/pt_utils.py

@@ -19,6 +19,7 @@
     constants,
     utils,
 )
+from .argparse_custom import CompletionItem
 
 if TYPE_CHECKING:
     from .cmd2 import Cmd
@@ -69,7 +70,7 @@ def get_completions(self, document: Document, _complete_event: object) -> Iterab
         # Print formatted completions or hints above the prompt if present
         if self.cmd_app.formatted_completions:
             print_formatted_text(ANSI(self.cmd_app.formatted_completions.rstrip()))
-        elif self.cmd_app.completion_hint:
+        if self.cmd_app.completion_hint:
             print_formatted_text(ANSI(self.cmd_app.completion_hint.rstrip()))
 
         # Now we iterate over self.cmd_app.completion_matches and self.cmd_app.display_matches
@@ -87,14 +88,17 @@ def get_completions(self, document: Document, _complete_event: object) -> Iterab
 
         for i, match in enumerate(matches):
             display = display_matches[i] if use_display_matches else match
+            display_meta = None
+            if isinstance(match, CompletionItem) and match.descriptive_data:
+                display_meta = match.descriptive_data[0]
 
             # prompt_toolkit replaces the word before cursor by default if we use the default Completer?
             # No, we yield Completion(text, start_position=...).
             # Default start_position is 0 (append).
 
             start_position = -len(text)
 
-            yield Completion(match, start_position=start_position, display=display)
+            yield Completion(match, start_position=start_position, display=display, display_meta=display_meta)
 
 
 class Cmd2History(History):