0
# Rich-Click
1

2
Rich-Click is a Python library that provides attractive help output from Click, formatted with Rich, with minimal customization required. It serves as a drop-in replacement for Click while enhancing command-line interfaces with rich text formatting, colors, and visual enhancements.
3

4
## Package Information
5

6
- **Package Name**: rich-click
7
- **Language**: Python
8
- **Installation**: `pip install rich-click`
9

10
## Core Imports
11

12
```python
13
import rich_click as click
14
```
15

16
Or use specific imports:
17

18
```python
19
from rich_click import command, group, option, argument
20
from rich_click import RichCommand, RichGroup, RichContext
21
from rich_click import __version__
22
```
23

24
### Version Information
25

26
```python { .api }
27
__version__: str = "1.8.9"
28
```
29

30
## Basic Usage
31

32
```python
33
import rich_click as click
34

35
@click.command()
36
@click.option("--count", default=1, help="Number of greetings.")
37
@click.option("--name", prompt="Your name", help="The person to greet.")
38
def hello(count, name):
39
    """Simple program that greets NAME for a total of COUNT times."""
40
    for _ in range(count):
41
        click.echo(f"Hello, {name}!")
42

43
if __name__ == '__main__':
44
    hello()
45
```
46

47
## Architecture
48

49
Rich-Click extends Click's architecture with Rich formatting capabilities:
50

51
- **Drop-in Replacement**: Complete Click API compatibility via re-exports
52
- **Rich Enhancement**: Enhanced classes (RichCommand, RichGroup, RichContext) with Rich formatting
53
- **Configuration System**: Comprehensive styling through RichHelpConfiguration
54
- **Patching Capability**: Monkey-patch existing Click applications
55
- **CLI Tool**: Command-line utility to enhance external Click tools
56

57
## Capabilities
58

59
### Core Decorators
60

61
Essential decorators for creating rich-formatted Click commands and groups with enhanced help output and styling capabilities.
62

63
```python { .api }
64
def command(name=None, cls=None, **attrs):
65
    """Create a rich-formatted command."""
66

67
def group(name=None, cls=None, **attrs):
68
    """Create a rich-formatted command group."""
69

70
def pass_context(f):
71
    """Pass RichContext to the decorated function."""
72

73
def rich_config(help_config=None, *, console=None):
74
    """Configure Rich settings for commands."""
75
```
76

77
[Core Decorators](./decorators.md)
78

79
### Rich Classes
80

81
Enhanced Click classes with rich formatting capabilities including command classes, context management, and configuration systems.
82

83
```python { .api }
84
class RichCommand(click.Command):
85
    """Enhanced Click command with rich formatting."""
86

87
class RichGroup(click.Group):
88
    """Enhanced Click group with rich formatting."""
89

90
class RichContext(click.Context):
91
    """Enhanced Click context with Rich capabilities."""
92

93
class RichHelpConfiguration:
94
    """Comprehensive configuration for Rich help formatting."""
95
```
96

97
[Rich Classes](./classes.md)
98

99
### Configuration and Styling
100

101
Comprehensive configuration system for customizing Rich-Click appearance, behavior, and styling with extensive options for colors, panels, tables, and text formatting.
102

103
```python { .api }
104
class RichHelpConfiguration:
105
    # Style configuration
106
    style_option: str = "bold cyan"
107
    style_argument: str = "bold cyan"
108
    style_command: str = "bold cyan"
109
    # ... many more styling options
110
    
111
    # Behavior configuration
112
    show_arguments: bool = False
113
    show_metavars_column: bool = True
114
    text_markup: str = "ansi"
115
    # ... many more behavior options
116
```
117

118
[Configuration](./configuration.md)
119

120
### Click API Re-exports
121

122
Complete Click API re-exported for drop-in compatibility including all core classes, decorators, exceptions, types, and utility functions.
123

124
```python { .api }
125
# Core classes
126
class Command: ...
127
class Group: ...
128
class Context: ...
129
class Option: ...
130
class Argument: ...
131

132
# Decorators
133
def option(*param_decls, **attrs): ...
134
def argument(*param_decls, **attrs): ...
135

136
# Exception classes
137
class ClickException(Exception): ...
138
class UsageError(ClickException): ...
139
class BadParameter(UsageError): ...
140
```
141

142
[Click API](./click-api.md)
143

144
### Utilities and Patching
145

146
Utility functions for patching existing Click applications and various helper functions for working with Rich-Click components.
147

148
```python { .api }
149
def patch(rich_config=None):
150
    """Patch Click internals to use rich-click types."""
151

152
def truthy(o):
153
    """Check if string or other obj is truthy."""
154

155
class CommandGroupDict(TypedDict):
156
    """Specification for command groups."""
157

158
class OptionGroupDict(TypedDict):
159
    """Specification for option groups."""
160
```
161

162
[Utilities](./utilities.md)
163

164
### Command Line Interface
165

166
Rich-Click CLI tool for enhancing external Click applications with rich formatting without modifying their source code.
167

168
```python { .api }
169
def main(ctx, script_and_args, output, errors_in_output_format, 
170
         suppress_warnings, rich_config, show_help):
171
    """Rich-click CLI command entry point."""
172
```
173

174
[CLI Tool](./cli.md)