tessl/pypi-rich-argparse

Rich help formatters for argparse and optparse that enhance CLI help output with colors and formatting

—

Pending

Overview

Eval results

Files

Contrib Formatters

Name: tessl/pypi-rich-argparse
Author: tessl

Additional specialized formatters for advanced formatting needs. The contrib module contains optional, standard implementations of common patterns of rich help message formatting that do not translate directly to standard argparse formatters.

Capabilities

ParagraphRichHelpFormatter

Rich help formatter that retains paragraph separation in help text. Unlike the standard RichHelpFormatter, this formatter preserves paragraph breaks (double newlines) in descriptions, epilogs, and argument help text.

# From rich_argparse.contrib
class ParagraphRichHelpFormatter(RichHelpFormatter):
    """Rich help message formatter which retains paragraph separation."""
    
    def _rich_split_lines(self, text: Text, width: int) -> Lines:
        """
        Split text into lines while preserving paragraph separation.
        
        Args:
            text: Rich Text object to split
            width: Maximum width for line wrapping
            
        Returns:
            Lines object with paragraph separation preserved
        """
    
    def _rich_fill_text(self, text: Text, width: int, indent: Text) -> Text:
        """
        Fill text to specified width while preserving paragraphs.
        
        Args:
            text: Rich Text object to fill
            width: Maximum width for filling
            indent: Indentation to apply to each line
            
        Returns:
            Filled Text object with preserved paragraph structure
        """

Usage Examples

Basic usage with paragraph preservation:

import argparse
from rich_argparse.contrib import ParagraphRichHelpFormatter

parser = argparse.ArgumentParser(
    description="""
    This is the first paragraph of the description.
    It explains the basic purpose of the application.
    
    This is the second paragraph which provides more detailed
    information about advanced features and usage patterns.
    
    The final paragraph contains important notes and warnings
    that users should be aware of.
    """,
    epilog="""
    Additional information paragraph one.
    
    Additional information paragraph two with more details.
    """,
    formatter_class=ParagraphRichHelpFormatter
)

parser.add_argument(
    "--input",
    help="""
    Input file specification.
    
    This argument accepts various file formats including JSON, YAML,
    and plain text files.
    
    Special handling is provided for compressed files.
    """
)

Comparison with standard formatter:

import argparse
from rich_argparse import RichHelpFormatter
from rich_argparse.contrib import ParagraphRichHelpFormatter

# Standard formatter - removes paragraph breaks
parser1 = argparse.ArgumentParser(
    description="""
    First paragraph.
    
    Second paragraph.
    """,
    formatter_class=RichHelpFormatter
)

# Contrib formatter - preserves paragraph breaks  
parser2 = argparse.ArgumentParser(
    description="""
    First paragraph.
    
    Second paragraph.
    """,
    formatter_class=ParagraphRichHelpFormatter
)

When to Use ParagraphRichHelpFormatter

The ParagraphRichHelpFormatter is particularly useful when:

Documentation-heavy CLIs: Applications with extensive help text that benefits from clear paragraph separation
Multi-section help: Help text that logically groups information into distinct paragraphs
Structured descriptions: Applications where the description or epilog contains multiple concepts that should be visually separated
Educational tools: CLIs that include tutorial-like help text with step-by-step explanations

Behavior Differences

Feature	RichHelpFormatter	ParagraphRichHelpFormatter
Single newlines	Converted to spaces	Converted to spaces
Double newlines	Converted to spaces	Preserved as paragraph breaks
Text wrapping	Normal wrapping	Wrapping within paragraphs
Indentation	Standard	Applied to each paragraph
Rich markup	Fully supported	Fully supported
Style customization	All styles available	All styles available

Complete Example

import argparse
from rich_argparse.contrib import ParagraphRichHelpFormatter

# Configure custom styling
ParagraphRichHelpFormatter.styles.update({
    "argparse.text": "dim white",
    "argparse.help": "bright_white"
})

parser = argparse.ArgumentParser(
    prog="document-processor",
    description="""
    Document Processor v2.0
    
    A comprehensive tool for processing various document formats with
    advanced features including format conversion, content extraction,
    and metadata manipulation.
    
    This tool supports batch processing and provides detailed logging
    for troubleshooting and audit purposes.
    
    For more information, visit our documentation website or use the
    --help-extended option.
    """,
    epilog="""
    Examples:
    
    Process a single file:
        document-processor input.pdf --output output.txt
    
    Batch process multiple files:
        document-processor *.pdf --batch --output-dir ./results/
    
    Extract metadata only:
        document-processor input.docx --metadata-only
    """,
    formatter_class=ParagraphRichHelpFormatter
)

parser.add_argument(
    "input", 
    nargs="+", 
    help="""
    Input file(s) to process.
    
    Supports various formats including PDF, DOCX, TXT, and HTML.
    Wildcards are supported for batch processing.
    """
)

parser.add_argument(
    "--output", 
    help="""
    Output file path.
    
    If not specified, output will be written to stdout.
    For batch processing, use --output-dir instead.
    """
)

parser.add_argument(
    "--format", 
    choices=["txt", "html", "json", "xml"],
    default="txt",
    help="""
    Output format specification.
    
    Different formats provide different levels of detail and
    structure preservation.
    
    JSON format includes full metadata and structure information.
    """
)

parser.add_argument(
    "--verbose", 
    action="store_true",
    help="""
    Enable verbose output.
    
    Provides detailed progress information during processing.
    Useful for debugging and monitoring large batch operations.
    """
)

if __name__ == "__main__":
    parser.print_help()

Integration with Other Formatters

The ParagraphRichHelpFormatter can be combined with other argparse formatter features:

import argparse
from rich_argparse.contrib import ParagraphRichHelpFormatter

# Combine with ArgumentDefaultsHelpFormatter behavior
class ParagraphArgumentDefaultsFormatter(
    argparse.ArgumentDefaultsHelpFormatter, 
    ParagraphRichHelpFormatter
):
    """Combines paragraph preservation with default value display."""
    pass

parser = argparse.ArgumentParser(
    formatter_class=ParagraphArgumentDefaultsFormatter
)

parser.add_argument(
    "--timeout", 
    type=int, 
    default=30,
    help="""
    Connection timeout in seconds.
    
    Higher values may be needed for slow network connections.
    Set to 0 to disable timeout.
    """
)

The formatter maintains all the styling and customization capabilities of the base RichHelpFormatter while adding paragraph preservation functionality.

Install with Tessl CLI