Added flag to configure prompt-toolkit tab-completion style

This defaults to the columnar way.  But a user can set it to CompleteStyle.READLINE_LIKE to get readline style tab completion.

Also:
- Renamed `include_bottom_toolbar` flag to just `bottom_toolbar`
- Renamed `_bottom_toolbar` method to `get_bottom_toolbar` which is a better name for it
- Updated `examples/hello_cmd2.py` to use readline style tab-completion

Author: tleonhardt

CHANGELOG.md

@@ -27,8 +27,8 @@ shell, and the option for a persistent bottom bar that can display realtime stat
       `cmd2.Cmd.async_alert`
 - Enhancements
     - New optional persistent **bottom toolbar** capable of displaying realtime status information,
-      see the `include_bottom_toolbar` optional argument to the initializer for `cmd2.Cmd` and the
-      `cmd2.Cmd2._bottom_toolbar` method that can be overridden as well as the updated
+      see the `bottom_toolbar` optional argument to the initializer for `cmd2.Cmd` and the
+      `cmd2.Cmd2.get_bottom_toolbar` method that can be overridden as well as the updated
       `getting_started.py` example
     - Added `cmd2.Cmd._in_prompt` flag that is set to `True` when the prompt is displayed and the
       application is waiting for user input

cmd2/cmd2.py

@@ -307,8 +307,9 @@ def __init__(
         auto_load_commands: bool = False,
         allow_clipboard: bool = True,
         suggest_similar_command: bool = False,
-        include_bottom_toolbar: bool = False,
         intro: RenderableType = '',
+        bottom_toolbar: bool = False,
+        complete_style: CompleteStyle = CompleteStyle.COLUMN,
     ) -> None:
         """Easy but powerful framework for writing line-oriented command interpreters, extends Python's cmd package.
 
@@ -358,8 +359,10 @@ def __init__(
         :param allow_clipboard: If False, cmd2 will disable clipboard interactions
         :param suggest_similar_command: if ``True``, then when a command is not found,
                                         [cmd2.Cmd][] will look for similar commands and suggest them.
-        :param include_bottom_toolbar: if ``True``, then a bottom toolbar will be displayed.
         :param intro: introduction to display at startup
+        :param bottom_toolbar: if ``True``, then a bottom toolbar will be displayed.
+        :param complete_style: style of prompt-toolkit tab completion to use, defaults to CompleteStyle.COLUMN;
+                               set to CompleteStyle.READLINE_LIKE if you want it like readline
         """
         # Check if py or ipy need to be disabled in this instance
         if not include_py:
@@ -450,13 +453,13 @@ def _(event: Any) -> None:  # pragma: no cover
         # Initialize prompt-toolkit PromptSession
         self.history_adapter = Cmd2History(self)
         self.completer = Cmd2Completer(self)
-        self.include_bottom_toolbar = include_bottom_toolbar
+        self.bottom_toolbar = bottom_toolbar
 
         try:
             self.session: PromptSession[str] = PromptSession(
                 history=self.history_adapter,
                 completer=self.completer,
-                complete_style=CompleteStyle.COLUMN,
+                complete_style=complete_style,
                 complete_in_thread=True,
                 complete_while_typing=False,
                 key_bindings=key_bindings,
@@ -470,7 +473,7 @@ def _(event: Any) -> None:  # pragma: no cover
                 completer=self.completer,
                 input=DummyInput(),
                 output=DummyOutput(),
-                complete_style=CompleteStyle.COLUMN,
+                complete_style=complete_style,
                 complete_in_thread=True,
                 complete_while_typing=False,
                 key_bindings=key_bindings,
@@ -1666,17 +1669,17 @@ def _reset_completion_defaults(self) -> None:
         self.matches_delimited = False
         self.matches_sorted = False
 
-    def _bottom_toolbar(self) -> list[str | tuple[str, str]] | None:
+    def get_bottom_toolbar(self) -> list[str | tuple[str, str]] | None:
         """Get the bottom toolbar content.
 
-        If self.include_bottom_toolbar is False, returns None.
+        If self.bottom_toolbar is False, returns None.
 
         Otherwise returns tokens for prompt-toolkit to populate in the bottom toolbar.
 
         NOTE: This content can extend over multiple lines.  However we would recommend
         keeping it to a single line or two lines maximum.
         """
-        if self.include_bottom_toolbar:
+        if self.bottom_toolbar:
             import datetime
             import shutil
 
@@ -3382,15 +3385,15 @@ def get_prompt() -> ANSI | str:
                             prompt_to_use,
                             completer=completer_to_use,
                             pre_run=self.pre_prompt,
-                            bottom_toolbar=self._bottom_toolbar if self.include_bottom_toolbar else None,
+                            bottom_toolbar=self.get_bottom_toolbar if self.bottom_toolbar else None,
                         )
 
                     # history is None
                     return self.session.prompt(
                         prompt_to_use,
                         completer=completer_to_use,
                         pre_run=self.pre_prompt,
-                        bottom_toolbar=self._bottom_toolbar if self.include_bottom_toolbar else None,
+                        bottom_toolbar=self.get_bottom_toolbar if self.bottom_toolbar else None,
                     )
 
             # Otherwise read from self.stdin
