Renamed completion_hint to hint.

Renamed completion_error to error.
Renamed completion_table to table and converted it from a string to a Rich Table.

Author: kmvanbrunt

CHANGELOG.md

@@ -42,8 +42,8 @@ prompt is displayed.
     - `Cmd.default_sort_key` moved to `utils.DEFAULT_STR_SORT_KEY`.
     - Moved completion state data, which previously resided in `Cmd`, into other classes.
         - `Cmd.matches_sorted` -> `Completions.is_sorted` and `Choices.is_sorted`
-        - `Cmd.completion_hint` -> `Completions.completion_hint`
-        - `Cmd.formatted_completions` -> `Completions.completion_table`
+        - `Cmd.completion_hint` -> `Completions.hint`
+        - `Cmd.formatted_completions` -> `Completions.table` (Now a Rich Table)
         - `Cmd.allow_appended_space/allow_closing_quote` -> `Completions.allow_finalization`
     - Removed `Cmd.matches_delimited` since it's no longer used.
     - Removed `flag_based_complete` and `index_based_complete` functions since their functionality

cmd2/argparse_completer.py

@@ -25,7 +25,6 @@
 from rich.text import Text
 
 from .constants import INFINITY
-from .rich_utils import Cmd2GeneralConsole
 
 if TYPE_CHECKING:  # pragma: no cover
     from .cmd2 import Cmd
