0
# Core Decorators
1
2
Essential decorators for creating rich-formatted Click commands and groups. These decorators provide the primary interface for building CLI applications with Rich-Click, offering enhanced help output, styling capabilities, and configuration options.
3
4
## Capabilities
5
6
### Command Decorator
7
8
Creates rich-formatted commands using RichCommand by default. Supports all Click command options while providing enhanced help formatting.
9
10
```python { .api }
11
def command(name=None, cls=None, **attrs):
12
"""
13
Command decorator function that uses RichCommand by default.
14
15
Parameters:
16
- name (str, optional): Name of the command
17
- cls (Type[Command], optional): Command class to use, defaults to RichCommand
18
- **attrs: Additional command attributes
19
20
Returns:
21
Union[Command, Callable]: Command object or decorator function
22
"""
23
```
24
25
Usage examples:
26
27
```python
28
import rich_click as click
29
30
# Simple command
31
@click.command()
32
def hello():
33
"""A simple command."""
34
click.echo("Hello!")
35
36
# Command with custom name
37
@click.command("greet")
38
def hello():
39
"""Greet someone."""
40
click.echo("Hello!")
41
42
# Command with custom class
43
@click.command(cls=MyCustomRichCommand)
44
def hello():
45
"""Custom command."""
46
click.echo("Hello!")
47
```
48
49
### Group Decorator
50
51
Creates rich-formatted command groups using RichGroup by default. Enables creation of multi-command CLIs with enhanced formatting.
52
53
```python { .api }
54
def group(name=None, cls=None, **attrs):
55
"""
56
Group decorator function that uses RichGroup by default.
57
58
Parameters:
59
- name (str, optional): Name of the group
60
- cls (Type[Group], optional): Group class to use, defaults to RichGroup
61
- **attrs: Additional group attributes
62
63
Returns:
64
Union[Group, Callable]: Group object or decorator function
65
"""
66
```
67
68
Usage examples:
69
70
```python
71
import rich_click as click
72
73
# Simple group
74
@click.group()
75
def cli():
76
"""A CLI application."""
77
pass
78
79
@cli.command()
80
def hello():
81
"""Say hello."""
82
click.echo("Hello!")
83
84
# Group with custom name
85
@click.group("mycli")
86
def cli():
87
"""My CLI application."""
88
pass
89
90
# Group with custom class
91
@click.group(cls=MyCustomRichGroup)
92
def cli():
93
"""Custom group."""
94
pass
95
```
96
97
### Context Passing Decorator
98
99
Type-aware context passing decorator that provides RichContext instead of regular Click Context.
100
101
```python { .api }
102
def pass_context(f):
103
"""
104
Marks a callback as wanting to receive the current RichContext object as first argument.
105
106
Parameters:
107
- f (Callable): Function to decorate
108
109
Returns:
110
Callable: Decorated function that receives RichContext
111
"""
112
```
113
114
Usage example:
115
116
```python
117
import rich_click as click
118
119
@click.command()
120
@click.pass_context
121
def hello(ctx):
122
"""Command that uses context."""
123
# ctx is a RichContext instance
124
click.echo(f"Command invoked with: {ctx.info_name}")
125
```
126
127
### Rich Configuration Decorator
128
129
Decorator for configuring Rich-Click settings including help configuration and console options.
130
131
```python { .api }
132
def rich_config(help_config=None, *, console=None):
133
"""
134
Use decorator to configure Rich Click settings.
135
136
Parameters:
137
- help_config (Union[Mapping[str, Any], RichHelpConfiguration], optional):
138
Rich help configuration for formatting help messages and exceptions
139
- console (Console, optional): Rich Console instance for the command
140
141
Returns:
142
Callable: Decorator function for configuring Rich settings
143
144
Raises:
145
- NotSupportedError: If used with incompatible command types
146
"""
147
```
148
149
Usage examples:
150
151
```python
152
import rich_click as click
153
from rich.console import Console
154
155
# Basic configuration
156
@click.command()
157
@click.rich_config({"style_option": "bold red"})
158
def hello():
159
"""Configured command."""
160
click.echo("Hello!")
161
162
# With custom console
163
console = Console(width=120)
164
165
@click.command()
166
@click.rich_config(console=console)
167
def hello():
168
"""Command with custom console."""
169
click.echo("Hello!")
170
171
# With RichHelpConfiguration object
172
from rich_click import RichHelpConfiguration
173
174
config = RichHelpConfiguration(
175
style_option="bold cyan",
176
show_arguments=True
177
)
178
179
@click.command()
180
@click.rich_config(config)
181
def hello():
182
"""Command with configuration object."""
183
click.echo("Hello!")
184
```
185
186
## Exception Classes
187
188
### Not Supported Error
189
190
Exception raised when rich_config decorator is used with incompatible objects.
191
192
```python { .api }
193
class NotSupportedError(Exception):
194
"""
195
Exception raised when rich_config is used with unsupported objects.
196
197
Raised when rich_config decorator is applied to objects that are not
198
RichCommand, RichGroup, or functions.
199
"""
200
```
201
202
## Type Information
203
204
```python { .api }
205
# Type aliases used in decorators
206
_AnyCallable = Callable[..., Any]
207
F = TypeVar("F", bound=Callable[..., Any])
208
FC = TypeVar("FC", bound=Union[Command, _AnyCallable])
209
GrpType = TypeVar("GrpType", bound=Group)
210
CmdType = TypeVar("CmdType", bound=Command)
211
```