Initial commit for phase 1 of Rich integration.

Still some work to do on help table formatting.
Unit tests will be fixed after code review.

Author: kmvanbrunt

cmd2/__init__.py

@@ -11,7 +11,10 @@
     # package is not installed
     pass
 
-from . import plugin
+from . import (
+    plugin,
+    rich_utils,
+)
 from .ansi import (
     Bg,
     Cursor,
@@ -101,6 +104,7 @@
     'SkipPostcommandHooks',
     # modules
     'plugin',
+    'rich_utils',
     # Utilities
     'categorize',
     'CompletionMode',

cmd2/ansi.py

@@ -4,7 +4,6 @@
 setting the window title, and asynchronous alerts.
 """
 
-import functools
 import re
 from enum import (
     Enum,
@@ -20,6 +19,8 @@
     wcswidth,
 )
 
+from . import rich_utils
+
 #######################################################
 # Common ANSI escape sequence constants
 #######################################################
@@ -29,38 +30,6 @@
 BEL = '\a'
 
 
-class AllowStyle(Enum):
-    """Values for ``cmd2.ansi.allow_style``"""
-
-    ALWAYS = 'Always'  # Always output ANSI style sequences
-    NEVER = 'Never'  # Remove ANSI style sequences from all output
-    TERMINAL = 'Terminal'  # Remove ANSI style sequences if the output is not going to the terminal
-
-    def __str__(self) -> str:
-        """Return value instead of enum name for printing in cmd2's set command"""
-        return str(self.value)
-
-    def __repr__(self) -> str:
-        """Return quoted value instead of enum description for printing in cmd2's set command"""
-        return repr(self.value)
-
-
-# Controls when ANSI style sequences are allowed in output
-allow_style = AllowStyle.TERMINAL
-"""When using outside of a cmd2 app, set this variable to one of:
-
-- ``AllowStyle.ALWAYS`` - always output ANSI style sequences
-- ``AllowStyle.NEVER`` - remove ANSI style sequences from all output
-- ``AllowStyle.TERMINAL`` - remove ANSI style sequences if the output is not going to the terminal
-
-to control how ANSI style sequences are handled by ``style_aware_write()``.
-
-``style_aware_write()`` is called by cmd2 methods like ``poutput()``, ``perror()``,
-``pwarning()``, etc.
-
-The default is ``AllowStyle.TERMINAL``.
-"""
-
 # Regular expression to match ANSI style sequence
 ANSI_STYLE_RE = re.compile(rf'{ESC}\[[^m]*m')
 
@@ -135,7 +104,9 @@ def style_aware_write(fileobj: IO[str], msg: str) -> None:
     :param fileobj: the file object being written to
     :param msg: the string being written
     """
-    if allow_style == AllowStyle.NEVER or (allow_style == AllowStyle.TERMINAL and not fileobj.isatty()):
+    if rich_utils.allow_style == rich_utils.AllowStyle.NEVER or (
+        rich_utils.allow_style == rich_utils.AllowStyle.TERMINAL and not fileobj.isatty()
+    ):
         msg = strip_style(msg)
     fileobj.write(msg)
 
@@ -1038,19 +1009,6 @@ def style(
     return "".join(map(str, additions)) + str(value) + "".join(map(str, removals))
 
 
-# Default styles for printing strings of various types.
-# These can be altered to suit an application's needs and only need to be a
-# function with the following structure: func(str) -> str
-style_success = functools.partial(style, fg=Fg.GREEN)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify success"""
-
-style_warning = functools.partial(style, fg=Fg.LIGHT_YELLOW)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify a warning"""
-
-style_error = functools.partial(style, fg=Fg.LIGHT_RED)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify an error"""
-
-
 def async_alert_str(*, terminal_columns: int, prompt: str, line: str, cursor_offset: int, alert_msg: str) -> str:
     """Calculate the desired string, including ANSI escape codes, for displaying an asynchronous alert message.
 

cmd2/argparse_custom.py

@@ -246,7 +246,6 @@ def my_completer(self, text, line, begidx, endidx, arg_tokens)
     gettext,
 )
 from typing import (
-    IO,
     TYPE_CHECKING,
     Any,
     Callable,
@@ -265,6 +264,8 @@ def my_completer(self, text, line, begidx, endidx, arg_tokens)
     Group,
     RenderableType,
 )
+from rich.table import Column, Table
+from rich.text import Text
 from rich_argparse import (
     ArgumentDefaultsRichHelpFormatter,
     MetavarTypeRichHelpFormatter,
@@ -274,8 +275,8 @@ def my_completer(self, text, line, begidx, endidx, arg_tokens)
 )
 
 from . import (
-    ansi,
     constants,
+    rich_utils,
 )
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -1053,10 +1054,17 @@ def _SubParsersAction_remove_parser(self: argparse._SubParsersAction, name: str)
 class Cmd2HelpFormatter(RichHelpFormatter):
     """Custom help formatter to configure ordering of help text"""
 
-    # Render markup in usage, help, description, and epilog text.
-    RichHelpFormatter.usage_markup = True
-    RichHelpFormatter.help_markup = True
-    RichHelpFormatter.text_markup = True
+    # Disable automatic highlighting in the help text.
+    highlights = []
+
+    # Disable markup rendering in usage, help, description, and epilog text.
+    # cmd2's built-in commands do not escape opening brackets in their help text
+    # and therefore rely on these settings being False. If you desire to use
+    # markup in your help text, inherit from a Cmd2 help formatter and override
+    # these settings in that child class.
+    usage_markup = False
+    help_markup = False
+    text_markup = False
 
     def _format_usage(
         self,
@@ -1319,24 +1327,23 @@ def __init__(
 
     def __rich__(self) -> Group:
         """Custom rendering logic."""
-        import rich
-
         formatter = self.formatter_creator()
 
-        styled_title = rich.text.Text(
+        styled_title = Text(
             type(formatter).group_name_formatter(f"{self.title}:"),
             style=formatter.styles["argparse.groups"],
         )
 
         # Left pad the text like an argparse argument group does
         left_padding = formatter._indent_increment
-
-        text_table = rich.table.Table(
+        text_table = Table(
+            Column(overflow="fold"),
             box=None,
             show_header=False,
             padding=(0, 0, 0, left_padding),
         )
         text_table.add_row(self.text)
+
         return Group(styled_title, text_table)
 
 
@@ -1413,12 +1420,20 @@ def error(self, message: str) -> NoReturn:
             linum += 1
 
         self.print_usage(sys.stderr)
-        formatted_message = ansi.style_error(formatted_message)
-        self.exit(2, f'{formatted_message}\n\n')
+
+        # Add failure style to message
+        console = self._get_formatter().console
+        with console.capture() as capture:
+            console.print(formatted_message, style=rich_utils.style_failure, crop=False)
+        formatted_message = f"{capture.get()}"
+
+        self.exit(2, f'{formatted_message}\n')
 
     def _get_formatter(self) -> Cmd2HelpFormatter:
-        """Copy of _get_formatter() with a different return type to assist type checkers."""
-        return cast(Cmd2HelpFormatter, super()._get_formatter())
+        """Copy of _get_formatter() with customizations for Cmd2HelpFormatter."""
+        formatter = cast(Cmd2HelpFormatter, super()._get_formatter())
+        formatter.console = rich_utils.Cmd2Console(sys.stdout)
+        return formatter
 
     def format_help(self) -> str:
         """Copy of format_help() from argparse.ArgumentParser with tweaks to separately display required parameters"""
@@ -1474,13 +1489,6 @@ def format_help(self) -> str:
         # determine help from format above
         return formatter.format_help() + '\n'
 
-    def _print_message(self, message: str, file: Optional[IO[str]] = None) -> None:
-        # Override _print_message to use style_aware_write() since we use ANSI escape characters to support color
-        if message:
-            if file is None:
-                file = sys.stderr
-            ansi.style_aware_write(file, message)
-
     def create_text_group(self, title: str, text: RenderableType) -> TextGroup:
         """Create a TextGroup using this parser's formatter creator."""
         return TextGroup(title, text, self._get_formatter)