Click Documentation Release 2.6

• 语言: 英语
• 格式: .pdf
• 来源: click.palletsprojects.com

摘要

文档介绍了Click，一个用于创建命令行界面的Python包。Click提供了一种组合式的方式，通过简单的代码实现命令行工具的快速创建，支持自动生成帮助页面、子命令的运行时懒加载和命令的任意嵌套。文档中展示了多个示例，包括命令和选项的定义、用户输入的处理以及帮助页面的自动生成。同时，文档还记录了Click的版本更新日志，涵盖了2.3到2.6版本之间的Bug修复和功能改进。Click通过装饰器来定义命令工具，支持参数的自动化处理，包括参数验证、输入提示和确认提示。

AI总结

《Click Documentation Release 2.6》是关于Python包Click的文档，Click是一个用于创建命令行界面的工具，旨在让开发者快速、轻松地构建功能丰富的CLI工具，同时避免传统方法中的麻烦。以下是文档的核心内容总结：

---

### Click 简介
- **Click** 是一个Python包，用于以可组合的方式创建美观的命令行界面（CLI），代码量最少。
- **核心特点**：
- 支持命令的任意嵌套。
- 自动生成帮助页。
- 运行时支持懒加载子命令。
- **默认配置**：Click高度可定制，且默认设置合理，能快速上手。

---

### Click 的使用
1. **基本commands**：
- 通过装饰器`@click.command()`将函数转换为命令行工具。
- 示例：

     @click.command()
     def hello():
         click.echo('Hello World!')

- 运行结果：

     $ hello
     Hello World!

2. **选项（Options）**：
- 使用`@click.option()`装饰器定义选项。
- 示例：

     @click.command()
     @click.option('--count', default=1, help='Number of greetings.')
     @click.option('--name', prompt='Your name', help='The person to greet.')
     def hello(count, name):
         for x in range(count):
             click.echo('Hello %s!' % name)

- 运行结果：

     $ hello --count=3
     Your name: John
     Hello John!
     Hello John!
     Hello John!

3. **参数（Arguments）**：
- 使用`@click.argument()`装饰器定义参数。
- 示例：

     @click.command()
     @click.argument('filename')
     def touch(filename):
         click.echo(filename)

- 运行结果：

     $ touch foo.txt
     foo.txt

4. **用户输入**：
- 支持通过`prompt()`函数手动询问用户输入，支持类型验证。

     value = click.prompt('Please enter a valid integer', type=int)

- 确认提示：`confirm()`函数用于确认操作。

     if click.confirm('Do you want to continue?'):
         click.echo('Well done!')

5. **命令组（Command Groups）**：
- 使用`@click.group()`装饰器定义命令组。
- 示例：

     @click.group()
     def cli():
         pass

     @cli.command()
     def init():
         click.echo('Initializing repository.')

6. **帮助文档**：
- Click自动生成帮助页，文本内容基于函数的docstring。
- 示例：

     @click.command()
     @click.option('--count', default=1, help='Number of greetings.')
     def hello(count):
         """This script prints hello NAME COUNT times."""

- 运行结果：

     $ hello --help
     Usage: hello [OPTIONS] NAME
     This script prints hello NAME COUNT times.
     Options:
       --count INTEGER  number of greetings
       --help           Show this message and exit.

---

### 高级功能
1. **参数验证**：
- 使用回调函数验证参数格式。
- 示例：

     def validate_rolls(ctx, param, value):
         try:
             rolls, dice = map(int, value.split('d', 2))
             return (dice, rolls)
         except ValueError:
             raise click.BadParameter('rolls need to be in format NdM')
     
     @click.command()
     @click.option('--rolls', callback=validate_rolls, default='1d6')
     def roll(rolls):
         click.echo('Rolling a %d-sided dice %d time(s)' % rolls)

2. **自定义帮助**：
- 支持通过`short_help`参数自定义命令的简短帮助信息。
- 支持禁止文本重排，例如在帮助文档中添加`\b`禁用重排。

3. **上下文设置**：
- 可以通过`context_settings`自定义-help选项的名称等。

---

### 版本更新
- **Version 2.6**：
- 修复了Python 3上wrapped streams的seekable值报告问题。
- **Version 2.5**：
- 修复了Python 3上的文本换行问题。
- **Version 2.4**：
- 修复了2.3版本中help选项的格式问题。
- **Version 2.3**：
- 修复了count选项的帮助记录格式问题。
- 在Windows上支持ANSI代码剥离（如果没有colorama）。
- 恢复Click 1.0中对help参数的边缘案例处理。

---

### 总结
Click是一个功能强大且易用的Python包，支持快速创建命令行工具，并提供丰富的功能，如参数验证、用户输入提示、命令组、自动帮助生成等。文档涵盖了基础使用、进阶功能以及版本更新内容，适合开发者快速上手并高效构建CLI应用。