0
# Configuration and Styling
1

2
Comprehensive configuration system for customizing Rich-Click appearance, behavior, and styling. The configuration system provides extensive options for colors, panels, tables, text formatting, and behavioral settings to create visually appealing command-line interfaces.
3

4
## Capabilities
5

6
### Global Configuration Module
7

8
The `rich_click.rich_click` module contains global configuration constants that control default styling and behavior across all Rich-Click commands.
9

10
```python { .api }
11
# Style constants
12
STYLE_OPTION: str = "bold cyan"
13
STYLE_ARGUMENT: str = "bold cyan"
14
STYLE_COMMAND: str = "bold cyan"
15
STYLE_SWITCH: str = "bold green"
16
STYLE_METAVAR: str = "bold yellow"
17
STYLE_METAVAR_APPEND: str = "dim yellow"
18
STYLE_METAVAR_SEPARATOR: str = "dim"
19
STYLE_HEADER_TEXT: str = ""
20
STYLE_EPILOG_TEXT: str = ""
21
STYLE_FOOTER_TEXT: str = ""
22
STYLE_USAGE: str = "yellow"
23
STYLE_USAGE_COMMAND: str = "bold"
24
STYLE_DEPRECATED: str = "red"
25
STYLE_HELPTEXT_FIRST_LINE: str = ""
26
STYLE_HELPTEXT: str = "dim"
27
STYLE_OPTION_HELP: str = ""
28
STYLE_OPTION_DEFAULT: str = "dim"
29
STYLE_OPTION_ENVVAR: str = "dim yellow"
30
STYLE_REQUIRED_SHORT: str = "red"
31
STYLE_REQUIRED_LONG: str = "dim red"
32
STYLE_ABORTED: str = "red"
33

34
# Panel styling constants
35
STYLE_OPTIONS_PANEL_BORDER: str = "dim"
36
STYLE_OPTIONS_PANEL_BOX: Optional[str] = "ROUNDED"
37
ALIGN_OPTIONS_PANEL: str = "left"
38
STYLE_COMMANDS_PANEL_BORDER: str = "dim"
39
STYLE_COMMANDS_PANEL_BOX: Optional[str] = "ROUNDED"
40
ALIGN_COMMANDS_PANEL: str = "left"
41
STYLE_ERRORS_PANEL_BORDER: str = "red"
42
STYLE_ERRORS_PANEL_BOX: Optional[str] = "ROUNDED"
43
ALIGN_ERRORS_PANEL: str = "left"
44

45
# Table styling constants  
46
STYLE_OPTIONS_TABLE_SHOW_LINES: bool = False
47
STYLE_OPTIONS_TABLE_LEADING: int = 0
48
STYLE_OPTIONS_TABLE_PAD_EDGE: bool = False
49
STYLE_OPTIONS_TABLE_PADDING: tuple = (0, 1)
50
STYLE_OPTIONS_TABLE_BOX: Optional[str] = ""
51
STYLE_OPTIONS_TABLE_ROW_STYLES: Optional[List[str]] = None
52
STYLE_OPTIONS_TABLE_BORDER_STYLE: Optional[str] = None
53
STYLE_COMMANDS_TABLE_SHOW_LINES: bool = False
54
STYLE_COMMANDS_TABLE_LEADING: int = 0
55
STYLE_COMMANDS_TABLE_PAD_EDGE: bool = False
56
STYLE_COMMANDS_TABLE_PADDING: tuple = (0, 1)
57
STYLE_COMMANDS_TABLE_BOX: Optional[str] = ""
58
STYLE_COMMANDS_TABLE_ROW_STYLES: Optional[List[str]] = None
59
STYLE_COMMANDS_TABLE_BORDER_STYLE: Optional[str] = None
60
STYLE_COMMANDS_TABLE_COLUMN_WIDTH_RATIO: Optional[tuple] = (None, None)
61

62
# Terminal configuration
63
WIDTH: Optional[int] = None
64
MAX_WIDTH: Optional[int] = None
65
COLOR_SYSTEM: Optional[str] = "auto"
66
FORCE_TERMINAL: Optional[bool] = None
67

68
# Text constants
69
HEADER_TEXT: Optional[str] = None
70
FOOTER_TEXT: Optional[str] = None
71
DEPRECATED_STRING: str = "(Deprecated) "
72
DEPRECATED_WITH_REASON_STRING: str = "(Deprecated: {}) "
73
DEFAULT_STRING: str = "[default: {}]"
74
ENVVAR_STRING: str = "[env var: {}]"
75
REQUIRED_SHORT_STRING: str = "*"
76
REQUIRED_LONG_STRING: str = "[required]"
77
RANGE_STRING: str = " [{}]"
78
APPEND_METAVARS_HELP_STRING: str = "({})"
79
ARGUMENTS_PANEL_TITLE: str = "Arguments"
80
OPTIONS_PANEL_TITLE: str = "Options"
81
COMMANDS_PANEL_TITLE: str = "Commands"
82
ERRORS_PANEL_TITLE: str = "Error"
83
ERRORS_SUGGESTION: Optional[str] = None
84
ERRORS_EPILOGUE: Optional[str] = None
85
ABORTED_TEXT: str = "Aborted."
86

87
# Behavior constants
88
SHOW_ARGUMENTS: bool = False
89
SHOW_METAVARS_COLUMN: bool = True
90
APPEND_METAVARS_HELP: bool = False
91
GROUP_ARGUMENTS_OPTIONS: bool = False
92
OPTION_ENVVAR_FIRST: bool = False
93
TEXT_MARKUP: str = "ansi"
94
USE_MARKDOWN: bool = False
95
USE_MARKDOWN_EMOJI: bool = True
96
USE_RICH_MARKUP: bool = False
97
COMMAND_GROUPS: Dict[str, List[CommandGroupDict]] = {}
98
OPTION_GROUPS: Dict[str, List[OptionGroupDict]] = {}
99
USE_CLICK_SHORT_HELP: bool = False
100
```
101

