Click

好的，下面是更加详细的 Click 教程，涵盖了更多功能和示例。

1. 安装 Click

首先，你需要安装 Click 库，使用以下命令：

pip install click

2. 基本命令行工具

一个简单的 Click 命令可以用 @click.command() 来定义，并使用 click.echo() 输出信息：

import click

@click.command()
def hello():
    click.echo("Hello, Click!")

if __name__ == "__main__":
    hello()

运行这个脚本：

python script.py

输出：

Hello, Click!

3. 添加选项 (@click.option)

Click 提供了简单的方式来为命令添加选项。选项是可选的参数，可以通过命令行指定。

import click

@click.command()
@click.option('--name', default='World', help='你想打招呼的人')
def greet(name):
    click.echo(f"Hello, {name}!")

if __name__ == '__main__':
    greet()

运行命令：

python script.py --name Alice

输出：

Hello, Alice!

如果不提供 --name，会输出默认值：

Hello, World!

常见选项配置：

• default：定义选项的默认值。
• help：为选项生成帮助文本。
• required=True：强制要求提供该选项。

4. 添加参数 (@click.argument)

参数与选项不同，参数是必需的，不能省略。

@click.command()
@click.argument('name')
def greet(name):
    click.echo(f"Hello, {name}!")

if __name__ == '__main__':
    greet()

运行：

python script.py Alice

输出：

Hello, Alice!

如果不提供参数，Click 会报错：

Error: Missing argument "name".

5. 布尔选项 (is_flag=True)

通过 is_flag=True，可以创建布尔开关选项。这种选项不需要值，只需在命令行中提供选项名称。

@click.command()
@click.option('--shout', is_flag=True, help='大写字母输出')
@click.argument('name')
def greet(name, shout):
    message = f"Hello, {name}!"
    if shout:
        message = message.upper()
    click.echo(message)

if __name__ == '__main__':
    greet()

运行：

python script.py Alice --shout

输出：

HELLO, ALICE!

6. 多值选项 (nargs)

可以通过 nargs 参数接收多个值：

@click.command()
@click.argument('names', nargs=2)
def greet(names):
    click.echo(f"Hello, {names[0]} and {names[1]}!")

if __name__ == '__main__':
    greet()

运行：

python script.py Alice Bob

输出：

Hello, Alice and Bob!

7. 选项类型验证 (type)

Click 允许你指定选项的类型。例如，如果你需要整数类型的输入，可以使用 type=int：

@click.command()
@click.option('--age', type=int, help='你的年龄')
def check_age(age):
    if age < 18:
        click.echo("未成年")
    else:
        click.echo("成年")

if __name__ == '__main__':
    check_age()

运行：

python script.py --age 20

输出：

成年

8. 枚举类型

使用 click.Choice 来限制输入为特定的枚举值：

@click.command()
@click.option('--color', type=click.Choice(['red', 'blue', 'green']), help='选择一个颜色')
def choose_color(color):
    click.echo(f"你选择的颜色是: {color}")

if __name__ == '__main__':
    choose_color()

运行：

python script.py --color red

输出：

你选择的颜色是: red

9. 多命令 CLI 应用 (@click.group)

当你需要一个包含多个命令的命令行工具时，可以使用 @click.group() 组织命令。

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

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

@click.command()
def goodbye():
    click.echo("Goodbye!")

cli.add_command(hello)
cli.add_command(goodbye)

if __name__ == '__main__':
    cli()

现在可以执行以下命令：

python script.py hello

输出：

Hello!

python script.py goodbye

输出：

Goodbye!

10. 处理异常

Click 提供了异常处理的机制，你可以自定义错误提示：

@click.command()
@click.argument('name')
def greet(name):
    if name == 'error':
        raise click.ClickException('出错了！')
    click.echo(f"Hello, {name}!")

if __name__ == '__main__':
    greet()

运行：

python script.py error

输出：

Error: 出错了！

11. 环境变量支持

Click 还允许通过环境变量来获取值。你可以使用 envvar 参数指定环境变量的名称：

@click.command()
@click.option('--name', envvar='USER_NAME', help='名字')
def greet(name):
    click.echo(f"Hello, {name}!")

if __name__ == '__main__':
    greet()

运行时，如果设置了环境变量 USER_NAME，即使不传 --name 选项也会自动使用环境变量的值：

export USER_NAME=Alice
python script.py

输出：

Hello, Alice!

12. 自定义上下文对象

可以通过 @click.pass_context 传递自定义上下文对象，供多个命令共享数据：

class MyAppContext:
    def __init__(self):
        self.verbose = False

@click.group()
@click.option('--verbose', is_flag=True)
@click.pass_context
def cli(ctx, verbose):
    ctx.obj = MyAppContext()
    ctx.obj.verbose = verbose

@click.command()
@click.pass_context
def hello(ctx):
    if ctx.obj.verbose:
        click.echo("Verbose Mode: Hello!")
    else:
        click.echo("Hello!")

cli.add_command(hello)

if __name__ == '__main__':
    cli()

运行：

python script.py hello --verbose

输出：

Verbose Mode: Hello!

13. 子命令

Click 允许为命令创建子命令，可以通过嵌套 @click.group() 来实现：

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

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

@click.command()
def create_user():
    click.echo("User created!")

@click.command()
def delete_user():
    click.echo("User deleted!")

admin.add_command(create_user)
admin.add_command(delete_user)
cli.add_command(admin)

if __name__ == '__main__':
    cli()

运行：

python script.py admin create-user

输出：

User created!

14. 自动生成帮助信息

Click 会为所有命令自动生成帮助信息。只需在命令后加上 --help：

python script.py --help

输出：

Usage: script.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  hello
  goodbye

你也可以为每个命令自定义帮助文档：

@click.command(help="这是一个问候命令")
@click.option('--name', default='World', help='你想问候的人')
def hello(name):
    click.echo(f'Hello, {name}!')

运行：

python script.py hello --help

输出：

Usage: script.py hello [OPTIONS]

  这是一个问候命令

Options:
  --name TEXT  你想问候的人
  --help       Show this message and exit.

15. 点击事件链

通过 click.command() 和 click.pass_context()，你可以实现命令链功能，允许一个命令的结果传递给下一个命令。

---

这就是 Click 的详细教程，涵盖了选项、参数、异常处理、多命令支持等。如果你有任何问题或需要更详细的示例，可以告诉我！