Add WrappedColorFormatter to contrib.

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.9.5
+    rev: v0.11.4
     hooks:
       - id: ruff
         args: [--fix]

README.md

@@ -253,6 +253,10 @@ syntax. The following formatters are available:
   description text. Leading and trailing trailing whitespace are stripped similar to
   `RichHelpFormatter`.
 
+* `WrappedColorFormatter`: Extends `ParagraphRichHelpFormatter` to preserve paragraph but also
+  wrap lines reasonably even on wide terminal screens (at most 88 chars width, never less than 40).
+
+
 _More formatters will be added in the future._
 
 ## Django support

rich_argparse/_contrib.py

@@ -4,6 +4,8 @@
 # for internal use only
 from __future__ import annotations
 
+from rich import get_console
+
 import rich_argparse._lazy_rich as r
 from rich_argparse._argparse import RichHelpFormatter
 from rich_argparse._common import rich_strip, rich_wrap
@@ -31,3 +33,27 @@ def _rich_split_lines(self, text: r.Text, width: int) -> r.Lines:
     def _rich_fill_text(self, text: r.Text, width: int, indent: r.Text) -> r.Text:
         lines = self._rich_split_lines(text, width)
         return r.Text("\n").join(indent + line for line in lines) + "\n"
+
+
+WRAPPED_MAX_WIDTH = 88
+WRAPPED_MIN_WIDTH = 40
+
+
+class WrappedColorFormatter(ParagraphRichHelpFormatter):
+    """
+    A colored formatter for argparse that retains paragraphs (unlike default
+    argparse formatters) and also wraps text to console width, which is better
+    for readability in both wide and narrow consoles.
+    """
+
+    def __init__(
+        self,
+        prog: str,
+        indent_increment: int = 2,
+        max_help_position: int = 24,
+        width: int | None = None,
+        console: r.Console | None = None,
+    ) -> None:
+        if not width:
+            width = max(WRAPPED_MIN_WIDTH, min(WRAPPED_MAX_WIDTH, get_console().width))
+        super().__init__(prog, indent_increment, max_help_position, width=width, console=console)

rich_argparse/contrib.py

@@ -9,8 +9,12 @@
 
 from __future__ import annotations
 
-from rich_argparse._contrib import ParagraphRichHelpFormatter
+from rich_argparse._contrib import (
+    ParagraphRichHelpFormatter,
+    WrappedColorFormatter,
+)
 
 __all__ = [
     "ParagraphRichHelpFormatter",
+    "WrappedColorFormatter",
 ]

tests/test_contrib.py

@@ -3,6 +3,7 @@
 from argparse import ArgumentParser
 
 from rich_argparse.contrib import ParagraphRichHelpFormatter
+from rich_argparse.contrib import WrappedColorFormatter
 from tests.helpers import clean_argparse
 
 
@@ -51,3 +52,50 @@ def test_paragraph_rich_help_formatter():
     quick brown fox jumps over the lazy dog.
     """
     assert parser.format_help() == clean_argparse(expected_help_output)
+
+
+def test_wrapped_color_formatter():
+    long_sentence = "The quick brown fox jumps over the lazy dog. " * 3
+    long_paragraphs = [long_sentence] * 2
+    long_text = "\n\n\r\n\t " + "\n\n".join(long_paragraphs) + "\n\n\r\n\t "
+    parser = ArgumentParser(
+        prog="PROG",
+        description=long_text,
+        epilog=long_text,
+        formatter_class=WrappedColorFormatter,
+    )
+    group = parser.add_argument_group("group", description=long_text)
+    group.add_argument("--long", help=long_text)
+
+    expected_help_output = """\
+    Usage: PROG [-h] [--long LONG]
+
+    The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy
+    dog. The quick brown fox jumps over the lazy dog.
+
+    The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy
+    dog. The quick brown fox jumps over the lazy dog.
+
+    Optional Arguments:
+      -h, --help   show this help message and exit
+
+    Group:
+      The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy
+      dog. The quick brown fox jumps over the lazy dog.
+
+      The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy
+      dog. The quick brown fox jumps over the lazy dog.
+
+      --long LONG  The quick brown fox jumps over the lazy dog. The quick brown fox jumps
+                   over the lazy dog. The quick brown fox jumps over the lazy dog.
+
+                   The quick brown fox jumps over the lazy dog. The quick brown fox jumps
+                   over the lazy dog. The quick brown fox jumps over the lazy dog.
+
+    The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy
+    dog. The quick brown fox jumps over the lazy dog.
+
+    The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy
+    dog. The quick brown fox jumps over the lazy dog.
+    """
+    assert parser.format_help() == clean_argparse(expected_help_output)