cmd2 4.0.1__tar.gz → 4.1.1__tar.gz

{cmd2-4.0.1 → cmd2-4.1.1}/.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.17"
+    rev: "v0.15.21"
     hooks:
       - id: ruff-format
         args: [--config=ruff.toml]
@@ -30,7 +30,7 @@ repos:
           - prettier-plugin-toml@2.0.6
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1.47.2
+    rev: v1.48.0
     hooks:
       - id: typos
         exclude: |

{cmd2-4.0.1 → cmd2-4.1.1}/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 4.1.1 (July 9, 2026)
+
+- Bug Fixes
+    - Fixed a couple type issues that emerged with the upgrade to `mypy` 2.2.0
+- Enhancements
+    - Async alert messages can now be Rich renderables.
+
 ## 4.1.0 (July 7, 2026)
 
 - Breaking Changes

{cmd2-4.0.1 → cmd2-4.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 4.0.1
+Version: 4.1.1
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT

{cmd2-4.0.1 → cmd2-4.1.1}/cmd2/argparse_utils.py

@@ -1035,13 +1035,13 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
 
         self.exit(2, f"{formatted_message}\n")
 
-    def _get_formatter(self, **_kwargs: Any) -> Cmd2HelpFormatter:
+    def _get_formatter(self, *_args: Any, **_kwargs: Any) -> Cmd2HelpFormatter:
         """Override with customizations for Cmd2HelpFormatter."""
         return self.formatter_class(prog=self.prog, file=self._thread_locals.current_output_file)
 
-    def format_help(self) -> str:
+    def format_help(self, *args: Any, **kwargs: Any) -> str:
         """Override to add a newline."""
-        return super().format_help() + "\n"
+        return super().format_help(*args, **kwargs) + "\n"
 
     def _get_nargs_pattern(self, action: argparse.Action) -> str:
         """Override to support nargs ranges."""

{cmd2-4.0.1 → cmd2-4.1.1}/cmd2/cmd2.py

@@ -312,7 +312,11 @@ class CommandParsers:
 class AsyncAlert:
     """Contents of an asynchronous alert which display while user is at prompt.
 
-    :param msg: an optional message to be printed above the prompt.
+    :param msg: an optional printable object (including Rich renderables) to be
+                printed above the prompt.
+    :param soft_wrap: Enable soft wrap mode. This only applies with msg is not None.
+                      Defaults to True. See print_to() docstring for more details on
+                      this parameter.
     :param prompt: an optional string to dynamically replace the current prompt.
 
     :ivar timestamp: monotonic creation time of the alert. If an alert was created
@@ -320,7 +324,8 @@ class AsyncAlert:
                      to avoid a stale display, but its msg data will still be displayed.
     """
 
-    msg: str | None = None
+    msg: Any | None = None
+    soft_wrap: bool = True
     prompt: str | None = None
     timestamp: float = field(default_factory=time.monotonic, init=False)
 
@@ -1572,7 +1577,7 @@ class Cmd:
                           If False, Rich wraps text to fit the terminal width.
                           Set this to False when printing structured Renderables like
                           Tables, Panels, or Columns to ensure they render as expected.
-                          For example, when soft_wrap is True Panels truncate text
+                          For example, when soft_wrap is True, Panels truncate text
                           which is wider than the terminal.
         :param justify: justify method ("left", "center", "right", "full"). Defaults to None.
         :param emoji: If True, Rich will replace emoji codes (e.g., :smiley:) with their
@@ -3657,7 +3662,19 @@ class Cmd:
                 # prevents async alerts from printing once a command starts.
 
                 # Print all alerts at once to reduce flicker.
-                alert_text = "\n".join(alert.msg for alert in self._alert_queue if alert.msg)
+                console = self._get_core_print_console(
+                    file=self.stdout,
+                    emoji=False,
+                    markup=False,
+                    highlight=False,
+                )
+
+                with console.capture() as capture:
+                    for alert in self._alert_queue:
+                        if alert.msg is not None:
+                            console.print(alert.msg, soft_wrap=alert.soft_wrap)
+
+                alert_text = capture.get()
 
                 # Find the latest prompt update among all pending alerts.
                 latest_prompt = None
@@ -3681,7 +3698,7 @@ class Cmd:
                 if alert_text:
                     # Print the alert messages above the prompt.
                     with patch_stdout():
-                        print_formatted_text(pt_filter_style(alert_text))
+                        print_formatted_text(ANSI(alert_text), end="")
 
                 elif latest_prompt is not None:
                     # Refresh UI immediately to show the new prompt
@@ -5616,7 +5633,13 @@ class Cmd:
         # self.last_result will be set by do_run_script()
         return self.do_run_script(su.quote(relative_path))
 
-    def add_alert(self, *, msg: str | None = None, prompt: str | None = None) -> None:
+    def add_alert(
+        self,
+        *,
+        msg: Any | None = None,
+        soft_wrap: bool = True,
+        prompt: str | None = None,
+    ) -> None:
         """Queue an asynchronous alert to be displayed when the prompt is active.
 
         Examples:
@@ -5624,7 +5647,11 @@ class Cmd:
             add_alert(prompt="user@host> ")       # Update prompt only
             add_alert(msg="Done", prompt="> ")    # Update both
 
-        :param msg: an optional message to be printed above the prompt.
+        :param msg: an optional printable object (including Rich renderables) to be
+                    printed above the prompt.
+        :param soft_wrap: Enable soft wrap mode. This only applies with msg is not None.
+                          Defaults to True. See print_to() docstring for more details on
+                          this parameter.
         :param prompt: an optional string to dynamically replace the current prompt.
 
         """
@@ -5632,7 +5659,7 @@ class Cmd:
             return
 
         with self._alert_condition:
-            alert = AsyncAlert(msg=msg, prompt=prompt)
+            alert = AsyncAlert(msg=msg, soft_wrap=soft_wrap, prompt=prompt)
             self._alert_queue.append(alert)
             self._alert_condition.notify_all()
 

{cmd2-4.0.1 → cmd2-4.1.1}/cmd2.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 4.0.1
+Version: 4.1.1
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT

cmd2-4.1.1/cmd2.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "4.1.1",
+  "distance": 0,
+  "node": "gb4d6cbbc607a8333ba538b765499e98eefa8e9a7",
+  "dirty": false,
+  "branch": "main",
+  "node_date": "2026-07-09"
+}

