快速启动¶

安装¶

从PyPI安装：：

pip install click

强烈建议安装到虚拟环境中。我们建议 Virtualenv .

示例¶

Click应用程序的一些独立示例与Click一起打包。它们可在 examples folder 回购的。

inout ：一个非常简单的应用程序示例，可以从文件中读取和写入文件，还可以接受来自stdin或写入stdout的输入。
validation ：以不同方式执行参数自定义验证的应用程序的简单示例。
naval ：港口 docopt 海军例子。
colors ：将文本着色的简单示例。在Windows上使用colorama。
aliases ：实现的高级示例命令别名 .
imagepipe ：一个实现一些的复杂示例命令管道 .它将图像处理指令链接在一起。需要枕头。
repo ：实现类似Git-/Mercurial命令行界面的高级示例。
complex ：一个非常高级的示例，实现从插件文件夹动态加载子命令。
termui ：一个简单的示例，展示了单击提供的终端UI助手。

基本概念-创建命令¶

单击基于通过修饰符声明命令。在内部，高级用例有一个非修饰接口，但不鼓励高级使用。

通过将函数修饰为单击命令行工具 click.command() . 最简单的是，用这个修饰器修饰一个函数就可以使它成为一个可调用的脚本：

import click

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

发生的是，修饰符将函数转换为 Command 然后可以调用它：

if __name__ == '__main__':
    hello()

看起来像是：

$ python hello.py
Hello World!

以及相应的帮助页面：

$ python hello.py --help
Usage: hello.py [OPTIONS]

Options:
  --help  Show this message and exit.

回响¶

为什么这个例子使用 echo() 而不是普通的 print() 功能？这个问题的答案是Click试图始终如一地支持不同的环境，并且即使在环境配置错误的情况下也非常健壮。Click希望至少在一个基本的层次上具有功能性，即使一切都被完全破坏了。

这意味着 echo() 函数在终端配置错误的情况下应用一些纠错，而不是死于 UnicodeError 。

ECHO功能还支持输出中的颜色和其他样式。如果输出流是文件，它将自动删除样式。在Windows上，Colorama会自动安装和使用。看见 ANSI颜色。

如果不需要，也可以使用 print() 结构/功能。

嵌套命令¶

命令可以附加到其他类型的命令 Group . 这允许任意嵌套脚本。例如，下面的脚本实现了两个用于管理数据库的命令：

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

@click.command()
def initdb():
    click.echo('Initialized the database')

@click.command()
def dropdb():
    click.echo('Dropped the database')

cli.add_command(initdb)
cli.add_command(dropdb)

如你所见， group() 装饰工的工作方式 command() 但创建了一个 Group 对象，它可以被赋予可以附加的多个子命令 Group.add_command() .

对于简单的脚本，还可以使用 Group.command() 改为装饰。上面的脚本可以这样编写：

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

@cli.command()
def initdb():
    click.echo('Initialized the database')

@cli.command()
def dropdb():
    click.echo('Dropped the database')

然后您将调用 Group 在您的入口点或其他调用中：

if __name__ == '__main__':
    cli()

稍后注册命令¶

而不是使用 @group.command() 装饰器，命令可以用素色装饰 @click.command() 装潢师，后来在一个小组注册 group.add_command() . 这可以用于将命令拆分为多个Python模块。

@click.command()
def greet():
    click.echo("Hello, World!")

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

group.add_command(greet)

添加参数¶

要添加参数，请使用 option() 和 argument() 装饰者：

@click.command()
@click.option('--count', default=1, help='number of greetings')
@click.argument('name')
def hello(count, name):
    for x in range(count):
        click.echo(f"Hello {name}!")

它是什么样子的：

$ python hello.py --help
Usage: hello.py [OPTIONS] NAME

Options:
  --count INTEGER  number of greetings
  --help           Show this message and exit.

切换到入口点¶

在您到目前为止编写的代码中，文件末尾有一个块，如下所示： if __name__ == '__main__': 。这是传统上独立的Python文件的外观。有了Click，你可以继续这样做，但更好的方法是将你的应用程序打包成一个入口点。

有两个主要（以及更多）原因：

第一个是安装程序会自动为Windows生成可执行包装，因此您的命令行实用程序也可以在Windows上运行。

第二个原因是，入口点脚本可以在Unix上与Virtualenv一起工作，而不必激活Virtualenv。这是一个非常有用的概念，它允许您将脚本与所有需求捆绑到一个虚拟环境中。

Click可以很好地处理这一点，事实上，文档的其余部分将假定您正在将应用程序编写为分布式包。

看看这个包装入口点在阅读其余章节之前，示例假定您将使用入口点。