Click Documentation Release 5.2.dev0

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

摘要

文档《Click Documentation, Release 5.2.dev0》介绍了Click，一款用于创建命令行界面的Python包。Click支持任意嵌套的命令、自动生成帮助页面，并支持运行时懒加载子命令。文档详细记录了Click的版本更新历史，包括功能增强和问题修复，如支持多命令链式调用、默认值设置、进程条渲染等。同时，文档介绍了如何通过回调实现参数校验，例如使用BadParameter错误处理无效输入，并提供了正确使用Context.invoke()的方法。此外，文档还涵盖了如何通过Choice类型限制参数选择、使用prompt实现用户输入提示等功能。

AI总结

以下是对《Click Documentation Release 5.2.dev0》文档内容的简要总结：

---

### **文档概述**
Click是一款Python包，用于以最少的代码轻松创建优雅的命令行界面（CLI）。其核心特点包括：
- 支持命令任意嵌套。
- 自动生成帮助页面。
- 支持运行时懒加载子命令。

---

### **主要功能改进与变更**
#### **新增功能**
1. **内部结构改进**：Click内部重构以支持vendoring。
2. **命令链支持**：新增对多命令链的支持。
3. **默认值扩展**：支持多选项和多参数的默认值设置。
4. **进度条优化**：修复进度条渲染问题。
5. **错误处理增强**：新增主方法独立模式禁用功能，支持命令回调返回值。
6. **其他改进**：
- 增加了`open_file`方法。
- 支持结果回调和上下文多次进入的清理_deferral_。
- 优化了标准错误输出的简化打印。

#### **Bug修复**
1. **版本2.6（2014-08-11）**：
- 修复了Python 3上包装流的`seekable`属性返回错误值的问题。
2. **版本2.5（2014-07-28）**：
- 修复了Python 3上的文本包装问题。
3. **版本2.4（2014-07-04）**：
- 修复了版本2.3中帮助选项的更改问题。
4. **版本2.3（2014-07-03）**：
- 修复了计数选项的帮助记录格式问题。
- 在Windows上增加了ANSI代码剥离支持（无colorama时）。
5. **版本2.2（2014-06-26）**：
- 修复了PyPy上的TTY检测问题。
6. **版本1.1（2014-05-23）**：
- 修复了Python 2中文本文件不接受本地字符串的问题。
7. **版本1.0（2014-05-21）**：
- 初始版本发布。

---

### **升级指南**
- Click尽量保持向后兼容，但某些变更可能会破坏兼容性。
- **升级至3.2**：
- `Context.invoke()`函数的使用方式发生了变更，需通过参数名传递参数，而非位置参数。
- 示例：`ctx.invoke(other_command, name_of_arg1='arg1', name_of_arg2='arg2')`。

---

### **API参考**
Click提供了丰富的装饰器和方法，包括：
- `@click.command()`：创建新的命令。
- `@click.group()`：创建命令组。
- `@click.option()`和`@click.argument()`：添加选项和参数。
- 其他工具方法：如`click.echo()`、`click.secho()`等，用于输出和格式化。

---

### **示例与用法**
文档中提供了多个示例，展示了Click的基本用法和高级功能：
1. **简单CLI程序**：

   @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)

运行示例：

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

2. **参数验证**：
使用回调函数实现自定义验证逻辑，支持抛出`UsageError`或`BadParameter`错误。

3. **选项类型**：
- **选择型选项**：使用`click.Choice`限制值的范围。
- **提示输入**：通过`prompt`参数实现用户交互。

---

### **总结**
本版本Click进一步优化了功能和性能，并修复了多个问题，提升了开发 CLI 工具的效率和体验。