cmd2-4.1.1/examples/async_printing.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python
+"""A simple example demonstrating an application that asynchronously prints alerts,
+updates the prompt, and changes the window title.
+"""
+
+import secrets
+import threading
+import time
+from typing import Any
+
+from rich.console import Group
+from rich.panel import Panel
+from rich.style import Style
+from rich.table import Table
+from rich.text import Text
+
+import cmd2
+from cmd2 import (
+    Color,
+    stylize,
+)
+
+
+def get_alerts() -> list[tuple[Any, bool]]:
+    """Return a list of (alert_msg, soft_wrap) tuples."""
+    table = Table("Command", "Description", title="Quick Help")
+    table.add_row("start_alerts", "Start the async alert generator")
+    table.add_row("stop_alerts", "Stop the async alert generator")
+    table.add_row("help", "Show help menu")
+
+    # Set soft_wrap to False when printing structured Renderables like Tables, Panels, or Columns
+    # to ensure they render as expected. For example, when soft_wrap is True, Panels truncate
+    # text which is wider than the terminal.
+    return [
+        (
+            Text(
+                "Watch as this application prints alerts asynchronously!",
+                style=Style(
+                    color=Color.BRIGHT_CYAN,
+                    bold=True,
+                ),
+            ),
+            True,
+        ),
+        ("Notice how alerts don't interfere with your typing or cursor location.", True),
+        (
+            Panel(
+                "This message is wrapped in a Rich Panel!",
+                title="System Alert",
+                border_style=Color.BRIGHT_BLUE,
+                expand=False,
+            ),
+            False,
+        ),
+        (table, False),
+        ("You can stop and start the alerts by typing stop_alerts and start_alerts.", True),
+    ]
+
+
+class AlerterApp(cmd2.Cmd):
+    """An app that shows off add_alert() and set_window_title()."""
+
+    def __init__(self) -> None:
+        """Initialize AlerterApp."""
+        super().__init__()
+
+        self.prompt = "(APR)> "
+
+        # The thread that will asynchronously alert the user of events
+        self._stop_event = threading.Event()
+        self._add_alert_thread = threading.Thread()
+        self._alert_count = 0
+
+        # Create some hooks to handle the starting and stopping of our thread
+        self.register_preloop_hook(self._preloop_hook)
+        self.register_postloop_hook(self._postloop_hook)
+
+        # Create an instance of SystemRandom
+        self._secure_generator = secrets.SystemRandom()
+
+    def _preloop_hook(self) -> None:
+        """Start the alerter thread."""
+        self._stop_event.clear()
+        self._add_alert_thread = threading.Thread(name="alerter", target=self._add_alerts_func)
+        self._add_alert_thread.start()
+
+    def _postloop_hook(self) -> None:
+        """Stop the alerter thread."""
+        self._stop_event.set()
+        if self._add_alert_thread.is_alive():
+            self._add_alert_thread.join()
+
+    def do_start_alerts(self, _: cmd2.Statement) -> None:
+        """Start the alerter thread."""
+        if self._add_alert_thread.is_alive():
+            print("The alert thread is already started")
+        else:
+            self._stop_event.clear()
+            self._add_alert_thread = threading.Thread(name="alerter", target=self._add_alerts_func)
+            self._add_alert_thread.start()
+
+    def do_stop_alerts(self, _: cmd2.Statement) -> None:
+        """Stop the alerter thread."""
+        self._stop_event.set()
+        if self._add_alert_thread.is_alive():
+            self._add_alert_thread.join()
+        else:
+            print("The alert thread is already stopped")
+
+    def _build_colored_prompt(self) -> str:
+        """Randomly build a colored prompt.
+
+        :return: the new prompt.
+        """
+        rand_num = self._secure_generator.randint(1, 6)
+
+        status_color = Color.DEFAULT
+
+        if rand_num == 1:
+            status_color = Color.BRIGHT_RED
+        elif rand_num == 2:
+            status_color = Color.BRIGHT_YELLOW
+        elif rand_num == 3:
+            status_color = Color.CYAN
+        elif rand_num == 4:
+            status_color = Color.BRIGHT_GREEN
+        elif rand_num == 5:
+            status_color = Color.BRIGHT_BLUE
+
+        return stylize(self.visible_prompt, style=status_color)
+
+    def _add_alerts_func(self) -> None:
+        """Print alerts and update the prompt any time the prompt is showing."""
+        self._alert_count = 0
+
+        alerts = get_alerts()
+        alert_index = 0
+        last_alert_time = 0.0
+
+        while not self._stop_event.is_set():
+            cur_time = time.monotonic()
+            alert_msg = None
+            soft_wrap = True
+
+            # Trigger the next alert every 4 seconds
+            if cur_time - last_alert_time >= 4.0:
+                alert_msg, soft_wrap = alerts[alert_index]
+                alert_index = (alert_index + 1) % len(alerts)
+                self._alert_count += 1
+                last_alert_time = cur_time
+
+            # Build a new prompt (color changes randomly)
+            new_prompt = self._build_colored_prompt()
+
+            # Check if we have an alert to print
+            if alert_msg is not None:
+                # Wrap the alert message and an empty string in a Rich Group.
+                # This is a clean way to append a blank line after any RenderableType
+                # (strings, panels, tables, etc.) for visual separation.
+                self.add_alert(
+                    msg=Group(alert_msg, ""),
+                    soft_wrap=soft_wrap,
+                    prompt=new_prompt,
+                )
+
+                new_title = f"Alerts Printed: {self._alert_count}"
+                self.set_window_title(new_title)
+
+            # Otherwise, check if the prompt needs to be updated or refreshed
+            elif self.prompt != new_prompt:
+                self.add_alert(prompt=new_prompt)
+
+            self._stop_event.wait(1.0)
+
+
+if __name__ == "__main__":
+    import sys
+
+    app = AlerterApp()
+    app.set_window_title("Asynchronous Printer Test")
+    sys.exit(app.cmdloop())