102
### Configuration Utility Functions
103

104
Helper functions for configuration management and terminal detection.
105

106
```python { .api }
107
def force_terminal_default() -> Optional[bool]:
108
    """
109
    Use as the default factory for `force_terminal`.
110
    
111
    Checks environment variables (FORCE_COLOR, PY_COLORS, GITHUB_ACTIONS)
112
    to determine if terminal formatting should be forced.
113
    
114
    Returns:
115
    Optional[bool]: Terminal force setting or None
116
    """
117

118
def terminal_width_default() -> Optional[int]:
119
    """
120
    Use as the default factory for `width` and `max_width`.
121
    
122
    Reads TERMINAL_WIDTH environment variable to set terminal width.
123
    
124
    Returns:
125
    Optional[int]: Terminal width or None
126
    
127
    Raises:
128
    UserWarning: If TERMINAL_WIDTH cannot be cast to integer
129
    """
130
```
131

132
### Command and Option Grouping
133

134
Configuration for organizing commands and options into named panels with custom styling.
135

136
```python { .api }
137
# Command grouping configuration
138
COMMAND_GROUPS: Dict[str, List[CommandGroupDict]] = {}
139

140
# Option grouping configuration  
141
OPTION_GROUPS: Dict[str, List[OptionGroupDict]] = {}
142

143
# Type definitions for grouping
144
CommandGroupDict = TypedDict('CommandGroupDict', {
145
    'name': NotRequired[str],
146
    'commands': List[str], 
147
    'table_styles': NotRequired[Dict[str, Any]],
148
    'panel_styles': NotRequired[Dict[str, Any]],
149
    'deduplicate': NotRequired[bool]
150
})
151

152
OptionGroupDict = TypedDict('OptionGroupDict', {
153
    'name': NotRequired[str],
154
    'options': NotRequired[List[str]],
155
    'table_styles': NotRequired[Dict[str, Any]], 
156
    'panel_styles': NotRequired[Dict[str, Any]],
157
    'deduplicate': NotRequired[bool]
158
})
159
```
160

161
Usage examples for grouping:
162

