0
# Command Definition and Decorators
1

2
Core decorators for creating commands and command groups, along with parameter decorators for handling command-line arguments and options. These decorators transform Python functions into Click commands with minimal boilerplate.
3

4
## Capabilities
5

6
### Command Creation
7

8
Transform Python functions into executable commands with automatic help generation and parameter parsing.
9

10
```python { .api }
11
def command(name=None, cls=None, **attrs):
12
    """
13
    Decorator that converts a function into a Click command.
14
    
15
    Parameters:
16
    - name: str, optional name for the command (defaults to function name)
17
    - cls: Command class to use (defaults to Command)
18
    - context_settings: dict, default Context settings
19
    - help: str, help text for the command
20
    - epilog: str, text to show after help
21
    - short_help: str, short help for command listings
22
    - add_help_option: bool, whether to add --help option
23
    - no_args_is_help: bool, show help when no arguments provided
24
    - hidden: bool, hide from help listings
25
    - deprecated: bool, mark as deprecated
26
    
27
    Returns:
28
    Decorated function as Command instance
29
    """
30

31
def group(name=None, cls=None, **attrs):
32
    """
33
    Decorator that converts a function into a Click command group.
34
    
35
    Parameters:
36
    - name: str, optional name for the group (defaults to function name)
37
    - cls: Group class to use (defaults to Group)
38
    - commands: dict, initial subcommands
39
    - invoke_without_command: bool, invoke group callback without subcommand
40
    - no_args_is_help: bool, show help when no arguments provided
41
    - subcommand_metavar: str, how to represent subcommands in help
42
    - chain: bool, allow chaining multiple subcommands
43
    - result_callback: callable, callback for processing results
44
    
45
    Returns:
46
    Decorated function as Group instance
47
    """
48
```
49

50
**Usage Examples:**
51

52
```python
53
@click.command()
54
def simple():
55
    """A simple command."""
56
    click.echo('Hello World!')
57

58
@click.group()
59
def cli():
60
    """A command group."""
61
    pass
62

63
@cli.command()
64
def subcommand():
65
    """A subcommand."""
66
    click.echo('This is a subcommand')
67

68
# Chaining commands
69
@click.group(chain=True)
70
def pipeline():
71
    """Pipeline processing."""
72
    pass
73

74
@pipeline.command()
75
def step1():
76
    click.echo('Step 1')
77

78
@pipeline.command() 
79
def step2():
80
    click.echo('Step 2')
81
```
82

83
### Parameter Decorators
84

85
Add command-line arguments and options to commands with automatic type conversion and validation.
86

87
```python { .api }
88
def argument(*param_decls, cls=None, **attrs):
89
    """
90
    Decorator to add a positional argument to a command.
91
    
92
    Parameters:
93
    - param_decls: parameter declarations (argument name)
94
    - cls: Argument class to use
95
    - type: parameter type for conversion
96
    - required: bool, whether argument is required (default True)
97
    - default: default value if not provided
98
    - callback: function to process the value
99
    - nargs: number of arguments to consume
100
    - multiple: bool, accept multiple values
101
    - metavar: how to display in help
102
    - envvar: environment variable name(s)
103
    - shell_complete: shell completion function
104
    """
105

106
def option(*param_decls, cls=None, **attrs):
107
    """
108
    Decorator to add a command-line option to a command.
109
    
110
    Parameters:
111
    - param_decls: option flags (e.g., '--verbose', '-v')
112
    - cls: Option class to use
113
    - type: parameter type for conversion
114
    - required: bool, whether option is required
115
    - default: default value
116
    - help: help text for the option
117
    - show_default: bool/str, show default value in help
118
    - prompt: bool/str, prompt for value if not provided
119
    - confirmation_prompt: bool, require confirmation
120
    - hide_input: bool, hide input when prompting
121
    - is_flag: bool, treat as boolean flag
122
    - flag_value: value when flag is present
123
    - multiple: bool, allow multiple values
124
    - count: bool, count number of times option is used
125
    - envvar: environment variable name(s)
126
    - show_envvar: bool, show env var in help
127
    - show_choices: bool, show choices in help
128
    - hidden: bool, hide from help
129
    """
130
```
131

132
**Usage Examples:**
133