{cmd2-4.0.1 → cmd2-4.1.1}/tests/test_cmd2.py

@@ -1258,7 +1258,7 @@ def test_ctrl_d_at_prompt(say_app, monkeypatch) -> None:
         (None, "", False),
     ],
 )
-def test_async_alert(base_app, msg, prompt, is_stale) -> None:
+def test_async_alert(base_app: cmd2.Cmd, msg: str, prompt: str, is_stale: bool) -> None:
     import time
 
     with (
@@ -1311,18 +1311,82 @@ def test_async_alert(base_app, msg, prompt, is_stale) -> None:
                     assert base_app.prompt == prompt
 
 
-def test_add_alert(base_app) -> None:
-    orig_num_alerts = len(base_app._alert_queue)
+@pytest.mark.skipif(
+    sys.platform.startswith("win"),
+    reason="Don't have a real Windows console with how we are currently running tests in GitHub Actions",
+)
+def test_async_alert_rich(base_app: cmd2.Cmd) -> None:
+    from prompt_toolkit.formatted_text import ANSI
+    from rich.table import Table
+
+    table = Table("Header")
+    table.add_row("Value")
+
+    with (
+        mock.patch("cmd2.cmd2.print_formatted_text") as mock_print,
+        mock.patch("cmd2.cmd2.get_app") as mock_get_app,
+    ):
+        mock_app = mock.MagicMock()
+        mock_get_app.return_value = mock_app
+
+        # Add alert with a Rich table
+        base_app.add_alert(msg=table, soft_wrap=False)
+
+        with create_pipe_input() as pipe_input:
+            base_app.main_session = PromptSession(
+                input=pipe_input,
+                output=DummyOutput(),
+                history=base_app.main_session.history,
+                completer=base_app.main_session.completer,
+            )
+            pipe_input.send_text("quit\n")
+            base_app._cmdloop()
+
+            # Verify that print_formatted_text was called with a formatted ANSI object
+            assert mock_print.called
+            args, _kwargs = mock_print.call_args
+            printed_arg = args[0]
+            assert isinstance(printed_arg, ANSI)
+
+            # The printed text should contain our table values
+            assert "Header" in printed_arg.value
+            assert "Value" in printed_arg.value
+
+
+def test_add_alert(base_app: cmd2.Cmd) -> None:
+    base_app._alert_queue.clear()
 
     # Nothing is added when both are None
     base_app.add_alert(msg=None, prompt=None)
-    assert len(base_app._alert_queue) == orig_num_alerts
+    assert not base_app._alert_queue
 
-    # Now test valid alert arguments
+    # Test that soft_wrap defaults to True
     base_app.add_alert(msg="Hello", prompt=None)
-    base_app.add_alert(msg="Hello", prompt="prompt> ")
+    last_alert = base_app._alert_queue[-1]
+    assert last_alert.msg == "Hello"
+    assert last_alert.soft_wrap is True
+    assert last_alert.prompt is None
+
+    # Test that soft_wrap can be set to True
+    base_app.add_alert(msg="Hello", soft_wrap=True, prompt=None)
+    last_alert = base_app._alert_queue[-1]
+    assert last_alert.msg == "Hello"
+    assert last_alert.soft_wrap is True
+    assert last_alert.prompt is None
+
+    # Test that soft_wrap can be set to False
+    base_app.add_alert(msg="Hello", soft_wrap=False, prompt=None)
+    last_alert = base_app._alert_queue[-1]
+    assert last_alert.msg == "Hello"
+    assert last_alert.soft_wrap is False
+    assert last_alert.prompt is None
+
+    # Test only prompt
     base_app.add_alert(msg=None, prompt="prompt> ")
-    assert len(base_app._alert_queue) == orig_num_alerts + 3
+    last_alert = base_app._alert_queue[-1]
+    assert last_alert.msg is None
+    assert last_alert.soft_wrap is True
+    assert last_alert.prompt == "prompt> "
 
 
 def test_visible_prompt() -> None:

cmd2-4.0.1/cmd2.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "4.0.1",
-  "distance": 0,
-  "node": "gaca7d06e65b6a08bb7290b2531fb612b95ee26c2",
-  "dirty": false,
-  "branch": "main",
-  "node_date": "2026-07-07"
-}

