Renamed bottom_toolbar flag to enable_bottom_toolbar.

Added enable_rprompt flag.

Author: kmvanbrunt

CHANGELOG.md

@@ -6,7 +6,8 @@
           thread. If `False` then completion runs in the main thread and causes it to block if slow.
           Defaults to `True`.
         - **refresh_interval**: (float) How often, in seconds, to automatically refresh the UI.
-          Defaults to 0.0.
+          Defaults to 0.0. This is used for bottom toolbars and right prompts which have dynamic
+          content needing to be refreshed at regular intervals and not just when a key is pressed.
 
 - Bug Fixes
     - Fixed type hinting so that methods decorated with `with_annotated` no longer trigger spurious
@@ -48,9 +49,10 @@
       `preprocess=str.lower` on an `Enum`). The two are mutually exclusive on one parameter and
       neither may be combined with a value-less action.
 
-    - Breaking Changes
-        - Removed `Cmd.bottom_toolbar` boolean. Just return `None` from `Cmd.get_bottom_toolbar()`
-          when you don't want to display one. This is exactly how `Cmd.get_rprompt()` works.
+- Breaking Changes
+    - Renamed the `bottom_toolbar` argument in `Cmd.__init__()` to `enable_bottom_toolbar`.
+    - `get_rprompt()` is now only called if the `enable_rprompt` argument in `Cmd.__init__()` is set
+      to `True`.
 
 ## 4.0.0 (June 5, 2026)
 

cmd2/cmd2.py