134
```python
135
@click.command()
136
@click.argument('filename')
137
@click.option('--verbose', '-v', is_flag=True, help='Enable verbose output')
138
@click.option('--count', default=1, help='Number of times to process')
139
@click.option('--output', type=click.Path(), help='Output file path')
140
def process(filename, verbose, count, output):
141
    """Process a file with options."""
142
    for i in range(count):
143
        if verbose:
144
            click.echo(f'Processing {filename} (iteration {i+1})')
145
        # Process file...
146

147
@click.command()
148
@click.option('--name', prompt=True, help='Your name')
149
@click.option('--password', prompt=True, hide_input=True)
150
def login(name, password):
151
    """Login command with prompts."""
152
    click.echo(f'Logging in {name}...')
153
```
154

155
### Special Option Decorators
156

157
Pre-configured option decorators for common CLI patterns.
158

159
```python { .api }
160
def confirmation_option(*param_decls, **kwargs):
161
    """
162
    Add a confirmation option (typically --yes).
163
    
164
    Parameters:
165
    - param_decls: option flags (defaults to '--yes')
166
    - expose_value: bool, expose value to callback (default False)
167
    - prompt: str, confirmation prompt text
168
    """
169

170
def password_option(*param_decls, **kwargs):
171
    """
172
    Add a password option with hidden input.
173
    
174
    Parameters:
175
    - param_decls: option flags (defaults to '--password')
176
    - prompt: bool/str, prompt text (default True)
177
    - hide_input: bool, hide input (default True)
178
    - confirmation_prompt: bool, require confirmation (default False)
179
    """
180

181
def version_option(version=None, *param_decls, package_name=None, 
182
                   prog_name=None, message=None, **kwargs):
183
    """
184
    Add a version option.
185
    
186
    Parameters:
187
    - version: str, version string or None to auto-detect
188
    - param_decls: option flags (defaults to '--version')
189
    - package_name: str, package name for auto-detection
190
    - prog_name: str, program name in message
191
    - message: str, custom version message template
192
    """
193

194
def help_option(*param_decls, **kwargs):
195
    """
196
    Add a help option.
197
    
198
    Parameters:
199
    - param_decls: option flags (defaults to '--help')
200
    - help: str, help text for the option
201
    """
202
```
203

204
**Usage Examples:**
205

206
```python
207
@click.command()
208
@click.confirmation_option(prompt='Are you sure you want to delete all files?')
209
def cleanup():
210
    """Cleanup command with confirmation."""
211
    click.echo('Cleaning up...')
212

213
@click.command()
214
@click.password_option()
215
def secure_operation(password):
216
    """Command requiring password."""
217
    click.echo('Performing secure operation...')
218

219
@click.command()
220
@click.version_option(version='1.0.0')
221
def myapp():
222
    """Application with version info."""
223
    click.echo('Running myapp...')
224
```
225

226
### Context Passing Decorators
227

228
Pass context information to command callbacks for advanced functionality.
229

230
```python { .api }
231
def pass_context(f):
232
    """
233
    Decorator to pass the current context as the first argument.
234
    
235
    Returns:
236
    Decorated function receiving Context as first parameter
237
    """
238

239
def pass_obj(f):
240
    """
241
    Decorator to pass the context object (ctx.obj) as the first argument.
242
    
243
    Returns:
244
    Decorated function receiving ctx.obj as first parameter
245
    """
246

247
def make_pass_decorator(object_type, ensure=False):
248
    """
249
    Factory to create custom pass decorators.
250
    
251
    Parameters:
252
    - object_type: type to look for in context hierarchy
253
    - ensure: bool, create object if not found
254
    
255
    Returns:
256
    Decorator function that passes the found object
257
    """
258
```
259

260
**Usage Examples:**
261

262
```python
263
@click.group()
264
@click.pass_context
265
def cli(ctx):
266
    """Main CLI with context."""
267
    ctx.ensure_object(dict)
268
    ctx.obj['verbose'] = False
269

270
@cli.command()
271
@click.option('--verbose', is_flag=True)
272
@click.pass_obj
273
def subcommand(config, verbose):
274
    """Subcommand accessing shared config."""
275
    if verbose:
276
        config['verbose'] = True
277
    click.echo(f'Verbose mode: {config["verbose"]}')
278

279
# Custom pass decorator
280
pass_config = click.make_pass_decorator(dict)
281

282
@cli.command()
283
@pass_config
284
def another_command(config):
285
    """Another command with custom decorator."""
286
    click.echo(f'Config: {config}')
287
```