0
# types-click
1

2
Typing stubs for click - a command line interface creation kit for Python. These type stubs enable static type checking with tools like mypy, PyCharm, and pytype when using the click library, providing better IDE support and helping catch type-related errors during development.
3

4
## Package Information
5

6
- **Package Name**: types-click
7
- **Language**: Python (Type Stubs)
8
- **Installation**: `pip install types-click`
9
- **Described Package**: click 7.1.x
10
- **Purpose**: Provides comprehensive typing stubs for the click library
11

12
## Core Imports
13

14
```python
15
import click
16
```
17

18
Common decorator imports:
19

20
```python
21
from click import command, group, option, argument, pass_context, pass_obj
22
```
23

24
Core classes and utilities:
25

26
```python
27
from click import Context, Command, Group, echo, style, prompt, confirm
28
```
29

30
Parameter types:
31

32
```python
33
from click import Choice, Path, IntRange, FloatRange, File, DateTime
34
# Or use type constants
35
from click import BOOL, INT, FLOAT, STRING, UUID
36
```
37

38
Exception handling:
39

40
```python
41
from click import ClickException, UsageError, BadParameter, Abort
42
```
43

44
Testing support:
45

46
```python
47
from click.testing import CliRunner
48
```
49

50
Advanced imports:
51

52
```python
53
# Special decorators
54
from click import version_option, help_option, confirmation_option, password_option
55

56
# Terminal UI functions  
57
from click import progressbar, clear, pause, edit, launch, get_terminal_size
58

59
# File and stream utilities
60
from click import get_binary_stream, get_text_stream, open_file, get_app_dir
61

62
# Formatting utilities
63
from click.formatting import HelpFormatter, wrap_text
64

65
# Global context access
66
from click import get_current_context
67
```
68

69
## Basic Usage
70

71
```python
72
import click
73

74
@click.command()
75
@click.option('--count', default=1, help='Number of greetings.')
76
@click.option('--name', prompt='Your name', help='The person to greet.')
77
def hello(count, name):
78
    """Simple program that greets NAME for a total of COUNT times."""
79
    for _ in range(count):
80
        click.echo(f'Hello, {name}!')
81

82
if __name__ == '__main__':
83
    hello()
84
```
85

86
Group example:
87

88
```python
89
import click
90

91
@click.group()
92
def cli():
93
    """A CLI tool with multiple commands."""
94
    pass
95

96
@cli.command()
97
@click.argument('name')
98
def greet(name):
99
    """Greet someone."""
100
    click.echo(f'Hello {name}!')
101

102
@cli.command()
103
@click.option('--format', type=click.Choice(['json', 'plain']))
104
def status(format):
105
    """Show status."""
106
    if format == 'json':
107
        click.echo('{"status": "ok"}')
108
    else:
109
        click.echo('Status: OK')
110

111
if __name__ == '__main__':
112
    cli()
113
```
114

115
## Architecture
116

117
Click follows a decorator-based design pattern built around several key concepts:
118

119
- **Commands**: Individual CLI commands defined with `@command` decorator
120
- **Groups**: Collections of commands using `@group` decorator  
121
- **Parameters**: Options (`@option`) and arguments (`@argument`) that define command inputs
122
- **Context**: Execution context passed between commands containing state and configuration
123
- **Types**: Rich parameter validation and conversion system
124
- **Testing**: Built-in CLI testing framework for automated testing
125

126
This architecture enables building complex CLI applications with hierarchical commands, rich parameter validation, interactive prompts, and comprehensive help generation.
127

128
## Capabilities
129

130
### Command and Group Creation
131

132
Core decorators for defining CLI commands and organizing them into groups. Commands are the fundamental building blocks of CLI applications, while groups enable hierarchical command structures.
133

134
```python { .api }
135
def command(name: str | None = ..., **kwargs) -> Callable[[Callable], Command]: ...
136
def group(name: str | None = ..., **kwargs) -> Callable[[Callable], Group]: ...
137
```
138

139
[Commands and Groups](./commands-groups.md)
140

141
### Parameter Definition
142

143
Decorators for defining command-line options and arguments with rich type validation, default values, prompts, and help text. These provide the interface between users and command functionality.
144

145
```python { .api }
146
def option(*param_decls: str, **kwargs) -> Callable: ...
147
def argument(*param_decls: str, **kwargs) -> Callable: ...
148
```
149

150
[Parameters](./parameters.md)
151

152
### Parameter Types
153

154
Rich type system for validating and converting command-line inputs including built-in types for common patterns like file paths, choices, numeric ranges, and custom type creation.
155

156
```python { .api }
157
class Choice(ParamType):
158
    def __init__(self, choices: Iterable[str], case_sensitive: bool = ...) -> None: ...
159

160
class Path(ParamType):
161
    def __init__(self, exists: bool = ..., file_okay: bool = ..., dir_okay: bool = ..., **kwargs) -> None: ...
162

163
class IntRange(IntParamType):
164
    def __init__(self, min: int | None = ..., max: int | None = ..., clamp: bool = ...) -> None: ...
165
```
166

