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

Optparse Formatters

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

Rich formatting support for Python's optparse module, providing enhanced help output for legacy applications and libraries that still use optparse. These formatters maintain compatibility with optparse while adding rich visual enhancements.

Capabilities

RichHelpFormatter

The main optparse formatter class that provides rich, colorful help output. It's the drop-in replacement for optparse.HelpFormatter with customizable styling.

# From rich_argparse.optparse
class RichHelpFormatter(optparse.HelpFormatter):
    """An optparse HelpFormatter class that renders using rich."""
    
    styles: dict[str, StyleType] = {
        "optparse.args": "cyan",
        "optparse.groups": "dark_orange",
        "optparse.help": "default", 
        "optparse.metavar": "dark_cyan",
        "optparse.syntax": "bold",
        "optparse.text": "default",
        "optparse.prog": "grey50",
    }
    """A dict of rich styles to control the formatter styles."""
    
    highlights: list[str]
    """A list of regex patterns to highlight in the help text."""

Usage Examples

Basic usage with optparse:

import optparse
from rich_argparse.optparse import RichHelpFormatter

parser = optparse.OptionParser(
    description="A sample application with rich formatting",
    formatter=RichHelpFormatter()
)

parser.add_option("--input", help="Input file path")
parser.add_option("--verbose", action="store_true", help="Enable verbose output")

parser.print_help()

Custom styling:

import optparse
from rich_argparse.optparse import RichHelpFormatter

# Customize colors
formatter = RichHelpFormatter()
formatter.styles["optparse.args"] = "bold blue"
formatter.styles["optparse.help"] = "dim"

parser = optparse.OptionParser(formatter=formatter)

IndentedRichHelpFormatter

Indented version of the optparse RichHelpFormatter, similar to optparse.IndentedHelpFormatter but with rich styling.

class IndentedRichHelpFormatter(RichHelpFormatter):
    """Indented version of optparse RichHelpFormatter."""

Usage Examples

import optparse
from rich_argparse.optparse import IndentedRichHelpFormatter

parser = optparse.OptionParser(
    description="Application with indented help formatting",
    formatter=IndentedRichHelpFormatter()
)

parser.add_option("--config", help="Configuration file path")
parser.add_option("--debug", action="store_true", help="Enable debug mode")

TitledRichHelpFormatter

Titled version of the optparse RichHelpFormatter, similar to optparse.TitledHelpFormatter but with rich styling.

class TitledRichHelpFormatter(RichHelpFormatter):
    """Titled version of optparse RichHelpFormatter."""

Usage Examples

import optparse
from rich_argparse.optparse import TitledRichHelpFormatter

parser = optparse.OptionParser(
    description="Application with titled help formatting", 
    formatter=TitledRichHelpFormatter()
)

# Create option groups
group = parser.add_option_group("Advanced Options", "Options for advanced users")
group.add_option("--advanced-setting", help="Advanced configuration setting")

Constants

GENERATE_USAGE

Special constant for automatic usage generation in optparse, equivalent to optparse's SUPPRESS_USAGE but with automatic generation.

GENERATE_USAGE: str = "==GENERATE_USAGE=="
"""Special value for automatic usage generation in optparse."""

Usage Examples

import optparse
from rich_argparse.optparse import RichHelpFormatter, GENERATE_USAGE

parser = optparse.OptionParser(
    description="Application with auto-generated usage",
    formatter=RichHelpFormatter(),
    usage=GENERATE_USAGE  # Automatically generates usage string
)

parser.add_option("--input", metavar="FILE", help="Input file")
parser.add_option("--output", metavar="FILE", help="Output file")

Style Configuration

Available Style Keys

# Style keys for optparse formatters
OPTPARSE_STYLE_KEYS = {
    "optparse.args": "Options (e.g., '--help')",
    "optparse.groups": "Group names (e.g., 'Options')",
    "optparse.help": "Option help text (e.g., 'show this help message and exit')",
    "optparse.metavar": "Meta variables (e.g., 'FILE' in '--file=FILE')",
    "optparse.prog": "Program name in usage (e.g., 'foo' in 'Usage: foo [options]')",
    "optparse.syntax": "Highlighted back-tick quoted text (e.g., '`some text`')",
    "optparse.text": "Descriptions and epilog (e.g., 'A foo program')"
}

Highlight Patterns

The default highlight patterns for optparse formatters are the same as argparse, highlighting command-line options and backtick-quoted text.

# Default highlight regex patterns (same as argparse)
DEFAULT_OPTPARSE_HIGHLIGHTS = [
    r"`(?P<syntax>[^`]*)`|(?:^|\s)(?P<args>-{1,2}[\w]+[\w-]*)"
]

Complete Usage Example

import optparse
from rich_argparse.optparse import (
    IndentedRichHelpFormatter,
    GENERATE_USAGE
)

# Add custom highlight pattern
IndentedRichHelpFormatter.highlights.append(r"(?P<metavar>\bregexes\b)")

parser = optparse.OptionParser(
    description="I [link https://pypi.org/project/rich]rich[/]ify optparse help.",
    formatter=IndentedRichHelpFormatter(),
    prog="my-optparse-app",
    epilog=":link: https://github.com/hamdanal/rich-argparse#optparse-support",
    usage=GENERATE_USAGE,
)

parser.add_option(
    "--formatter", 
    metavar="rich", 
    help="A piece of :cake: isn't it? :wink:"
)

parser.add_option(
    "--styles", 
    metavar="yours", 
    help="Not your style? No biggie, change it :sunglasses:"
)

parser.add_option(
    "--highlights",
    action="store_true",
    help=":clap: --highlight :clap: all :clap: the :clap: regexes :clap:",
)

parser.add_option(
    "--syntax", 
    action="store_true", 
    help="`backquotes` may be bold, but they are :muscle:"
)

parser.add_option(
    "-s", "--long", 
    metavar="METAVAR", 
    help="That's a lot of metavars for an option!"
)

# Create option group
group = parser.add_option_group("Magic", description=":sparkles: :sparkles: :sparkles:")
group.add_option(
    "--treasure", 
    action="store_false", 
    help="Mmm, did you find the --hidden :gem:?"
)
group.add_option(
    "--hidden", 
    action="store_false", 
    dest="treasure", 
    help=optparse.SUPPRESS_HELP
)

parser.print_help()

Migration from Standard Optparse

Basic Migration

Replace the standard formatter:

# Before
import optparse
parser = optparse.OptionParser()

# After  
import optparse
from rich_argparse.optparse import RichHelpFormatter

parser = optparse.OptionParser(formatter=RichHelpFormatter())

Importing All Components

from rich_argparse.optparse import (
    RichHelpFormatter,
    IndentedRichHelpFormatter, 
    TitledRichHelpFormatter,
    GENERATE_USAGE
)

Compatibility Notes

All rich_argparse optparse formatters maintain full compatibility with existing optparse code
Rich markup in descriptions and help text is enabled by default
Console markup can be disabled by setting formatter attributes if needed
The formatters work with all optparse features including option groups, callbacks, and custom actions

Install with Tessl CLI