@@ -3405,7 +3408,7 @@ def get_prompt() -> ANSI | str:
                 line = temp_session2.prompt(
                     prompt,
                     pre_run=self.pre_prompt,
-                    bottom_toolbar=self._bottom_toolbar if self.include_bottom_toolbar else None,
+                    bottom_toolbar=self.get_bottom_toolbar if self.bottom_toolbar else None,
                 )
                 if len(line) == 0:
                     raise EOFError
@@ -3420,7 +3423,7 @@ def get_prompt() -> ANSI | str:
                 )
                 line = temp_session3.prompt(
                     pre_run=self.pre_prompt,
-                    bottom_toolbar=self._bottom_toolbar if self.include_bottom_toolbar else None,
+                    bottom_toolbar=self.get_bottom_toolbar if self.bottom_toolbar else None,
                 )
                 if len(line) == 0:
                     raise EOFError

docs/features/initialization.md

@@ -25,6 +25,8 @@ 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`)
+- **complete_style**: style to display tab-completion hints in (from `CompleteStyle` options in `prompt-toolkit`)
 - **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
 - **debug**: if `True`, show full stack trace on error (Default: `False`)
@@ -41,7 +43,6 @@ Here are instance attributes of `cmd2.Cmd` which developers might wish to overri
 - **feedback_to_output**: if `True`, send nonessential output to stdout, if `False` send them to stderr (Default: `False`)
 - **help_error**: the error that prints when no help information can be found
 - **hidden_commands**: commands to exclude from the help menu and tab completion
-- **include_bottom_toolbar**: if `True`, then a bottom toolbar will be displayed (Default: `False`)
 - **last_result**: stores results from the last command run to enable usage of results in a Python script or interactive console. Built-in commands don't make use of this. It is purely there for user-defined commands and convenience.
 - **macros**: dictionary of macro names and their values
 - **max_completion_items**: max number of CompletionItems to display during tab completion (Default: 50)

docs/features/prompt.md

@@ -56,21 +56,22 @@ terminal window while the application is idle and waiting for input.
 
 ### Enabling the Toolbar
 
-To enable the toolbar, set `include_bottom_toolbar=True` in the [cmd2.Cmd.__init__][] constructor:
+To enable the toolbar, set `bottom_toolbar=True` in the [cmd2.Cmd.__init__][] constructor:
 
 ```py
 class App(cmd2.Cmd):
     def __init__(self):
-        super().__init__(include_bottom_toolbar=True)
+        super().__init__(bottom_toolbar=True)
 ```
 
 ### Customizing Toolbar Content
 
-You can customize the content of the toolbar by overriding the [cmd2.Cmd._bottom_toolbar][] method.
-This method should return either a string or a list of `(style, text)` tuples for formatted text.
+You can customize the content of the toolbar by overriding the [cmd2.Cmd.get_bottom_toolbar][]
+method. This method should return either a string or a list of `(style, text)` tuples for formatted
+text.
 
 ```py
