0
# Rich Argparse
1

2
A comprehensive Python library that provides rich, colorful, and visually appealing help formatters for Python's built-in argparse and optparse modules. It enhances command-line interface (CLI) help output by leveraging the Rich library to add colors, styling, and better formatting to argument help text.
3

4
## Package Information
5

6
- **Package Name**: rich-argparse
7
- **Language**: Python
8
- **Installation**: `pip install rich-argparse`
9
- **Python Support**: 3.8+
10
- **Dependencies**: rich >= 11.0.0
11

12
## Core Imports
13

14
Main argparse formatters:
15

16
```python
17
from rich_argparse import RichHelpFormatter
18
```
19

20
Multiple formatter imports:
21

22
```python
23
from rich_argparse import (
24
    RichHelpFormatter,
25
    RawDescriptionRichHelpFormatter,
26
    RawTextRichHelpFormatter,
27
    ArgumentDefaultsRichHelpFormatter,
28
    MetavarTypeRichHelpFormatter,
29
    HelpPreviewAction
30
)
31
```
32

33
## Basic Usage
34

35
```python
36
import argparse
37
from rich_argparse import RichHelpFormatter
38

39
# Create parser with rich formatting
40
parser = argparse.ArgumentParser(
41
    prog="my-cli",
42
    description="A sample CLI with rich help formatting",
43
    formatter_class=RichHelpFormatter
44
)
45

46
parser.add_argument("--input", help="Input file path")
47
parser.add_argument("--output", help="Output file path")
48
parser.add_argument("--verbose", action="store_true", help="Enable verbose output")
49

50
# Rich-formatted help will be displayed
51
parser.print_help()
52
```
53

54
## Architecture
55

56
Rich-argparse provides drop-in replacements for argparse's standard formatters while maintaining full compatibility with existing argparse code. The library works by:
57

58
- **Style Configuration**: Customizable color schemes through the `styles` class attribute
59
- **Text Highlighting**: Regex-based highlighting for options, syntax, and special patterns
60
- **Markup Support**: Optional rich console markup in descriptions and help text
61
- **Cross-platform**: Automatic handling of Windows console differences and legacy terminal support
62

63
Key components include formatter classes for different argparse behaviors, optparse support for legacy code, Django integration utilities, and specialized formatters for advanced use cases like paragraph-preserving text formatting.
64

65
## Capabilities
66

67
### Argparse Formatters
68

69
Core rich formatting classes that replace argparse's built-in help formatters with enhanced visual output, including customizable colors, syntax highlighting, and rich markup support.
70

71
```python { .api }
72
class RichHelpFormatter(argparse.HelpFormatter):
73
    """Main argparse HelpFormatter class that renders using rich."""
74
    
75
class RawDescriptionRichHelpFormatter(RichHelpFormatter):
76
    """Preserves raw description formatting without text processing."""
77
    
78
class RawTextRichHelpFormatter(RawDescriptionRichHelpFormatter):
79
    """Preserves raw help text formatting for all text elements."""
80
    
81
class ArgumentDefaultsRichHelpFormatter(argparse.ArgumentDefaultsHelpFormatter, RichHelpFormatter):
82
    """Shows default values in argument help text."""
83
    
84
class MetavarTypeRichHelpFormatter(argparse.MetavarTypeHelpFormatter, RichHelpFormatter):
85
    """Uses type names as metavars instead of dest names."""
86
    
87
class HelpPreviewAction(argparse.Action):
88
    """Special action to generate help preview images/SVGs."""
89
```
90

91
[Argparse Formatters](./argparse-formatters.md)
92

93
### Optparse Formatters
94

95
Rich formatting support for Python's optparse module, providing enhanced help output for legacy applications and libraries that still use optparse.
96

97
```python { .api }
98
# From rich_argparse.optparse
99
class RichHelpFormatter(optparse.HelpFormatter):
100
    """Main optparse HelpFormatter class that renders using rich."""
101
    
102
class IndentedRichHelpFormatter(RichHelpFormatter):
103
    """Indented version of optparse RichHelpFormatter."""
104
    
105
class TitledRichHelpFormatter(RichHelpFormatter):
106
    """Titled version of optparse RichHelpFormatter."""
107

108
# Special constant for usage generation
109
GENERATE_USAGE: str
110
```
111

112
[Optparse Formatters](./optparse-formatters.md)
113

114
### Contrib Formatters
115

116
Additional specialized formatters for advanced formatting needs, including paragraph-preserving text formatting and other extended capabilities.
117

118
```python { .api }
119
# From rich_argparse.contrib
120
class ParagraphRichHelpFormatter(RichHelpFormatter):
121
    """Rich help formatter that retains paragraph separation in text."""
122
```
123

124
[Contrib Formatters](./contrib-formatters.md)
125

126
### Django Integration
127

128
Django-specific utilities that enable rich formatting for Django management commands with project-wide configuration support.
129

130
```python { .api }
131
# From rich_argparse.django
132
class DjangoRichHelpFormatter:
133
    """Rich help formatter for Django commands."""
134

135
def richify_command_line_help(formatter_class=DjangoRichHelpFormatter) -> None:
136
    """Set rich default formatter for Django BaseCommand project-wide."""
137
```
138

139
[Django Integration](./django-integration.md)
140

141
## Types
142

143
### Style Configuration
144

145
```python { .api }
146
# Style dictionary structure for RichHelpFormatter
147
StyleDict = dict[str, str | Style]
148

149
# Available style keys for argparse formatters:
150
# - "argparse.args": for positional arguments and options (default: "cyan")
151
# - "argparse.groups": for group names (default: "dark_orange")
152
# - "argparse.help": for argument help text (default: "default")
153
# - "argparse.metavar": for metavariables (default: "dark_cyan")
154
# - "argparse.syntax": for syntax highlights (default: "bold")
155
# - "argparse.text": for descriptions/epilog (default: "default")
156
# - "argparse.prog": for program name (default: "grey50")
157
# - "argparse.default": for default values (default: "italic")
158

159
# Available style keys for optparse formatters:
160
# - "optparse.args": for options (default: "cyan")
161
# - "optparse.groups": for group names (default: "dark_orange")
162
# - "optparse.help": for option help text (default: "default")
163
# - "optparse.metavar": for metavariables (default: "dark_cyan")
164
# - "optparse.syntax": for syntax highlights (default: "bold")
165
# - "optparse.text": for descriptions/epilog (default: "default")
166
# - "optparse.prog": for program name (default: "grey50")
167
```
168

169
### Configuration Options
170

171
```python { .api }
172
# RichHelpFormatter class attributes for customization
173
GroupNameFormatter = Callable[[str], str]  # Function to format group names
174
HighlightPatterns = list[str]  # List of regex patterns for text highlighting
175
```