0
# Click
1

2
A comprehensive Python library for creating beautiful command line interfaces with minimal code. Click provides a decorator-based API for building command line tools with automatic help generation, argument validation, and option parsing, supporting arbitrary nesting of commands, lazy loading of subcommands at runtime, and advanced features like shell completion, prompts, progress bars, and styled output.
3

4
## Package Information
5

6
- **Package Name**: click
7
- **Language**: Python
8
- **Installation**: `pip install click`
9
- **Requires**: Python >=3.10
10

11
## Core Imports
12

13
```python
14
import click
15
```
16

17
For individual components:
18

19
```python
20
from click import command, option, argument, group, Context, Command
21
```
22

23
## Basic Usage
24

25
```python
26
import click
27

28
@click.command()
29
@click.option('--count', default=1, help='Number of greetings.')
30
@click.option('--name', prompt='Your name', help='The person to greet.')
31
def hello(count, name):
32
    """Simple program that greets NAME for a total of COUNT times."""
33
    for _ in range(count):
34
        click.echo(f'Hello, {name}!')
35

36
if __name__ == '__main__':
37
    hello()
38
```
39

40
## Architecture
41

42
Click's design is built around composable command structures:
43

44
- **Context**: Holds command state, parameters, and execution environment
45
- **Command**: Represents individual commands that can be executed
46
- **Group**: Multi-command containers that can nest other commands and groups
47
- **Parameter**: Base for Option and Argument classes handling command-line parameters
48
- **ParamType**: Type system for parameter validation and conversion
49
- **Decorators**: Function decorators that transform Python functions into Click commands
50

51
This architecture enables building complex CLI applications through simple decorators and intuitive patterns, making it ideal for creating development tools, automation scripts, system administration utilities, and any application requiring sophisticated command-line interaction.
52

53
## Capabilities
54

55
### Command Definition and Decorators
56

57
Core decorators for creating commands and command groups, along with parameter decorators for handling command-line arguments and options.
58

59
```python { .api }
60
def command(name=None, cls=None, **attrs): ...
61
def group(name=None, cls=None, **attrs): ...
62
def argument(*param_decls, cls=None, **attrs): ...
63
def option(*param_decls, cls=None, **attrs): ...
64
```
65

66
[Command Definition](./command-definition.md)
67

68
### Core Classes and Context Management
69

70
The foundational classes that represent commands, groups, parameters, and execution context, providing the structure for command-line applications.
71

72
```python { .api }
73
class Context: ...
74
class Command: ...
75
class Group: ...
76
class Parameter: ...
77
class Option(Parameter): ...
78
class Argument(Parameter): ...
79
```
80

81
[Core Classes](./core-classes.md)
82

83
### Parameter Types and Validation
84

85
Rich type system for command-line parameter validation and conversion, including built-in types for common data formats and custom type creation.
86

87
```python { .api }
88
class ParamType: ...
89
STRING: StringParamType
90
INT: IntParamType
91
FLOAT: FloatParamType
92
BOOL: BoolParamType
93
UUID: UUIDParameterType
94
class Choice(ParamType): ...
95
class Path(ParamType): ...
96
class File(ParamType): ...
97
```
98

99
[Parameter Types](./parameter-types.md)
100

101
### Terminal UI and User Interaction
102

103
Interactive terminal functionality including prompts, confirmations, progress bars, styled output, and text editing capabilities.
104

105
```python { .api }
106
def echo(message=None, file=None, nl=True, err=False, color=None): ...
107
def prompt(text, default=None, hide_input=False, confirmation_prompt=False, type=None, **kwargs): ...
108
def confirm(text, default=False, abort=False, **kwargs): ...
109
def style(text, fg=None, bg=None, bold=None, dim=None, underline=None, **kwargs): ...
110
def progressbar(iterable=None, length=None, **kwargs): ...
111
```
112

113
[Terminal UI](./terminal-ui.md)
114

115
### Exception Handling and Error Management
116

117
Comprehensive exception classes for handling various error conditions in command-line applications, with proper error reporting and user-friendly messages.
118

119
```python { .api }
120
class ClickException(Exception): ...
121
class UsageError(ClickException): ...
122
class BadParameter(UsageError): ...
123
class MissingParameter(BadParameter): ...
124
class NoSuchOption(UsageError): ...
125
```
126

127
[Exception Handling](./exception-handling.md)
128

129
### Utilities and Helper Functions
130

131
Utility functions for file handling, stream management, text formatting, and other common CLI application needs.
132

133
```python { .api }
134
def get_app_dir(app_name, roaming=True, force_posix=False): ...
135
def open_file(filename, mode="r", encoding=None, errors="strict", lazy=False, atomic=False): ...
136
def format_filename(filename, shorten=False): ...
137
def get_current_context(silent=False): ...
138
class HelpFormatter: ...
139
def wrap_text(text, width=78, initial_indent="", subsequent_indent="", preserve_paragraphs=False): ...
140
```
141

142
[Utilities](./utilities.md)
143

144
## Types
145

146
### Basic Context and Command Types
147

148
```python { .api }
149
class Context:
150
    def __init__(self, command, parent=None, info_name=None, obj=None, 
151
                 auto_envvar_prefix=None, default_map=None, terminal_width=None, 
152
                 max_content_width=None, resilient_parsing=False, 
153
                 allow_extra_args=None, allow_interspersed_args=None, 
154
                 ignore_unknown_options=None, help_option_names=None, 
155
                 token_normalize_func=None, color=None, show_default=None): ...
156

157
class Command:
158
    def __init__(self, name, context_settings=None, callback=None, params=None, 
159
                 help=None, epilog=None, short_help=None, options_metavar="[OPTIONS]", 
160
                 add_help_option=True, no_args_is_help=False, hidden=False, 
161
                 deprecated=False): ...
162

163
class Group(Command):
164
    def __init__(self, name=None, commands=None, invoke_without_command=False, 
165
                 no_args_is_help=None, subcommand_metavar=None, chain=False, 
166
                 result_callback=None, **kwargs): ...
167
```