163
```python
164
import rich_click as click
165

166
# Configure command groups
167
click.COMMAND_GROUPS = {
168
    "mycli": [
169
        {
170
            "name": "Database Commands",
171
            "commands": ["init-db", "migrate", "seed"]
172
        },
173
        {
174
            "name": "Server Commands", 
175
            "commands": ["run", "debug", "test"]
176
        }
177
    ]
178
}
179

180
# Configure option groups
181
click.OPTION_GROUPS = {
182
    "mycli": [
183
        {
184
            "name": "Configuration Options",
185
            "options": ["--config", "--env", "--debug"]
186
        },
187
        {
188
            "name": "Output Options",
189
            "options": ["--verbose", "--quiet", "--format"]
190
        }
191
    ]
192
}
193

194
@click.group()
195
def mycli():
196
    """My CLI application."""
197
    pass
198

199
@mycli.command()
200
@click.option("--config", help="Configuration file")
201
@click.option("--verbose", is_flag=True, help="Verbose output")
202
def init_db():
203
    """Initialize database."""
204
    pass
205
```
206

207
### Style Customization Examples
208

209
Examples of common styling customizations:
210

211
```python
212
import rich_click as click
213

214
# Customize colors
215
click.STYLE_OPTION = "bold blue"
216
click.STYLE_COMMAND = "bold green"
217
click.STYLE_USAGE = "bold yellow"
218

219
# Customize panel appearance
220
click.STYLE_OPTIONS_PANEL_BOX = "DOUBLE"
221
click.STYLE_COMMANDS_PANEL_BOX = "HEAVY"
222
click.OPTIONS_PANEL_TITLE = "Available Options"
223
click.COMMANDS_PANEL_TITLE = "Available Commands"
224

225
# Enable arguments display
226
click.SHOW_ARGUMENTS = True
227

228
# Enable markdown formatting
229
click.TEXT_MARKUP = "markdown"
230

231
# Customize error styling
232
click.STYLE_ERRORS_PANEL_BORDER = "bold red"
233
click.ERRORS_PANEL_TITLE = "Error Details"
234

235
@click.command()
236
@click.option("--name", help="Your name")
237
@click.argument("count", type=int)
238
def hello(name, count):
239
    """Say hello with custom styling."""
240
    for _ in range(count):
241
        click.echo(f"Hello, {name}!")
242
```
243

244
### RichHelpConfiguration Integration
245

246
The global constants integrate with RichHelpConfiguration for per-command customization:
247

248
```python
249
import rich_click as click
250

251
# Create configuration from globals
252
config = click.RichHelpConfiguration.load_from_globals()
253

254
# Modify specific settings
255
config.style_option = "bold magenta"
256
config.show_arguments = True
257
config.options_panel_title = "Configuration"
258

259
# Apply to specific command
260
@click.command()
261
@click.rich_config(config)
262
def hello():
263
    """Command with custom configuration."""
264
    click.echo("Hello!")
265

266
# Or dump back to globals
267
config.dump_to_globals()
268
```
269

270
### Text Markup Options
271

272
Rich-Click supports multiple text markup formats for help text:
273

274
```python
275
import rich_click as click
276

277
# ANSI markup (default)
278
click.TEXT_MARKUP = "ansi"
279

280
# Rich markup  
281
click.TEXT_MARKUP = "rich"
282
click.USE_RICH_MARKUP = True
283

284
# Markdown markup
285
click.TEXT_MARKUP = "markdown" 
286
click.USE_MARKDOWN = True
287
click.USE_MARKDOWN_EMOJI = True
288

289
@click.command()
290
def hello():
291
    """
292
    Say hello with [bold]rich[/bold] formatting.
293
    
294
    This command supports **markdown** and :smile: emoji when configured.
295
    """
296
    click.echo("Hello!")
297
```
298

299
## Deprecated Configuration
300

301
### Legacy Configuration Options
302

303
Some configuration options are deprecated but still supported:
304

305
```python { .api }
306
# Deprecated - use text_markup instead
307
USE_MARKDOWN: bool = False
308
USE_RICH_MARKUP: bool = False
309

310
# Deprecated function access
311
def get_module_help_configuration():
312
    """Deprecated. Use RichHelpConfiguration.load_from_globals() instead."""
313
```