0
# Optparse Formatters
1
2
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.
3
4
## Capabilities
5
6
### RichHelpFormatter
7
8
The main optparse formatter class that provides rich, colorful help output. It's the drop-in replacement for optparse.HelpFormatter with customizable styling.
9
10
```python { .api }
11
# From rich_argparse.optparse
12
class RichHelpFormatter(optparse.HelpFormatter):
13
"""An optparse HelpFormatter class that renders using rich."""
14
15
styles: dict[str, StyleType] = {
16
"optparse.args": "cyan",
17
"optparse.groups": "dark_orange",
18
"optparse.help": "default",
19
"optparse.metavar": "dark_cyan",
20
"optparse.syntax": "bold",
21
"optparse.text": "default",
22
"optparse.prog": "grey50",
23
}
24
"""A dict of rich styles to control the formatter styles."""
25
26
highlights: list[str]
27
"""A list of regex patterns to highlight in the help text."""
28
```
29
30
#### Usage Examples
31
32
Basic usage with optparse:
33
34
```python
35
import optparse
36
from rich_argparse.optparse import RichHelpFormatter
37
38
parser = optparse.OptionParser(
39
description="A sample application with rich formatting",
40
formatter=RichHelpFormatter()
41
)
42
43
parser.add_option("--input", help="Input file path")
44
parser.add_option("--verbose", action="store_true", help="Enable verbose output")
45
46
parser.print_help()
47
```
48
49
Custom styling:
50
51
```python
52
import optparse
53
from rich_argparse.optparse import RichHelpFormatter
54
55
# Customize colors
56
formatter = RichHelpFormatter()
57
formatter.styles["optparse.args"] = "bold blue"
58
formatter.styles["optparse.help"] = "dim"
59
60
parser = optparse.OptionParser(formatter=formatter)
61
```
62
63
### IndentedRichHelpFormatter
64
65
Indented version of the optparse RichHelpFormatter, similar to optparse.IndentedHelpFormatter but with rich styling.
66
67
```python { .api }
68
class IndentedRichHelpFormatter(RichHelpFormatter):
69
"""Indented version of optparse RichHelpFormatter."""
70
```
71
72
#### Usage Examples
73
74
```python
75
import optparse
76
from rich_argparse.optparse import IndentedRichHelpFormatter
77
78
parser = optparse.OptionParser(
79
description="Application with indented help formatting",
80
formatter=IndentedRichHelpFormatter()
81
)
82
83
parser.add_option("--config", help="Configuration file path")
84
parser.add_option("--debug", action="store_true", help="Enable debug mode")
85
```
86
87
### TitledRichHelpFormatter
88
89
Titled version of the optparse RichHelpFormatter, similar to optparse.TitledHelpFormatter but with rich styling.
90
91
```python { .api }
92
class TitledRichHelpFormatter(RichHelpFormatter):
93
"""Titled version of optparse RichHelpFormatter."""
94
```
95
96
#### Usage Examples
97
98
```python
99
import optparse
100
from rich_argparse.optparse import TitledRichHelpFormatter
101
102
parser = optparse.OptionParser(
103
description="Application with titled help formatting",
104
formatter=TitledRichHelpFormatter()
105
)
106
107
# Create option groups
108
group = parser.add_option_group("Advanced Options", "Options for advanced users")
109
group.add_option("--advanced-setting", help="Advanced configuration setting")
110
```
111
112
## Constants
113
114
### GENERATE_USAGE
115
116
Special constant for automatic usage generation in optparse, equivalent to optparse's SUPPRESS_USAGE but with automatic generation.
117
118
```python { .api }
119
GENERATE_USAGE: str = "==GENERATE_USAGE=="
120
"""Special value for automatic usage generation in optparse."""
121
```
122
123
#### Usage Examples
124
125
```python
126
import optparse
127
from rich_argparse.optparse import RichHelpFormatter, GENERATE_USAGE
128
129
parser = optparse.OptionParser(
130
description="Application with auto-generated usage",
131
formatter=RichHelpFormatter(),
132
usage=GENERATE_USAGE # Automatically generates usage string
133
)
134
135
parser.add_option("--input", metavar="FILE", help="Input file")
136
parser.add_option("--output", metavar="FILE", help="Output file")
137
```
138
139
## Style Configuration
140
141
### Available Style Keys
142
143
```python { .api }
144
# Style keys for optparse formatters
145
OPTPARSE_STYLE_KEYS = {
146
"optparse.args": "Options (e.g., '--help')",
147
"optparse.groups": "Group names (e.g., 'Options')",
148
"optparse.help": "Option help text (e.g., 'show this help message and exit')",
149
"optparse.metavar": "Meta variables (e.g., 'FILE' in '--file=FILE')",
150
"optparse.prog": "Program name in usage (e.g., 'foo' in 'Usage: foo [options]')",
151
"optparse.syntax": "Highlighted back-tick quoted text (e.g., '`some text`')",
152
"optparse.text": "Descriptions and epilog (e.g., 'A foo program')"
153
}
154
```
155
156
### Highlight Patterns
157
158
The default highlight patterns for optparse formatters are the same as argparse, highlighting command-line options and backtick-quoted text.
159
160
```python { .api }
161
# Default highlight regex patterns (same as argparse)
162
DEFAULT_OPTPARSE_HIGHLIGHTS = [
163
r"`(?P<syntax>[^`]*)`|(?:^|\s)(?P<args>-{1,2}[\w]+[\w-]*)"
164
]
165
```
166
167
## Complete Usage Example
168
169
```python
170
import optparse
171
from rich_argparse.optparse import (
172
IndentedRichHelpFormatter,
173
GENERATE_USAGE
174
)
175
176
# Add custom highlight pattern
177
IndentedRichHelpFormatter.highlights.append(r"(?P<metavar>\bregexes\b)")
178
179
parser = optparse.OptionParser(
180
description="I [link https://pypi.org/project/rich]rich[/]ify optparse help.",
181
formatter=IndentedRichHelpFormatter(),
182
prog="my-optparse-app",
183
epilog=":link: https://github.com/hamdanal/rich-argparse#optparse-support",
184
usage=GENERATE_USAGE,
185
)
186
187
parser.add_option(
188
"--formatter",
189
metavar="rich",
190
help="A piece of :cake: isn't it? :wink:"
191
)
192
193
parser.add_option(
194
"--styles",
195
metavar="yours",
196
help="Not your style? No biggie, change it :sunglasses:"
197
)
198
199
parser.add_option(
200
"--highlights",
201
action="store_true",
202
help=":clap: --highlight :clap: all :clap: the :clap: regexes :clap:",
203
)
204
205
parser.add_option(
206
"--syntax",
207
action="store_true",
208
help="`backquotes` may be bold, but they are :muscle:"
209
)
210
211
parser.add_option(
212
"-s", "--long",
213
metavar="METAVAR",
214
help="That's a lot of metavars for an option!"
215
)
216
217
# Create option group
218
group = parser.add_option_group("Magic", description=":sparkles: :sparkles: :sparkles:")
219
group.add_option(
220
"--treasure",
221
action="store_false",
222
help="Mmm, did you find the --hidden :gem:?"
223
)
224
group.add_option(
225
"--hidden",
226
action="store_false",
227
dest="treasure",
228
help=optparse.SUPPRESS_HELP
229
)
230
231
parser.print_help()
232
```
233
234
## Migration from Standard Optparse
235
236
### Basic Migration
237
238
Replace the standard formatter:
239
240
```python
241
# Before
242
import optparse
243
parser = optparse.OptionParser()
244
245
# After
246
import optparse
247
from rich_argparse.optparse import RichHelpFormatter
248
249
parser = optparse.OptionParser(formatter=RichHelpFormatter())
250
```
251
252
### Importing All Components
253
254
```python
255
from rich_argparse.optparse import (
256
RichHelpFormatter,
257
IndentedRichHelpFormatter,
258
TitledRichHelpFormatter,
259
GENERATE_USAGE
260
)
261
```
262
263
### Compatibility Notes
264
265
- All rich_argparse optparse formatters maintain full compatibility with existing optparse code
266
- Rich markup in descriptions and help text is enabled by default
267
- Console markup can be disabled by setting formatter attributes if needed
268
- The formatters work with all optparse features including option groups, callbacks, and custom actions