@@ -370,6 +370,8 @@ def __init__(
         auto_suggest: bool = True,
         complete_in_thread: bool = True,
         command_sets: Iterable[CommandSet[Any]] | None = None,
+        enable_bottom_toolbar: bool = False,
+        enable_rprompt: bool = False,
         include_ipy: bool = False,
         include_py: bool = False,
         intro: RenderableType = "",
@@ -410,6 +412,10 @@ def __init__(
                              This allows CommandSets with custom constructor parameters to be
                              loaded.  This also allows the a set of CommandSets to be provided
                              when `auto_load_commands` is set to False
+        :param enable_bottom_toolbar: if ``True``, enables a bottom toolbar while at the main prompt.
+                                      Override ``get_bottom_toolbar()`` to define its content.
+        :param enable_rprompt: if ``True``, enables a right prompt while at the main prompt.
+                               Override ``get_rprompt()`` to define its content.
         :param include_ipy: should the "ipy" command be included for an embedded IPython shell
         :param include_py: should the "py" command be included for an embedded Python shell
         :param intro: introduction to display at startup
@@ -534,9 +540,14 @@ def __init__(
         self._initialize_history(persistent_history_file)
 
         # Create the main PromptSession
-        self.complete_in_thread = complete_in_thread
-        self.refresh_interval = refresh_interval
-        self.main_session = self._create_main_session(auto_suggest, completekey)
+        self.main_session = self._create_main_session(
+            auto_suggest=auto_suggest,
+            complete_in_thread=complete_in_thread,
+            completekey=completekey,
+            enable_bottom_toolbar=enable_bottom_toolbar,
+            enable_rprompt=enable_rprompt,
+            refresh_interval=refresh_interval,
+        )
 
         # The session currently holding focus (either the main REPL or a command's
         # custom prompt). Completion and UI logic should reference this variable
@@ -727,7 +738,16 @@ def _should_continue_multiline(self) -> bool:
                 # No macro found or already processed. The statement is complete.
                 return False
 
-    def _create_main_session(self, auto_suggest: bool, completekey: str) -> PromptSession[str]:
+    def _create_main_session(
+        self,
+        *,
+        auto_suggest: bool,
+        complete_in_thread: bool,
+        completekey: str,
+        enable_bottom_toolbar: bool,
+        enable_rprompt: bool,
+        refresh_interval: float,
+    ) -> PromptSession[str]:
         """Create and return the main PromptSession for the application.
 
         Builds an interactive session if self.stdin and self.stdout are TTYs.
@@ -757,19 +777,19 @@ 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,
+            "bottom_toolbar": self.get_bottom_toolbar if enable_bottom_toolbar else None,
             "color_depth": ColorDepth.TRUE_COLOR,
             "complete_style": CompleteStyle.MULTI_COLUMN,
-            "complete_in_thread": self.complete_in_thread,
+            "complete_in_thread": complete_in_thread,
             "complete_while_typing": False,
             "completer": Cmd2Completer(self),
             "history": Cmd2History(item.raw for item in self.history),
             "key_bindings": key_bindings,
             "lexer": Cmd2Lexer(self),
             "multiline": filters.Condition(self._should_continue_multiline),
             "prompt_continuation": self.continuation_prompt,
-            "refresh_interval": self.refresh_interval,
-            "rprompt": self.get_rprompt,
+            "refresh_interval": refresh_interval,
+            "rprompt": self.get_rprompt if enable_rprompt else None,
             "style": DynamicStyle(get_pt_theme),
         }
 
@@ -1984,32 +2004,32 @@ def ppretty(
     def get_bottom_toolbar(self) -> AnyFormattedText:
         """Get the bottom toolbar content.
 
-        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.
+        This method is called by prompt-toolkit while at the main prompt if ``enable_bottom_toolbar``
+        was set to ``True`` during initialization. Because prompt-toolkit executes this callback
+        on every UI refresh (such as on every keypress or timed interval), keeping this function
+        highly optimized is critical to ensuring the CLI remains responsive.
 
         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.
 
-        :return: Content to populate the bottom toolbar, or None to hide it.
+        :return: Content to populate the bottom toolbar.
         """
         return None
 
     def get_rprompt(self) -> AnyFormattedText:
         """Provide text to populate the prompt-toolkit right prompt.
 
-        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.
+        This method is called by prompt-toolkit while at the main prompt if ``enable_rprompt``
+        was set to ``True`` during initialization. Because prompt-toolkit executes this callback
+        on every UI refresh (such as on every keypress or timed interval), keeping this function
+        highly optimized is critical to ensuring the CLI remains responsive.
 
-        Override this if you want a right-prompt displaying contextual information useful for
+        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: Content to populate the right prompt, or None to hide it.
+        :return: Content to populate the right prompt.
         """
         return None
 

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:
 
-- **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
 - **complete_in_thread**: if `True`, then completion will run in a separate thread (Default: `True`)
 - **continuation_prompt**: used for multiline commands on 2nd+ line of input
@@ -42,6 +41,8 @@ Here are instance attributes of `cmd2.Cmd` which developers might wish to overri
 - **disabled_commands**: commands that have been disabled from use. This is to support commands that are only available during specific states of the application. This dictionary's keys are the command names and its values are DisabledCommand objects.
 - **echo**: if `True`, each command the user issues will be repeated to the screen before it is executed. This is particularly useful when running scripts. This behavior does not occur when running a command at the prompt. (Default: `False`)
 - **editor**: text editor program to use with _edit_ command (e.g. `vim`)
+- **enable_bottom_toolbar**: if `True`, enables a bottom toolbar while at the main prompt. (Default: `False`)
+- **enable_rprompt**: if `True`, enables a right prompt while at the main prompt. (Default: `False`)
 - **exclude_from_history**: commands to exclude from the _history_ command
 - **exit_code**: this determines the value returned by `cmdloop()` when exiting the application
 - **help_error**: the error that prints when no help information can be found
@@ -55,6 +56,7 @@ Here are instance attributes of `cmd2.Cmd` which developers might wish to overri
 - **py_bridge_name**: name by which embedded Python environments and scripts refer to the `cmd2` application by in order to call commands (Default: `app`)
 - **py_locals**: dictionary that defines specific variables/functions available in Python shells and scripts (provides more fine-grained control than making everything available with **self_in_py**)
 - **quiet**: if `True`, then completely suppress nonessential output (Default: `False`)
+- **refresh_interval**: how often, in seconds, to automatically refresh the UI. (Default: 0.0)
 - **scripts_add_to_history**: if `True`, scripts and pyscripts add commands to history (Default: `True`)
 - **self_in_py**: if `True`, allow access to your application in _py_ command via `self` (Default: `False`)
 - **settable**: dictionary that controls which of these instance attributes are settable at runtime using the _set_ command

docs/features/prompt.md

@@ -65,10 +65,22 @@ terminal window while the application is idle and waiting for input.
 
 ### Enabling the Toolbar
 
-To enable the toolbar, override the [cmd2.Cmd.get_bottom_toolbar][] method to return the content you
-wish to display.
+To enable the toolbar, set `enable_bottom_toolbar=True` in the [cmd2.Cmd.__init__][] constructor:
 
 ```py
+class App(cmd2.Cmd):
+    def __init__(self):
+        super().__init__(enable_bottom_toolbar=True)
+```
+
+### Customizing Toolbar Content
+
+You can customize the content of the toolbar by overriding the [cmd2.Cmd.get_bottom_toolbar][]
+method.
+
+```py
+    from prompt_toolkit.formatted_text import AnyFormattedText
+
     def get_bottom_toolbar(self) -> AnyFormattedText:
         return [
             ('ansigreen', 'My Application Name'),

docs/upgrades.md

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

examples/getting_started.py

@@ -46,6 +46,8 @@ def __init__(self) -> None:
 
         super().__init__(
             auto_suggest=True,
+            enable_bottom_toolbar=True,
+            enable_rprompt=True,
             include_ipy=True,
             multiline_commands=["echo"],
             persistent_history_file="cmd2_history.dat",

tests/test_cmd2.py

@@ -67,17 +67,14 @@ def test_version(base_app) -> None:
 def test_complete_in_thread() -> None:
     # Test default
     app_default = cmd2.Cmd()
-    assert app_default.complete_in_thread is True
     assert app_default.main_session.complete_in_thread is True
 
     # Test True
     app_true = cmd2.Cmd(complete_in_thread=True)
-    assert app_true.complete_in_thread is True
     assert app_true.main_session.complete_in_thread is True
 
     # Test False
     app_false = cmd2.Cmd(complete_in_thread=False)
-    assert app_false.complete_in_thread is False
     assert app_false.main_session.complete_in_thread is False
 
 
@@ -4229,13 +4226,14 @@ def test_custom_completekey_ctrl_k():
 
 def test_completekey_empty_string() -> None:
     # Test that an empty string for completekey defaults to DEFAULT_COMPLETEKEY
+
     with mock.patch("cmd2.Cmd._create_main_session", autospec=True) as create_session_mock:
         create_session_mock.return_value = mock.MagicMock(spec=PromptSession)
-        app = cmd2.Cmd(completekey="")
 
-        # Verify it was called with DEFAULT_COMPLETEKEY
-        # auto_suggest is the second arg and it defaults to True
-        create_session_mock.assert_called_once_with(app, True, app.DEFAULT_COMPLETEKEY)
+        app = cmd2.Cmd(completekey="")
+        create_session_mock.assert_called_once()
+        _, kwargs = create_session_mock.call_args
+        assert kwargs["completekey"] == app.DEFAULT_COMPLETEKEY
 
 
 def test_create_main_session_exception(monkeypatch):
@@ -4290,12 +4288,40 @@ def test_path_complete_users_windows(monkeypatch, base_app):
 
 def test_refresh_interval() -> None:
     # Test default value
-    default_refresh_app = cmd2.Cmd()
-    assert default_refresh_app.main_session.refresh_interval == 0.0
+    default_app = cmd2.Cmd()
+    assert default_app.main_session.refresh_interval == 0.0
 
     # Test custom value
-    custom_refresh_app = cmd2.Cmd(refresh_interval=5.0)
-    assert custom_refresh_app.main_session.refresh_interval == 5.0
+    custom_app = cmd2.Cmd(refresh_interval=5.0)
+    assert custom_app.main_session.refresh_interval == 5.0
+
+
+def test_enable_bottom_toolbar() -> None:
+    # Test default
+    default_app = cmd2.Cmd()
+    assert default_app.main_session.bottom_toolbar is None
+
+    # Test True
+    custom_app = cmd2.Cmd(enable_bottom_toolbar=True)
+    assert custom_app.main_session.bottom_toolbar == custom_app.get_bottom_toolbar
+
+    # Test False
+    custom_app = cmd2.Cmd(enable_bottom_toolbar=False)
+    assert custom_app.main_session.bottom_toolbar is None
+
+
+def test_enable_rprompt() -> None:
+    # Test default
+    default_app = cmd2.Cmd()
+    assert default_app.main_session.rprompt is None
+
+    # Test True
+    custom_app = cmd2.Cmd(enable_rprompt=True)
+    assert custom_app.main_session.rprompt == custom_app.get_rprompt
+
+    # Test False
+    custom_app = cmd2.Cmd(enable_rprompt=False)
+    assert custom_app.main_session.rprompt is None
 
 
 def test_get_bottom_toolbar(base_app, monkeypatch):
@@ -4377,7 +4403,14 @@ def test_create_main_session_with_custom_tty() -> None:
         app = cmd2.Cmd()
         app.stdin = custom_stdin
         app.stdout = custom_stdout
-        app._create_main_session(auto_suggest=True, completekey=app.DEFAULT_COMPLETEKEY)
+        app._create_main_session(
+            auto_suggest=True,
+            completekey=app.DEFAULT_COMPLETEKEY,
+            enable_bottom_toolbar=False,
+            enable_rprompt=False,
+            complete_in_thread=False,
+            refresh_interval=0.0,
+        )
 
         mock_create_input.assert_called_once_with(stdin=custom_stdin)
         mock_create_output.assert_called_once_with(stdout=custom_stdout)