Remove always_show_hint settable (#1652)

* Remove always_show_hint settable

This setting worked well for some cases when cmd2 was using readline. However, due to subtle differences in how prompt-toolkit and readline work, setting this True provided a bad user experience with prompt-toolkit.

* Simplified a logic condition to prevent double checking

Also:
- Clarified a parameter description to document how to accept fish-shell style auto-suggestions

Author: tleonhardt

CHANGELOG.md

@@ -99,6 +99,8 @@ prompt is displayed.
     - Renamed `Cmd._command_parsers` to `Cmd.command_parsers`.
     - Removed `RichPrintKwargs` `TypedDict` in favor of using `Mapping[str, Any]`, allowing for
       greater flexibility in passing keyword arguments to `console.print()` calls.
+    - Removed `always_show_hint` settable as it provided a poor user experience with
+      `prompt-toolkit`
 - Enhancements
     - New `cmd2.Cmd` parameters
         - **auto_suggest**: (boolean) if `True`, provide fish shell style auto-suggestions. These

cmd2/argparse_completer.py

@@ -491,13 +491,6 @@ def _handle_last_token(
 
             # If we have results, then return them
             if completions:
-                if not completions.hint:
-                    # Add a hint even though there are results in case Cmd.always_show_hint is True.
-                    completions = dataclasses.replace(
-                        completions,
-                        hint=_build_hint(self._parser, flag_arg_state.action),
-                    )
-
                 return completions
 
             # Otherwise, print a hint if the flag isn't finished or text isn't possibly the start of a flag
@@ -519,12 +512,6 @@ def _handle_last_token(
 
             # If we have results, then return them
             if completions:
-                if not completions.hint:
-                    # Add a hint even though there are results in case Cmd.always_show_hint is True.
-                    completions = dataclasses.replace(
-                        completions,
-                        hint=_build_hint(self._parser, pos_arg_state.action),
-                    )
                 return completions
 
             # Otherwise, print a hint if text isn't possibly the start of a flag

cmd2/cmd2.py

@@ -395,7 +395,8 @@ def __init__(
                                    instantiate and register all commands. If False, CommandSets
                                    must be manually installed with `register_command_set`.
         :param auto_suggest: If True, cmd2 will provide fish shell style auto-suggestions
-                            based on history. If False, these will not be provided.
+                            based on history. User can press right-arrow key to accept the
+                            provided suggestion.
         :param bottom_toolbar: if ``True``, then a bottom toolbar will be displayed.
         :param command_sets: Provide CommandSet instances to load during cmd2 initialization.
                              This allows CommandSets with custom constructor parameters to be
@@ -464,7 +465,6 @@ def __init__(
         self.interactive_pipe = False
 
         # Attributes which ARE dynamically settable via the set command at runtime
-        self.always_show_hint = False
         self.debug = False
         self.echo = False
         self.editor = self.DEFAULT_EDITOR
@@ -1324,10 +1324,6 @@ def allow_style_type(value: str) -> ru.AllowStyle:
                 choices_provider=get_allow_style_choices,
             )
         )
-
-        self.add_settable(
-            Settable("always_show_hint", bool, "Display completion hint even when completion suggestions print", self)
-        )
         self.add_settable(Settable("debug", bool, "Show full traceback on exception", self))
         self.add_settable(Settable("echo", bool, "Echo command issued into output", self))
         self.add_settable(Settable("editor", str, "Program used by 'edit'", self))

cmd2/pt_utils.py

@@ -97,11 +97,10 @@ def get_completions(self, document: Document, _complete_event: object) -> Iterab
                 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.hint and (self.cmd_app.always_show_hint or not completions):
-            print_formatted_text(pt_filter_style(completions.hint))
-
         if not completions:
+            # # Print hint if present
+            if completions.hint:
+                print_formatted_text(pt_filter_style(completions.hint))
             return
 
         # The length of the user's input minus any shortcut.

docs/features/builtin_commands.md

@@ -80,7 +80,6 @@ application:
   Name                            Value      Description
 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  allow_style                     Terminal   Allow ANSI text style sequences in output (valid values: Always, Never, Terminal)
- always_show_hint                False      Display completion hint even when completion suggestions print
  debug                           False      Show full traceback on exception
  echo                            False      Echo command issued into output
  editor                          vim        Program used by 'edit'

docs/features/initialization.md

@@ -33,7 +33,6 @@ The `cmd2.Cmd` class provides a large number of public instance attributes which
 
 Here are instance attributes of `cmd2.Cmd` which developers might wish to override:
 
-- **always_show_hint**: if `True`, display tab completion hint even when completion suggestions print (Default: `False`)
 - **bottom_toolbar**: if `True`, then a bottom toolbar will be displayed (Default: `False`)
 - **broken_pipe_warning**: if non-empty, this string will be displayed if a broken pipe error occurs
 - **continuation_prompt**: used for multiline commands on 2nd+ line of input

docs/features/settings.md

@@ -37,11 +37,6 @@ This setting can be one of three values:
   stripped.
 - `Always` - ANSI escape sequences are always passed through to the output
 
-### always_show_hint
-
-If `True`, display tab completion hint even when completion suggestions print. The default value of
-this setting is `False`.
-
 ### debug
 
 The default value of this setting is `False`, which causes the `cmd2.Cmd.pexcept` method to only

tests/scripts/postcmds.txt

@@ -1 +1 @@
-set always_show_hint False
+set allow_style Terminal

tests/scripts/precmds.txt

@@ -1 +1 @@
-set always_show_hint True
+set allow_style Always

tests/test_cmd2.py

@@ -488,11 +488,11 @@ def test_run_script_nested_run_scripts(base_app, request) -> None:
     expected = f"""
 {initial_run}
 _relative_run_script precmds.txt
-set always_show_hint True
+set allow_style Always
 help
 shortcuts
 _relative_run_script postcmds.txt
-set always_show_hint False"""
+set allow_style Terminal"""
     out, _err = run_cmd(base_app, "history -s")
     assert out == normalize(expected)
 
@@ -505,11 +505,11 @@ def test_runcmds_plus_hooks(base_app, request) -> None:
     base_app.runcmds_plus_hooks(["run_script " + prefilepath, "help", "shortcuts", "run_script " + postfilepath])
     expected = f"""
 run_script {prefilepath}
-set always_show_hint True
+set allow_style Always
 help
 shortcuts
 run_script {postfilepath}
-set always_show_hint False"""
+set allow_style Terminal"""
 
     out, _err = run_cmd(base_app, "history -s")
     assert out == normalize(expected)