-    def _bottom_toolbar(self) -> list[str | tuple[str, str]] | None:
+    def get_bottom_toolbar(self) -> list[str | tuple[str, str]] | None:
         return [
             ('ansigreen', 'My Application Name'),
             ('', ' - '),

docs/upgrades.md

@@ -36,10 +36,10 @@ While we have strived to maintain compatibility, there are some differences:
 `cmd2` now supports an optional, persistent bottom toolbar. This can be used to display information
 such as the application name, current state, or even a real-time clock.
 
-- **Enablement**: Set `include_bottom_toolbar=True` in the [cmd2.Cmd.__init__][] constructor.
-- **Customization**: Override the [cmd2.Cmd._bottom_toolbar][] method to return the content you wish
-  to display. The content can be a simple string or a list of `(style, text)` tuples for formatted
-  text with colors.
+- **Enablement**: Set `bottom_toolbar=True` in the [cmd2.Cmd.__init__][] constructor.
+- **Customization**: Override the [cmd2.Cmd.get_bottom_toolbar][] method to return the content you
+  wish to display. The content can be a simple string or a list of `(style, text)` tuples for
+  formatted text with colors.
 
 See the
 [getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py)

examples/getting_started.py

@@ -43,7 +43,7 @@ def __init__(self) -> None:
         shortcuts = cmd2.DEFAULT_SHORTCUTS
         shortcuts.update({'&': 'intro'})
         super().__init__(
-            include_bottom_toolbar=True,
+            bottom_toolbar=True,
             include_ipy=True,
             multiline_commands=['echo'],
             persistent_history_file='cmd2_history.dat',

examples/hello_cmd2.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python
 """This is intended to be a completely bare-bones cmd2 application suitable for rapid testing and debugging."""
 
+from prompt_toolkit.shortcuts import CompleteStyle
+
 from cmd2 import (
     cmd2,
 )
@@ -9,8 +11,12 @@
     import sys
 
     # If run as the main application, simply start a bare-bones cmd2 application with only built-in functionality.
-    # Enable commands to support interactive Python and IPython shells.
-    app = cmd2.Cmd(include_py=True, include_ipy=True, persistent_history_file='cmd2_history.dat')
+    app = cmd2.Cmd(
+        complete_style=CompleteStyle.READLINE_LIKE,  # Use readline style tab completion instead of prompt-toolkit style
+        include_ipy=True,  # Enable support for interactive Python shell via py command
+        include_py=True,  # Enable support for interactive IPython shell via ipy command
+        persistent_history_file='cmd2_history.dat',  # Persist history between runs
+    )
     app.self_in_py = True  # Enable access to "self" within the py command
     app.debug = True  # Show traceback if/when an exception occurs
     sys.exit(app.cmdloop())

mkdocs.yml

@@ -74,7 +74,7 @@ plugins:
             unwrap_annotated: true
             filters:
               - "!^_"
-              - "_bottom_toolbar"
+              - "get_bottom_toolbar"
             merge_init_into_class: true
             docstring_style: sphinx
             docstring_section_style: spacy

tests/test_cmd2.py

@@ -3444,14 +3444,14 @@ def run_alert():
     assert "Main thread is not at the prompt" in str(exceptions[0])
 
 
-def test_bottom_toolbar(base_app, monkeypatch):
+def test_get_bottom_toolbar(base_app, monkeypatch):
     # Test default (disabled)
-    assert base_app._bottom_toolbar() is None
+    assert base_app.get_bottom_toolbar() is None
 
     # Test enabled
-    base_app.include_bottom_toolbar = True
+    base_app.bottom_toolbar = True
     monkeypatch.setattr(sys, 'argv', ['myapp.py'])
-    toolbar = base_app._bottom_toolbar()
+    toolbar = base_app.get_bottom_toolbar()
     assert isinstance(toolbar, list)
     assert toolbar[0] == ('ansigreen', 'myapp.py')
     assert toolbar[2][0] == 'ansiblue'