0
# Contrib Formatters
1

2
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.
3

4
## Capabilities
5

6
### ParagraphRichHelpFormatter
7

8
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.
9

10
```python { .api }
11
# From rich_argparse.contrib
12
class ParagraphRichHelpFormatter(RichHelpFormatter):
13
    """Rich help message formatter which retains paragraph separation."""
14
    
15
    def _rich_split_lines(self, text: Text, width: int) -> Lines:
16
        """
17
        Split text into lines while preserving paragraph separation.
18
        
19
        Args:
20
            text: Rich Text object to split
21
            width: Maximum width for line wrapping
22
            
23
        Returns:
24
            Lines object with paragraph separation preserved
25
        """
26
    
27
    def _rich_fill_text(self, text: Text, width: int, indent: Text) -> Text:
28
        """
29
        Fill text to specified width while preserving paragraphs.
30
        
31
        Args:
32
            text: Rich Text object to fill
33
            width: Maximum width for filling
34
            indent: Indentation to apply to each line
35
            
36
        Returns:
37
            Filled Text object with preserved paragraph structure
38
        """
39
```
40

41
#### Usage Examples
42

43
Basic usage with paragraph preservation:
44

45
```python
46
import argparse
47
from rich_argparse.contrib import ParagraphRichHelpFormatter
48

49
parser = argparse.ArgumentParser(
50
    description="""
51
    This is the first paragraph of the description.
52
    It explains the basic purpose of the application.
53
    
54
    This is the second paragraph which provides more detailed
55
    information about advanced features and usage patterns.
56
    
57
    The final paragraph contains important notes and warnings
58
    that users should be aware of.
59
    """,
60
    epilog="""
61
    Additional information paragraph one.
62
    
63
    Additional information paragraph two with more details.
64
    """,
65
    formatter_class=ParagraphRichHelpFormatter
66
)
67

68
parser.add_argument(
69
    "--input",
70
    help="""
71
    Input file specification.
72
    
73
    This argument accepts various file formats including JSON, YAML,
74
    and plain text files.
75
    
76
    Special handling is provided for compressed files.
77
    """
78
)
79
```
80

81
Comparison with standard formatter:
82

83
```python
84
import argparse
85
from rich_argparse import RichHelpFormatter
86
from rich_argparse.contrib import ParagraphRichHelpFormatter
87

88
# Standard formatter - removes paragraph breaks
89
parser1 = argparse.ArgumentParser(
90
    description="""
91
    First paragraph.
92
    
93
    Second paragraph.
94
    """,
95
    formatter_class=RichHelpFormatter
96
)
97

98
# Contrib formatter - preserves paragraph breaks  
99
parser2 = argparse.ArgumentParser(
100
    description="""
101
    First paragraph.
102
    
103
    Second paragraph.
104
    """,
105
    formatter_class=ParagraphRichHelpFormatter
106
)
107
```
108

109
#### When to Use ParagraphRichHelpFormatter
110

111
The ParagraphRichHelpFormatter is particularly useful when:
112

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

118
#### Behavior Differences
119

120
| Feature | RichHelpFormatter | ParagraphRichHelpFormatter |
121
|---------|-------------------|---------------------------|
122
| Single newlines | Converted to spaces | Converted to spaces |
123
| Double newlines | Converted to spaces | Preserved as paragraph breaks |
124
| Text wrapping | Normal wrapping | Wrapping within paragraphs |
125
| Indentation | Standard | Applied to each paragraph |
126
| Rich markup | Fully supported | Fully supported |
127
| Style customization | All styles available | All styles available |
128
129
## Complete Example
130

131
```python
132
import argparse
133
from rich_argparse.contrib import ParagraphRichHelpFormatter
134

135
# Configure custom styling
136
ParagraphRichHelpFormatter.styles.update({
137
    "argparse.text": "dim white",
138
    "argparse.help": "bright_white"
139
})
140

141
parser = argparse.ArgumentParser(
142
    prog="document-processor",
143
    description="""
144
    Document Processor v2.0
145
    
146
    A comprehensive tool for processing various document formats with
147
    advanced features including format conversion, content extraction,
148
    and metadata manipulation.
149
    
150
    This tool supports batch processing and provides detailed logging
151
    for troubleshooting and audit purposes.
152
    
153
    For more information, visit our documentation website or use the
154
    --help-extended option.
155
    """,
156
    epilog="""
157
    Examples:
158
    
159
    Process a single file:
160
        document-processor input.pdf --output output.txt
161
    
162
    Batch process multiple files:
163
        document-processor *.pdf --batch --output-dir ./results/
164
    
165
    Extract metadata only:
166
        document-processor input.docx --metadata-only
167
    """,
168
    formatter_class=ParagraphRichHelpFormatter
169
)
170

171
parser.add_argument(
172
    "input", 
173
    nargs="+", 
174
    help="""
175
    Input file(s) to process.
176
    
177
    Supports various formats including PDF, DOCX, TXT, and HTML.
178
    Wildcards are supported for batch processing.
179
    """
180
)
181

182
parser.add_argument(
183
    "--output", 
184
    help="""
185
    Output file path.
186
    
187
    If not specified, output will be written to stdout.
188
    For batch processing, use --output-dir instead.
189
    """
190
)
191

192
parser.add_argument(
193
    "--format", 
194
    choices=["txt", "html", "json", "xml"],
195
    default="txt",
196
    help="""
197
    Output format specification.
198
    
199
    Different formats provide different levels of detail and
200
    structure preservation.
201
    
202
    JSON format includes full metadata and structure information.
203
    """
204
)
205

206
parser.add_argument(
207
    "--verbose", 
208
    action="store_true",
209
    help="""
210
    Enable verbose output.
211
    
212
    Provides detailed progress information during processing.
213
    Useful for debugging and monitoring large batch operations.
214
    """
215
)
216

217
if __name__ == "__main__":
218
    parser.print_help()
219
```
220

221
## Integration with Other Formatters
222

223
The ParagraphRichHelpFormatter can be combined with other argparse formatter features:
224

225
```python
226
import argparse
227
from rich_argparse.contrib import ParagraphRichHelpFormatter
228

229
# Combine with ArgumentDefaultsHelpFormatter behavior
230
class ParagraphArgumentDefaultsFormatter(
231
    argparse.ArgumentDefaultsHelpFormatter, 
232
    ParagraphRichHelpFormatter
233
):
234
    """Combines paragraph preservation with default value display."""
235
    pass
236

237
parser = argparse.ArgumentParser(
238
    formatter_class=ParagraphArgumentDefaultsFormatter
239
)
240

241
parser.add_argument(
242
    "--timeout", 
243
    type=int, 
244
    default=30,
245
    help="""
246
    Connection timeout in seconds.
247
    
248
    Higher values may be needed for slow network connections.
249
    Set to 0 to disable timeout.
250
    """
251
)
252
```
253

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