@@ -500,11 +499,11 @@ def _handle_last_token(
 
             # If we have results, then return them
             if completions:
-                if not completions.completion_hint:
+                if not completions.hint:
                     # Add a hint even though there are results in case Cmd.always_show_hint is True.
                     completions = dataclasses.replace(
                         completions,
-                        completion_hint=_build_hint(self._parser, flag_arg_state.action),
+                        hint=_build_hint(self._parser, flag_arg_state.action),
                     )
 
                 return completions
@@ -528,11 +527,11 @@ def _handle_last_token(
 
             # If we have results, then return them
             if completions:
-                if not completions.completion_hint:
+                if not completions.hint:
                     # Add a hint even though there are results in case Cmd.always_show_hint is True.
                     completions = dataclasses.replace(
                         completions,
-                        completion_hint=_build_hint(self._parser, pos_arg_state.action),
+                        hint=_build_hint(self._parser, pos_arg_state.action),
                     )
                 return completions
 
@@ -592,8 +591,8 @@ def _complete_flags(self, text: str, line: str, begidx: int, endidx: int, used_f
 
         return Completions(items)
 
-    def _format_completions(self, arg_state: _ArgumentState, completions: Completions) -> Completions:
-        """Format CompletionItems into completion table."""
+    def _build_completion_table(self, arg_state: _ArgumentState, completions: Completions) -> Completions:
+        """Build a rich.Table for completion results if applicable."""
         # Skip table generation for single results or if the list exceeds the
         # user-defined threshold for table display.
         if len(completions) < 2 or len(completions) > self._cmd2_app.max_completion_table_items:
@@ -627,19 +626,14 @@ def _format_completions(self, arg_state: _ArgumentState, completions: Completion
             column if isinstance(column, Column) else Column(column, overflow="fold") for column in table_header
         )
 
-        # Add the data rows
-        hint_table = Table(*rich_columns, box=SIMPLE_HEAD, show_edge=False, border_style=Cmd2Style.TABLE_BORDER)
+        # Build the table
+        table = Table(*rich_columns, box=SIMPLE_HEAD, show_edge=False, border_style=Cmd2Style.TABLE_BORDER)
         for item in completions:
-            hint_table.add_row(Text.from_ansi(item.display), *item.table_row)
-
-        # Generate the table string
-        console = Cmd2GeneralConsole(file=self._cmd2_app.stdout)
-        with console.capture() as capture:
-            console.print(hint_table, end="", soft_wrap=False)
+            table.add_row(Text.from_ansi(item.display), *item.table_row)
 
         return dataclasses.replace(
             completions,
-            completion_table=capture.get(),
+            table=table,
         )
 
     def complete_subcommand_help(self, text: str, line: str, begidx: int, endidx: int, tokens: Sequence[str]) -> Completions:
@@ -780,7 +774,7 @@ def _complete_arg(
             filtered = [choice for choice in all_choices if choice.text not in used_values]
             completions = self._cmd2_app.basic_complete(text, line, begidx, endidx, filtered)
 
-        return self._format_completions(arg_state, completions)
+        return self._build_completion_table(arg_state, completions)
 
 
 # The default ArgparseCompleter class for a cmd2 app

cmd2/cmd2.py

@@ -2467,26 +2467,26 @@ def complete(
             return completions  # noqa: TRY300
 
         except CompletionError as ex:
-            err_str = str(ex)
-            completion_error = ""
+            error_msg = str(ex)
+            formatted_error = ""
 
             # Don't display anything if the error is blank (e.g. _NoResultsError for an argument which supresses hints)
-            if err_str:
+            if error_msg:
                 # _NoResultsError completion hints already include a trailing "\n".
                 end = "" if isinstance(ex, argparse_completer._NoResultsError) else "\n"
 
                 console = Cmd2GeneralConsole(file=self.stdout)
                 with console.capture() as capture:
                     console.print(
-                        err_str,
+                        error_msg,
                         style=Cmd2Style.ERROR if ex.apply_style else "",
                         end=end,
                     )
-                completion_error = capture.get()
-            return Completions(completion_error=completion_error)
+                formatted_error = capture.get()
+            return Completions(error=formatted_error)
         except Exception as ex:  # noqa: BLE001
             formatted_exception = self.format_exception(ex)
-            return Completions(completion_error=formatted_exception)
+            return Completions(error=formatted_exception)
 
     def in_script(self) -> bool:
         """Return whether a text script is running."""

cmd2/completion.py

@@ -18,6 +18,8 @@
     overload,
 )
 
+from rich.table import Table
+
 from . import string_utils as su
 
 if sys.version_info >= (3, 11):
@@ -214,14 +216,14 @@ class Choices(CompletionResultsBase):
 class Completions(CompletionResultsBase):
     """The results of a completion operation."""
 
-    # An optional hint which prints above completion suggestions
-    completion_hint: str = ""
+    # Optional hint which prints above completion suggestions
+    hint: str = ""
 
     # Optional message to display if an error occurs during completion
-    completion_error: str = ""
+    error: str = ""
 
-    # An optional table string populated by the argparse completer
-    completion_table: str = ""
+    # Optional Rich table which provides more context for the data being completed
+    table: Table | None = None
 
     # If True, the completion engine is allowed to finalize a completion
     # when a single match is found by appending a trailing space and

cmd2/pt_utils.py

@@ -86,17 +86,20 @@ def get_completions(self, document: Document, _complete_event: object) -> Iterab
             text, line=line, begidx=begidx, endidx=endidx, custom_settings=self.custom_settings
         )
 
-        if completions.completion_error:
-            print_formatted_text(pt_filter_style(completions.completion_error))
+        if completions.error:
+            print_formatted_text(pt_filter_style(completions.error))
             return
 
         # Print completion table if present
-        if completions.completion_table:
-            print_formatted_text(pt_filter_style("\n" + completions.completion_table))
+        if completions.table is not None:
+            console = ru.Cmd2GeneralConsole(file=self.cmd_app.stdout)
+            with console.capture() as capture:
+                console.print(completions.table, end="", soft_wrap=False)
+            print_formatted_text(pt_filter_style("\n" + capture.get()))
 
         # Print hint if present and settings say we should
-        if completions.completion_hint and (self.cmd_app.always_show_hint or not completions):
-            print_formatted_text(pt_filter_style(completions.completion_hint))
+        if completions.hint and (self.cmd_app.always_show_hint or not completions):
+            print_formatted_text(pt_filter_style(completions.hint))
 
         if not completions:
             return

examples/argparse_completion.py

@@ -114,7 +114,7 @@ def choices_arg_tokens(self, arg_tokens: dict[str, list[str]]) -> Choices:
         choices_provider=choices_completion_tables,
         metavar="ITEM_ID",
         table_header=["Description"],
-        help="demonstrate use of CompletionItems",
+        help="demonstrate use of completion table",
     )
 
     # Demonstrate use of arg_tokens dictionary