cmd2 4.3.0__tar.gz → 4.3.1__tar.gz

{cmd2-4.3.0 → cmd2-4.3.1}/.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.17.0"
+    rev: "v0.17.1"
     hooks:
       - id: ruff-format
         args: [--config=ruff.toml]

{cmd2-4.3.0 → cmd2-4.3.1}/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 4.3.1 (October 24, 2026)
+
+- Bug Fixes
+    - Fixed `@with_annotated` command `--help` output bypassing the application's output stream,
+      leaving redirected help files empty and preventing help from being captured by embedded apps.
+- Enhancements
+    - Added the
+      [textual_tty_embed.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_embed.py)
+      example, which embeds a `cmd2` application in a [Textual](https://textual.textualize.io/)
+      application using [textual-tty](https://github.com/ttygroup/textual-tty). The Textual
+      application shows a realtime status panel beside the `cmd2` application, which can display
+      much richer information than a bottom toolbar. See the
+      [Embedding in Textual](docs/examples/embedding_in_textual.md) documentation for details.
+
 ## 4.3.0 (October 13, 2026)
 
 - Stabilized features

{cmd2-4.3.0 → cmd2-4.3.1}/MANIFEST.in

@@ -5,4 +5,4 @@ recursive-include docs *
 prune .github
 prune build
 exclude .github .gitignore .readthedocs.yaml
-global-exclude htmlcov/** .coverage* __pycache__/** .gitignore
+global-exclude htmlcov/** .coverage* __pycache__/** .gitignore .DS_Store

{cmd2-4.3.0 → cmd2-4.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 4.3.0
+Version: 4.3.1
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT
@@ -55,6 +55,12 @@ completion, command history, scripting, output styling, and much more.
 You can use `cmd2` for a small internal tool and grow the same application into an extensible,
 scriptable interface without replacing the framework or writing the usual CLI boilerplate.
 
+Want a richer visual display than a prompt and toolbar can offer? Your `cmd2` application can run
+inside a terminal pane of a [Textual](https://textual.textualize.io/) application, right next to
+dashboards and panels that show realtime status and other information. See
+[Embedding in Textual](https://cmd2.readthedocs.io/en/latest/examples/embedding_in_textual/) for an
+example.
+
 ## Quick start
 
 Install `cmd2`:

{cmd2-4.3.0 → cmd2-4.3.1}/README.md

@@ -26,6 +26,12 @@ completion, command history, scripting, output styling, and much more.
 You can use `cmd2` for a small internal tool and grow the same application into an extensible,
 scriptable interface without replacing the framework or writing the usual CLI boilerplate.
 
+Want a richer visual display than a prompt and toolbar can offer? Your `cmd2` application can run
+inside a terminal pane of a [Textual](https://textual.textualize.io/) application, right next to
+dashboards and panels that show realtime status and other information. See
+[Embedding in Textual](https://cmd2.readthedocs.io/en/latest/examples/embedding_in_textual/) for an
+example.
+
 ## Quick start
 
 Install `cmd2`:

{cmd2-4.3.0 → cmd2-4.3.1}/cmd2/annotated.py

@@ -3154,28 +3154,29 @@ def with_annotated(
 
         @functools.wraps(command_func)
         def cmd_wrapper(*args: Any, **kwargs: Any) -> _CommandReturn:
-            cmd2_app, statement_arg = _parse_positionals(args)
+            cmd_app, statement_arg = _parse_positionals(args)
             owner = args[0]  # Cmd or CommandSet instance
-            statement, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(
+            statement, parsed_arglist = cmd_app.statement_parser.get_command_arg_list(
                 command_name, statement_arg, preserve_quotes
             )
 
-            arg_parser = cmd2_app.command_parsers.get(cast(BoundCommandFunc[...], cmd_wrapper))
+            arg_parser = cmd_app.command_parsers.get(cast(BoundCommandFunc[...], cmd_wrapper))
             if arg_parser is None:
                 raise ValueError(f"No argument parser found for {command_name}")
 
             if ns_provider is None:
                 namespace = None
             else:
-                provider_self = cmd2_app._resolve_func_self(ns_provider, args[0])
-                namespace = ns_provider(provider_self if provider_self is not None else cmd2_app)
+                provider_self = cmd_app._resolve_func_self(ns_provider, args[0])
+                namespace = ns_provider(provider_self if provider_self is not None else cmd_app)
 
             try:
-                if with_unknown_args:
-                    ns, unknown = arg_parser.parse_known_args(parsed_arglist, namespace)
-                else:
-                    ns = arg_parser.parse_args(parsed_arglist, namespace)
-                    unknown = None
+                with arg_parser.output_to(cmd_app.stdout):
+                    if with_unknown_args:
+                        ns, unknown = arg_parser.parse_known_args(parsed_arglist, namespace)
+                    else:
+                        ns = arg_parser.parse_args(parsed_arglist, namespace)
+                        unknown = None
             except SystemExit as exc:
                 raise Cmd2ArgparseError from exc
 

{cmd2-4.3.0 → cmd2-4.3.1}/cmd2/argparse_utils.py

@@ -768,9 +768,9 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
         self.completer_class = completer_class
 
         # To assist type checkers, recast these to reflect our usage of rich-argparse.
-        self.formatter_class: type[Cmd2HelpFormatter]
-        self.description: HelpContent | None  # type: ignore[assignment]
-        self.epilog: HelpContent | None  # type: ignore[assignment]
+        self.formatter_class: type[Cmd2HelpFormatter]  # ty: ignore[invalid-mutable-override]
+        self.description: HelpContent | None  # type: ignore[assignment]  # ty: ignore[invalid-attribute-override]
+        self.epilog: HelpContent | None  # type: ignore[assignment]  # ty: ignore[invalid-attribute-override]
 
     def print_usage(self, file: IO[str] | None = None) -> None:  # type: ignore[override]  # ty: ignore[invalid-method-override]
         """Override to ensure the formatter is aware of the target file."""

{cmd2-4.3.0 → cmd2-4.3.1}/cmd2.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 4.3.0
+Version: 4.3.1
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT
@@ -55,6 +55,12 @@ completion, command history, scripting, output styling, and much more.
 You can use `cmd2` for a small internal tool and grow the same application into an extensible,
 scriptable interface without replacing the framework or writing the usual CLI boilerplate.
 
+Want a richer visual display than a prompt and toolbar can offer? Your `cmd2` application can run
+inside a terminal pane of a [Textual](https://textual.textualize.io/) application, right next to
+dashboards and panels that show realtime status and other information. See
+[Embedding in Textual](https://cmd2.readthedocs.io/en/latest/examples/embedding_in_textual/) for an
+example.
+
 ## Quick start
 
 Install `cmd2`:

{cmd2-4.3.0 → cmd2-4.3.1}/cmd2.egg-info/SOURCES.txt

@@ -47,7 +47,6 @@ cmd2.egg-info/requires.txt
 cmd2.egg-info/scm_file_list.json
 cmd2.egg-info/scm_version.json
 cmd2.egg-info/top_level.txt
-docs/.DS_Store
 docs/doc_conventions.md
 docs/index.md
 docs/testing.md
@@ -78,6 +77,7 @@ docs/assets/cmd2-logo.png
 docs/assets/cmd2-readme-demo.gif
 docs/assets/getting-started-demo.gif
 docs/examples/alternate_event_loops.md
+docs/examples/embedding_in_textual.md
 docs/examples/examples.md
 docs/examples/getting_started.md
 docs/examples/index.md
@@ -162,6 +162,7 @@ examples/remove_builtin_commands.py
 examples/remove_settable.py
 examples/rich_tables.py
 examples/rich_theme.py
+examples/textual_tty_embed.py
 examples/tmux_launch.sh
 examples/tmux_split.sh
 examples/unicode_commands.py

{cmd2-4.3.0 → cmd2-4.3.1}/cmd2.egg-info/scm_file_list.json

@@ -75,6 +75,7 @@
     "docs/assets/getting-started-demo.gif",
     "docs/doc_conventions.md",
     "docs/examples/alternate_event_loops.md",
+    "docs/examples/embedding_in_textual.md",
     "docs/examples/examples.md",
     "docs/examples/getting_started.md",
     "docs/examples/index.md",
@@ -172,6 +173,7 @@
     "examples/scripts/save_help_text.py",
     "examples/scripts/script.py",
     "examples/scripts/script.txt",
+    "examples/textual_tty_embed.py",
     "examples/tmux_launch.sh",
     "examples/tmux_split.sh",
     "examples/unicode_commands.py",

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

@@ -0,0 +1,8 @@
+{
+  "tag": "4.3.1",
+  "distance": 0,
+  "node": "ge9c64db568404a6ec384f156656768d77a026c04",
+  "dirty": false,
+  "branch": "main",
+  "node_date": "2026-10-24"
+}

cmd2-4.3.1/docs/examples/embedding_in_textual.md

@@ -0,0 +1,120 @@
+# Embedding in Textual
+
+[Textual](https://textual.textualize.io/) builds full-screen terminal user interfaces with widgets,
+layouts, and mouse support, while `cmd2` builds interactive command interpreters. You don't have to
+choose between them. [textual-tty](https://github.com/ttygroup/textual-tty) provides a `Terminal`
+widget for Textual applications, which is a terminal emulator that runs a program attached to a
+pseudo-terminal. That program can be a `cmd2` application, so a Textual application can show a
+`cmd2` application in one pane and, beside it, other widgets which display realtime status and
+situational awareness information. This can be much richer than what fits in a
+[bottom toolbar](../features/prompt.md#bottom-toolbar).
+
+The
+[textual_tty_embed.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_embed.py)
+example shows how to do this. It has a `cmd2` application in a terminal pane on the left. On the
+right, a status panel shows whether the `cmd2` application is idle or running a command, how many
+commands it has run, and how long the last one took, and a clock is updated by Textual on its own.
+
+!!! warning
+
+    textual-tty is still pre-alpha software, so its API may change. The example was written for
+    textual-tty 0.4. Also, on Windows textual-tty can only start a program by name and can't pass
+    it arguments, so the example's Textual application requires a POSIX system such as Linux or
+    macOS.
+
+## Running the Example
+
+Neither Textual nor textual-tty are dependencies of `cmd2`. In a `cmd2` checkout, textual-tty is
+part of the development environment on POSIX systems, so you can run:
+
+```shell
+uv run examples/textual_tty_embed.py
+```
+
+Otherwise, install textual-tty, which also installs Textual, into your own environment:
+
+```shell
+pip install textual-tty
+python examples/textual_tty_embed.py
+```
+
+Use the `quit` command or press ++ctrl+q++ to exit. Pass `--cmd2-only` to run just the `cmd2`
+application in your current terminal, without Textual.
+
+## How It Works
+
+The Textual application runs the `cmd2` application as a child process in a `Terminal` widget. The
+child process is the example script itself, run with `--cmd2-only --report-status`:
+
+```py
+def compose(self) -> ComposeResult:
+    cmd2_command = [sys.executable, __file__, "--cmd2-only", "--report-status"]
+    yield Header()
+    with Horizontal():
+        with Vertical(id="cmd2-pane"):
+            yield Terminal(command=cmd2_command, id="cmd2")
+        with Vertical(id="sidebar"):
+            yield StatusPanel(id="status")
+            yield ClockPanel(id="clock")
+    yield Footer()
+```
+
+Because it is attached to a pseudo-terminal, the `cmd2` application is a completely normal `cmd2`
+application which uses `prompt-toolkit` and doesn't know that it is embedded. Everything typed into
+the focused `Terminal` goes to the `cmd2` application.
+
+To report its state, the `cmd2` application registers a
+[postparsing hook](../features/hooks.md#postparsing-hooks), which runs before each command, and a
+[command finalization hook](../features/hooks.md#command-finalization-hooks), which runs after it.
+Both of them call [cmd2.Cmd.set_window_title][] with a JSON document. The document is prefixed with
+`cmd2-status:` so that the Textual application can tell it apart from other window titles. The
+`Terminal` widget turns each title change into a `Terminal.TitleChanged` message, which the Textual
+application handles to update the status panel:
+
+```py
+def on_terminal_title_changed(self, event: Terminal.TitleChanged) -> None:
+    if not event.title.startswith(STATUS_PREFIX):
+        return
+    with contextlib.suppress(TypeError, ValueError, OverflowError, RecursionError):
+        status = json.loads(event.title.removeprefix(STATUS_PREFIX))
+        if isinstance(status, dict):
+            self.query_one(StatusPanel).apply(status)
+```
+
+Since the status travels through the pseudo-terminal, there are no sockets, files, or threads to
+manage.
+
+## Things to Watch Out For
+
+The example handles several details which are easy to miss when building something similar:
+
+- Command finalization hooks run for every line of input, including blank lines, comments,
+  ++ctrl+c++ at the prompt, and lines with syntax errors. The other hooks only run for lines which
+  were parsed into a statement, so check whether `data.statement` is `None` in a finalization hook.
+- Commands run by other commands, like `run_script`, `history -r`, and `run_pyscript`, go through
+  the hooks too. The example counts the running commands so that only the outermost one is reported.
+- The postparsing hooks stop running as soon as one of them sets `stop` or raises an exception, but
+  the finalization hooks still run. If your application has other postparsing hooks, register the
+  one which counts commands first so that it is never skipped.
+- `prompt-toolkit` buffers its output, so flush it after setting the window title when a command
+  starts. Otherwise the "running" state only reaches the Textual application after the command is
+  done.
+- Any program run in the terminal, for example by the `shell` command, can set the window title.
+  Validate a status document before using it. Besides `json.JSONDecodeError`, `json.loads` raises
+  `ValueError` for integers with too many digits and `RecursionError` for documents which are nested
+  too deeply. Also escape the document's strings with `textual.markup.escape` before putting them in
+  Textual markup.
+- Only report status through the window title when running inside the Textual application. In a
+  normal terminal, it would overwrite the title of the user's window.
+- If the Textual application exits while a command is running, the pseudo-terminal is closed before
+  the finalization hook reports the end of that command, so setting the window title raises
+  `OSError`. The example ignores that error.
+- When the child process exits, `Terminal.ProcessExited.exit_code` holds its exit code, which is the
+  negated signal number if a signal killed it. The example passes the exit code back to the shell,
+  using 128 plus the signal number like a shell does, and when it isn't 0 the example keeps the
+  terminal on the screen so that any traceback can still be read.
+- A `Terminal` sizes its pseudo-terminal from its outer size, so put a border on a container around
+  the `Terminal` rather than on the `Terminal` itself. Otherwise the `cmd2` application draws more
+  rows than are visible and its prompt can end up hidden.
+- The focused `Terminal` sends almost every key press to the `cmd2` application. Textual's built-in
+  ++ctrl+q++ binding to quit is a priority binding, so it still works.

{cmd2-4.3.0 → cmd2-4.3.1}/docs/examples/index.md

@@ -4,6 +4,7 @@
 
 - [Getting Started](getting_started.md)
 - [Alternate Event Loops](alternate_event_loops.md)
+- [Embedding in Textual](embedding_in_textual.md)
 - [List of cmd2 examples](examples.md)
 
 <!--intro-end-->

{cmd2-4.3.0 → cmd2-4.3.1}/docs/features/prompt.md

@@ -106,3 +106,10 @@ class App(cmd2.Cmd):
 See the
 [getting_started.py](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py)
 example for a demonstration of this technique.
+
+!!! tip
+
+    If you want to show more realtime status information than fits in a toolbar, you can run your
+    `cmd2` application inside a [Textual](https://textual.textualize.io/) application, next to
+    widgets which display that information. See
+    [Embedding in Textual](../examples/embedding_in_textual.md).

{cmd2-4.3.0 → cmd2-4.3.1}/docs/overview/alternatives.md

@@ -38,3 +38,9 @@ If you are seeking a visually richer end-user experience and don't mind investin
 time, we would recommend checking out [Textual](https://github.com/Textualize/textual) as this can
 be used to build very sophisticated user interfaces in a terminal that are more akin to feature-rich
 web GUIs.
+
+You don't have to choose between `cmd2` and Textual, though. The
+[textual-tty](https://github.com/ttygroup/textual-tty) package provides a terminal emulator widget
+for Textual, so a `cmd2` application can run inside a Textual application, next to widgets which
+display realtime information about it. See
+[Embedding in Textual](../examples/embedding_in_textual.md) for an example of how to do this.

{cmd2-4.3.0 → cmd2-4.3.1}/examples/README.md

@@ -92,6 +92,11 @@ each:
     - Example of using Rich Tables within a cmd2 application for displaying tabular data
 - [rich_theme.py](https://github.com/python-cmd2/cmd2/blob/main/examples/rich_theme.py)
     - Demonstrates how to create a custom theme for a cmd2 application
+- [textual_tty_embed.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_embed.py)
+    - Shows how to embed a `cmd2` application in a [Textual](https://textual.textualize.io/)
+      application using [textual-tty](https://github.com/ttygroup/textual-tty), with a realtime
+      status panel next to the terminal. Requires a POSIX system such as Linux or macOS and
+      `textual-tty`, which is part of the `cmd2` development environment but not a `cmd2` dependency
 - [tmux_launch.sh](https://github.com/python-cmd2/cmd2/blob/main/examples/tmux_launch.sh)
     - Shell script that launches two applications using tmux in different windows/tabs
 - [tmux_split.sh](https://github.com/python-cmd2/cmd2/blob/main/examples/tmux_split.sh)