cmd2-4.0.1/examples/async_printing.py

@@ -1,182 +0,0 @@
-#!/usr/bin/env python
-"""A simple example demonstrating an application that asynchronously prints alerts, updates the prompt
-and changes the window title.
-"""
-
-import secrets
-import threading
-import time
-
-import cmd2
-from cmd2 import (
-    Color,
-    stylize,
-)
-
-ALERTS = [
-    "Watch as this application prints alerts and updates the prompt",
-    "This will only happen when the prompt is present",
-    "Notice how it doesn't interfere with your typing or cursor location",
-    "Go ahead and type some stuff and move the cursor throughout the line",
-    "Keep typing...",
-    "Move that cursor...",
-    "Pretty seamless, eh?",
-    "Feedback can also be given in the window title. Notice the alert count up there?",
-    "You can stop and start the alerts by typing stop_alerts and start_alerts",
-    "This demo will now continue to print alerts at random intervals",
-]
-
-
-class AlerterApp(cmd2.Cmd):
-    """An app that shows off async_alert() and async_update_prompt()."""
-
-    def __init__(self) -> None:
-        """Initializer."""
-        super().__init__()
-
-        self.prompt = "(APR)> "
-
-        # The thread that will asynchronously alert the user of events
-        self._stop_event = threading.Event()
-        self._add_alert_thread = threading.Thread()
-        self._alert_count = 0
-        self._next_alert_time = 0.0
-
-        # Create some hooks to handle the starting and stopping of our thread
-        self.register_preloop_hook(self._preloop_hook)
-        self.register_postloop_hook(self._postloop_hook)
-
-        # Create an instance of SystemRandom
-        self._secure_generator = secrets.SystemRandom()
-
-    def _preloop_hook(self) -> None:
-        """Start the alerter thread."""
-        self._stop_event.clear()
-        self._add_alert_thread = threading.Thread(name="alerter", target=self._add_alerts_func)
-        self._add_alert_thread.start()
-
-    def _postloop_hook(self) -> None:
-        """Stops the alerter thread."""
-        self._stop_event.set()
-        if self._add_alert_thread.is_alive():
-            self._add_alert_thread.join()
-
-    def do_start_alerts(self, _: cmd2.Statement) -> None:
-        """Starts the alerter thread."""
-        if self._add_alert_thread.is_alive():
-            print("The alert thread is already started")
-        else:
-            self._stop_event.clear()
-            self._add_alert_thread = threading.Thread(name="alerter", target=self._add_alerts_func)
-            self._add_alert_thread.start()
-
-    def do_stop_alerts(self, _: cmd2.Statement) -> None:
-        """Stops the alerter thread."""
-        self._stop_event.set()
-        if self._add_alert_thread.is_alive():
-            self._add_alert_thread.join()
-        else:
-            print("The alert thread is already stopped")
-
-    def _get_alerts(self) -> list[str]:
-        """Reports alerts
-        :return: the list of alerts.
-        """
-        cur_time = time.monotonic()
-        if cur_time < self._next_alert_time:
-            return []
-
-        alerts = []
-
-        if self._alert_count < len(ALERTS):
-            alerts.append(ALERTS[self._alert_count])
-            self._alert_count += 1
-            self._next_alert_time = cur_time + 4
-
-        else:
-            rand_num = self._secure_generator.randint(1, 20)
-            if rand_num > 2:
-                return []
-
-            for _ in range(rand_num):
-                self._alert_count += 1
-                alerts.append(f"Alert {self._alert_count}")
-
-            self._next_alert_time = 0
-
-        return alerts
-
-    def _build_alert_str(self) -> str:
-        """Combines alerts into one string that can be printed to the terminal
-        :return: the alert string.
-        """
-        alert_str = ""
-        alerts = self._get_alerts()
-
-        longest_alert = max(ALERTS, key=len)
-        num_asterisks = len(longest_alert) + 8
-
-        for i, cur_alert in enumerate(alerts):
-            # Use padding to center the alert
-            padding = " " * int((num_asterisks - len(cur_alert)) / 2)
-
-            if i > 0:
-                alert_str += "\n"
-            alert_str += "*" * num_asterisks + "\n"
-            alert_str += padding + cur_alert + padding + "\n"
-            alert_str += "*" * num_asterisks + "\n"
-
-        return alert_str
-
-    def _build_colored_prompt(self) -> str:
-        """Randomly builds a colored prompt
-        :return: the new prompt.
-        """
-        rand_num = self._secure_generator.randint(1, 6)
-
-        status_color = Color.DEFAULT
-
-        if rand_num == 1:
-            status_color = Color.BRIGHT_RED
-        elif rand_num == 2:
-            status_color = Color.BRIGHT_YELLOW
-        elif rand_num == 3:
-            status_color = Color.CYAN
-        elif rand_num == 4:
-            status_color = Color.BRIGHT_GREEN
-        elif rand_num == 5:
-            status_color = Color.BRIGHT_BLUE
-
-        return stylize(self.visible_prompt, style=status_color)
-
-    def _add_alerts_func(self) -> None:
-        """Prints alerts and updates the prompt any time the prompt is showing."""
-        self._alert_count = 0
-        self._next_alert_time = 0
-
-        while not self._stop_event.is_set():
-            # Get any alerts that need to be printed
-            alert_str = self._build_alert_str()
-
-            # Build a new prompt
-            new_prompt = self._build_colored_prompt()
-
-            # Check if we have alerts to print
-            if alert_str:
-                self.add_alert(msg=alert_str, prompt=new_prompt)
-                new_title = f"Alerts Printed: {self._alert_count}"
-                self.set_window_title(new_title)
-
-            # Otherwise check if the prompt needs to be updated or refreshed
-            elif self.prompt != new_prompt:
-                self.add_alert(prompt=new_prompt)
-
-            self._stop_event.wait(0.5)
-
-
-if __name__ == "__main__":
-    import sys
-
-    app = AlerterApp()
-    app.set_window_title("Asynchronous Printer Test")
-    sys.exit(app.cmdloop())