167
[Parameter Types](./parameter-types.md)
168

169
### Context Management
170

171
Context objects that maintain state and configuration throughout command execution, enabling communication between commands and providing access to execution metadata.
172

173
```python { .api }
174
class Context:
175
    def __init__(self, command: Command, **kwargs) -> None: ...
176
    def fail(self, message: str) -> NoReturn: ...
177
    def abort(self) -> NoReturn: ...
178
    def invoke(self, callback: Command | Callable, *args, **kwargs) -> Any: ...
179

180
def pass_context(f: Callable) -> Callable: ...
181
def get_current_context(silent: bool = ...) -> Context: ...
182
```
183

184
[Context Management](./context-management.md)
185

186
### Terminal User Interface
187

188
Interactive CLI elements including prompts, confirmation dialogs, progress bars, styled output, and terminal utilities for building rich command-line experiences.
189

190
```python { .api }
191
def prompt(text: str, **kwargs) -> Any: ...
192
def confirm(text: str, default: bool = ..., **kwargs) -> bool: ...
193
def progressbar(iterable=..., **kwargs): ...
194
def echo(message=..., **kwargs) -> None: ...
195
def style(text, fg=..., bg=..., bold=..., **kwargs) -> str: ...
196
```
197

198
[Terminal UI](./terminal-ui.md)
199

200
### Exception Handling
201

202
Comprehensive exception hierarchy for handling CLI errors with proper error messages, exit codes, and user feedback. Includes parameter validation errors and usage errors.
203

204
```python { .api }
205
class ClickException(Exception):
206
    def __init__(self, message: str) -> None: ...
207

208
class UsageError(ClickException):
209
    def __init__(self, message: str, ctx: Context | None = ...) -> None: ...
210

211
class BadParameter(UsageError):
212
    def __init__(self, message: str, ctx: Context | None = ..., param: Parameter | None = ...) -> None: ...
213
```
214

215
[Exception Handling](./exception-handling.md)
216

217
### Testing Support
218

219
Built-in testing framework with CLI runner, result objects, and utilities for testing CLI applications in isolation with controlled input/output.
220

221
```python { .api }
222
class CliRunner:
223
    def __init__(self, charset: str | None = ..., **kwargs) -> None: ...
224
    def invoke(self, cli: BaseCommand, args=..., **kwargs) -> Result: ...
225

226
class Result:
227
    exit_code: int
228
    output: str
229
    exception: Any
230
```
231

232
[Testing Support](./testing-support.md)
233

234
### Text Formatting
235

236
Text formatting utilities for creating well-structured help output, text wrapping, and table formatting. These functions are primarily used internally by Click but can be useful for custom help formatting.
237

238
```python { .api }
239
class HelpFormatter:
240
    def __init__(self, indent_increment: int = ..., width: int | None = ..., max_width: int | None = ...) -> None: ...
241
    def write_dl(self, rows: Iterable[Iterable[str]], col_max: int = ..., col_spacing: int = ...) -> None: ...
242
    def section(self, name: str) -> ContextManager[None]: ...
243

244
def wrap_text(text: str, width: int = ..., **kwargs) -> str: ...
245
def measure_table(rows: Iterable[Iterable[str]]) -> tuple[int, ...]: ...
246
```
247

248
[Text Formatting](./formatting.md)
249

250
## Types
251

252
### Core Classes
253

254
```python { .api }
255
class Command(BaseCommand):
256
    def __init__(self, name: str, callback: Callable | None = ..., **kwargs) -> None: ...
257

258
class Group(MultiCommand):
259
    def __init__(self, name: str | None = ..., commands: dict[str, Command] | None = ..., **kwargs) -> None: ...
260
    def add_command(self, cmd: Command, name: str | None = ...) -> None: ...
261

262
class Parameter:
263
    def __init__(self, param_decls: Iterable[str] | None = ..., **kwargs) -> None: ...
264

265
class Option(Parameter):
266
    def __init__(self, param_decls: Iterable[str] | None = ..., **kwargs) -> None: ...
267

268
class Argument(Parameter):
269
    def __init__(self, param_decls: Iterable[str] | None = ..., **kwargs) -> None: ...
270
```
271

272
## Module Constants
273

274
Click module-level constants and attributes for configuration and introspection.
275

276
```python { .api }
277
disable_unicode_literals_warning: bool
278
"""
279
Controls if click should emit warnings about unicode literals usage.
280
Set to True to suppress warnings in environments with unicode literal issues.
281

282
Usage:
283
import click
284
click.disable_unicode_literals_warning = True
285
"""
286

287
__version__: str
288
"""
289
Current version of the click library.
290

291
Usage:
292
import click
293
print(f"Click version: {click.__version__}")
294
"""
295
```