Removed bottom_toolbar boolean from Cmd to make get_bottom_toolbar()

work the same way as get_rprompt().

Removed default implementation of get_bottom_toolbar() from Cmd class
and moved it to the getting_started example.

Author: kmvanbrunt

cmd2/cmd2.py

@@ -32,6 +32,7 @@
 import contextlib
 import copy
 import dataclasses
+import datetime
 import functools
 import glob
 import inspect
@@ -73,7 +74,7 @@
 from prompt_toolkit.application import create_app_session, get_app
 from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
 from prompt_toolkit.completion import Completer, DummyCompleter
-from prompt_toolkit.formatted_text import ANSI, FormattedText
+from prompt_toolkit.formatted_text import ANSI, AnyFormattedText
 from prompt_toolkit.history import InMemoryHistory
 from prompt_toolkit.input import DummyInput, create_input
 from prompt_toolkit.key_binding import KeyBindings
@@ -367,7 +368,6 @@ def __init__(
         allow_redirection: bool = True,
         auto_load_commands: bool = False,
         auto_suggest: bool = True,
-        bottom_toolbar: bool = False,
         complete_in_thread: bool = True,
         command_sets: Iterable[CommandSet[Any]] | None = None,
         include_ipy: bool = False,
@@ -376,7 +376,7 @@ def __init__(
         multiline_commands: Iterable[str] | None = None,
         persistent_history_file: str = "",
         persistent_history_length: int = 1000,
-        refresh_interval: float = 0,
+        refresh_interval: float = 0.0,
         shortcuts: Mapping[str, str] | None = None,
         silence_startup_script: bool = False,
         startup_script: str = "",
@@ -405,7 +405,6 @@ def __init__(
         :param auto_suggest: If True, cmd2 will provide fish shell style auto-suggestions
                             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 complete_in_thread: if ``True``, then completion will run in a separate thread.
         :param command_sets: Provide CommandSet instances to load during cmd2 initialization.
                              This allows CommandSets with custom constructor parameters to be
@@ -418,7 +417,7 @@ def __init__(
         :param persistent_history_file: file path to load a persistent cmd2 command history from
         :param persistent_history_length: max number of history items to write
                                           to the persistent history file
-        :param refresh_interval: How often, in seconds, to refresh the UI. Defaults to 0.
+        :param refresh_interval: How often, in seconds, to refresh the UI. Defaults to 0.0.
                                  prompt-toolkit already refreshes the UI every time a key is pressed.
                                  Set this value if you need the UI to update automatically without
                                  user input (e.g., for displaying a clock or background status
@@ -535,7 +534,6 @@ def __init__(
         self._initialize_history(persistent_history_file)
 
         # Create the main PromptSession
-        self.bottom_toolbar = bottom_toolbar
         self.complete_in_thread = complete_in_thread
         self.refresh_interval = refresh_interval
         self.main_session = self._create_main_session(auto_suggest, completekey)
@@ -759,7 +757,7 @@ def _(event: Any) -> None:  # pragma: no cover
         # Base configuration
         kwargs: dict[str, Any] = {
             "auto_suggest": AutoSuggestFromHistory() if auto_suggest else None,
-            "bottom_toolbar": self.get_bottom_toolbar if self.bottom_toolbar else None,
+            "bottom_toolbar": self.get_bottom_toolbar,
             "color_depth": ColorDepth.TRUE_COLOR,
             "complete_style": CompleteStyle.MULTI_COLUMN,
             "complete_in_thread": self.complete_in_thread,
@@ -1983,49 +1981,35 @@ def ppretty(
             end=end,
         )
 
-    def get_bottom_toolbar(self) -> list[str | tuple[str, str]] | None:
+    def get_bottom_toolbar(self) -> AnyFormattedText:
         """Get the bottom toolbar content.
 
-        Returns None if `self.bottom_toolbar` is False. Otherwise, returns a
-        list of tokens to populate the toolbar (which can span multiple lines).
+        This method is intended to be called by prompt-toolkit as a UI lifecycle callback.
+        Because prompt-toolkit triggers this callback on every UI refresh (e.g., on every
+        keypress and at scheduled refresh intervals), keeping this function highly optimized
+        is critical to ensuring the CLI remains responsive.
 
-        NOTE: prompt-toolkit calls this method on every UI refresh (e.g., on every keypress
-              and at scheduled refresh intervals). To ensure the CLI remains responsive, keep
-              this function highly optimized.
-        """
-        if not self.bottom_toolbar:
-            return None
-
-        import datetime
-        import shutil
+        Override this if you want a bottom toolbar displaying contextual information useful for
+        your application. This could be information like the application name, current state,
+        or even a real-time clock.
 
-        # Get the current time in ISO format with 0.01s precision
-        dt = datetime.datetime.now(datetime.timezone.utc).astimezone()
-        now = dt.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-4] + dt.strftime("%z")
-        left_text = sys.argv[0]
-
-        # Get terminal width to calculate padding for right-alignment
-        cols, _ = shutil.get_terminal_size()
-        padding_size = cols - len(left_text) - len(now) - 1
-        if padding_size < 1:
-            padding_size = 1
-        padding = " " * padding_size
+        :return: Content to populate the bottom toolbar, or None to hide it.
+        """
+        return None
 
-        # Return formatted text for prompt-toolkit
-        return [
-            ("ansigreen", left_text),
-            ("", padding),
-            ("ansicyan", now),
-        ]
+    def get_rprompt(self) -> AnyFormattedText:
+        """Provide text to populate the prompt-toolkit right prompt.
 
-    def get_rprompt(self) -> str | FormattedText | None:
-        """Provide text to populate prompt-toolkit right prompt with.
+        This method is intended to be called by prompt-toolkit as a UI lifecycle callback.
+        Because prompt-toolkit triggers this callback on every UI refresh (e.g., on every
+        keypress and at scheduled refresh intervals), keeping this function highly optimized
+        is critical to ensuring the CLI remains responsive.
 
-        Override this if you want a right-prompt displaying contetual information useful for your application.
-        This could be information like current Git branch, time, current working directory, etc that is displayed
-        without cluttering the main input area.
+        Override this if you want a right-prompt displaying contextual information useful for
+        your application. This could be information like the current Git branch, time, or current
+        working directory that is displayed without cluttering the main input area.
 
-        :return: any type of formatted text to display as the right prompt
+        :return: Content to populate the right prompt, or None to hide it.
         """
         return None
 
@@ -2932,8 +2916,6 @@ def onecmd_plus_hooks(
                                command's stdout.
         :return: True if running of commands should stop
         """
-        import datetime
-
         stop = False
         statement = None
 

docs/features/prompt.md

@@ -65,22 +65,11 @@ terminal window while the application is idle and waiting for input.
 
 ### Enabling the Toolbar
 
-To enable the toolbar, set `bottom_toolbar=True` in the [cmd2.Cmd.__init__][] constructor:
+To enable the toolbar, override the [cmd2.Cmd.get_bottom_toolbar][] method to return the content you
+wish to display.
 
 ```py
-class App(cmd2.Cmd):
-    def __init__(self):
-        super().__init__(bottom_toolbar=True)
-```
-
-### Customizing Toolbar Content
-
-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 get_bottom_toolbar(self) -> list[str | tuple[str, str]] | None:
+    def get_bottom_toolbar(self) -> AnyFormattedText:
         return [
             ('ansigreen', 'My Application Name'),
             ('', ' - '),
@@ -92,7 +81,14 @@ text.
 
 Since the toolbar is rendered by `prompt-toolkit` as part of the prompt, it is naturally redrawn
 whenever the prompt is refreshed. If you want the toolbar to update automatically (for example, to
-display a clock), you can use a background thread to call `app.invalidate()` periodically.
+display a clock), you can set `refresh_interval` in the [cmd2.Cmd.__init__][] constructor to a value
+greater than 0.0.
+
+```py
+class App(cmd2.Cmd):
+    def __init__(self):
+        super().__init__(refresh_interval=0.5)
+```
 
 See the
 [getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py)

docs/upgrades.md

@@ -36,10 +36,8 @@ 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 `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.
+- **Enablement**: Override the [cmd2.Cmd.get_bottom_toolbar][] method to return the content you wish
+  to display.
 
 See the
 [getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py)

examples/getting_started.py

@@ -16,9 +16,11 @@
 12) Persistent bottom toolbar with realtime status updates
 """
 
+import datetime
 import pathlib
 
-from prompt_toolkit.formatted_text import FormattedText
+from prompt_toolkit.application import get_app
+from prompt_toolkit.formatted_text import AnyFormattedText
 from rich.style import Style
 
 import cmd2
@@ -44,7 +46,6 @@ def __init__(self) -> None:
 
         super().__init__(
             auto_suggest=True,
-            bottom_toolbar=True,
             include_ipy=True,
             multiline_commands=["echo"],
             persistent_history_file="cmd2_history.dat",
@@ -87,11 +88,33 @@ def __init__(self) -> None:
             )
         )
 
-    def get_rprompt(self) -> str | FormattedText | None:
+    def get_bottom_toolbar(self) -> AnyFormattedText:
+        # Get the current time in ISO format with 0.01s precision
+        dt = datetime.datetime.now(datetime.timezone.utc).astimezone()
+        now = dt.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-4] + dt.strftime("%z")
+        left_text = sys.argv[0]
+
+        # Fetch the terminal width to calculate padding for right-alignment.
+        # If called outside a running app loop (e.g., in unit tests), get_app()
+        # safely returns a dummy app with an 80-column fallback.
+        cols = get_app().output.get_size().columns
+        padding_size = cols - len(left_text) - len(now) - 1
+        if padding_size < 1:
+            padding_size = 1
+        padding = " " * padding_size
+
+        # Return formatted text for prompt-toolkit
+        return [
+            ("ansigreen", left_text),
+            ("", padding),
+            ("ansicyan", now),
+        ]
+
+    def get_rprompt(self) -> AnyFormattedText:
         current_working_directory = pathlib.Path.cwd()
         style = "bg:ansired fg:ansiwhite"
         text = f"cwd={current_working_directory}"
-        return FormattedText([(style, text)])
+        return [(style, text)]
 
     def do_intro(self, _: cmd2.Statement) -> None:
         """Display the intro banner."""

tests/test_cmd2.py

@@ -4289,33 +4289,24 @@ def test_path_complete_users_windows(monkeypatch, base_app):
 
 
 def test_get_bottom_toolbar(base_app, monkeypatch):
-    # Test default (disabled)
+    # Test default
     assert base_app.get_bottom_toolbar() is None
 
-    # Test enabled
-    base_app.bottom_toolbar = True
-    monkeypatch.setattr(sys, "argv", ["myapp.py"])
-    toolbar = base_app.get_bottom_toolbar()
-    assert isinstance(toolbar, list)
-    assert toolbar[0] == ("ansigreen", "myapp.py")
-    assert toolbar[2][0] == "ansicyan"
+    # Test overridden
+    expected_text = "bottom toolbar text"
+    base_app.get_bottom_toolbar = lambda: expected_text
+    assert base_app.get_bottom_toolbar() == expected_text
 
 
 def test_get_rprompt(base_app):
     # Test default
     assert base_app.get_rprompt() is None
 
     # Test overridden
-    from prompt_toolkit.formatted_text import FormattedText
-
     expected_text = "rprompt text"
     base_app.get_rprompt = lambda: expected_text
     assert base_app.get_rprompt() == expected_text
 
-    expected_formatted = FormattedText([("class:status", "OK")])
-    base_app.get_rprompt = lambda: expected_formatted
-    assert base_app.get_rprompt() == expected_formatted
-
 
 def test_multiline_complete_statement_keyboard_interrupt(multiline_app, monkeypatch):
     # Mock _read_command_line to raise KeyboardInterrupt
@@ -4499,25 +4490,6 @@ def my_pre_prompt():
         assert loop_check["running"]
 
 
-def test_get_bottom_toolbar_narrow_terminal(base_app, monkeypatch):
-    """Test get_bottom_toolbar when terminal is too narrow for calculated padding"""
-    import shutil
-
-    base_app.bottom_toolbar = True
-    monkeypatch.setattr(sys, "argv", ["myapp.py"])
-
-    # Mock shutil.get_terminal_size to return a very small width (e.g. 5)
-    # Calculated padding_size = 5 - len('myapp.py') - len(now) - 1
-    # Since len(now) is ~29, this will definitely be < 1
-    monkeypatch.setattr(shutil, "get_terminal_size", lambda: os.terminal_size((5, 20)))
-
-    toolbar = base_app.get_bottom_toolbar()
-    assert isinstance(toolbar, list)
-
-    # The padding (index 1) should be exactly 1 space
-    assert toolbar[1] == ("", " ")
-
-
 def test_auto_suggest_true():
     """Test that auto_suggest=True initializes AutoSuggestFromHistory."""
     app = cmd2.Cmd(auto_suggest=True)