快速入门

您可以直接从 PyPI 获取库：

pip install click

强烈建议安装到 virtualenv 中。

虚拟环境

Virtualenv 可能是您想用于开发 Click 应用程序的工具。

virtualenv 解决了什么问题？除了 Click 脚本之外，您可能还想将它用于其他项目。但是你拥有的项目越多，你就越有可能使用不同版本的 Python 本身，或者至少是不同版本的 Python 库。让我们面对现实：库经常破坏向后兼容性，并且任何严肃的应用程序都不可能具有零依赖项。那么，如果您的两个或多个项目存在相互冲突的依赖关系，您会怎么做？

Virtualenv 来救援！ Virtualenv 支持 Python 的多个并行安装，每个项目一个。它实际上并没有安装单独的 Python 副本，但它确实提供了一种保持不同项目环境隔离的巧妙方法。让我们看看 virtualenv 是如何工作的。

如果您使用的是 Mac OS X 或 Linux：

$ pip install virtualenv --user

其中之一可能会在您的系统上安装 virtualenv。也许它甚至在你的包管理器中。如果您使用 Ubuntu，请尝试：

$ sudo apt-get install python-virtualenv

如果您使用的是 Windows（或以上方法均无效），您必须先安装 pip。有关这方面的更多信息，请参阅安装 pip。安装后，从上面运行 pip 命令，但不要带 sudo 前缀。

一旦你安装了 virtualenv，只需启动一个 shell 并创建你自己的环境。我通常在其中创建一个项目文件夹和一个 venv 文件夹：

$ mkdir myproject
$ cd myproject
$ virtualenv venv
New python executable in venv/bin/python
Installing setuptools, pip............done.

现在，每当您要处理一个项目时，只需激活相应的环境即可。在 OS X 和 Linux 上，执行以下操作：

$ . venv/bin/activate

如果您是 Windows 用户，以下命令适合您：

$ venv\scripts\activate

无论哪种方式，您现在都应该使用您的 virtualenv（请注意您的 shell 提示如何更改以显示活动环境）。

如果你想回到现实世界，请使用以下命令：

$ deactivate

这样做之后，你的 shell 的提示应该和以前一样熟悉了。

现在，让我们继续。输入以下命令以在您的 virtualenv 中激活 Click：

$ pip install click

几秒钟后，你就可以开始了。

截屏视频和示例

有一个可用的截屏视频，其中显示了 Click 的基本 API 以及如何使用它构建简单的应用程序。它还探讨了如何使用子命令构建命令。

使用 Click 构建命令行应用程序

Click 应用程序的示例可以在文档以及 GitHub 存储库以及自述文件中找到：

基本概念 - 创建命令

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

一个函数通过click.command()修饰就变成了Click命令行工具。最简单的，只要用这个装饰器装饰一个函数，它就会变成一个可调用的脚本：

发生的事情是装饰器将函数转换为 Command ，然后可以调用它：

if __name__ == '__main__':
    hello()

以及它的样子：

以及相应的帮助页面：

回声

为什么这个例子使用 echo() 而不是常规的 print() 函数？这个问题的答案是 Click 尝试一致地支持不同的环境，并且即使在环境配置错误的情况下也非常健壮。即使一切都完全坏了，Click 也希望至少在基本层面上发挥作用。

这意味着 echo() 函数会应用一些错误更正，以防终端配置错误，而不是因 UnicodeError 而死亡。

echo 函数还支持输出中的颜色和其他样式。如果输出流是文件，它将自动删除样式。在 Windows 上，会自动安装和使用 colorama。请参阅 ANSI 颜色。

如果你不需要这个，你也可以使用 print() 构造/函数。

嵌套命令

命令可以附加到类型为 Group 的其他命令。这允许脚本的任意嵌套。作为示例，这里是一个脚本，它实现了两个用于管理数据库的命令：

如您所见，group() 装饰器的工作方式类似于 command() 装饰器，但创建了一个 Group 对象，该对象可以被赋予多个子命令，这些子命令可以附有 Group.add_command()。

对于简单的脚本，也可以使用 Group.command() 装饰器来自动附加和创建命令。上面的脚本可以这样写：

然后，您将在 setuptools 入口点或其他调用中调用 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() 装饰器：

它的样子：

切换到设置工具

在您目前编写的代码中，文件末尾有一个块，如下所示：if __name__ == '__main__':。这通常是独立 Python 文件的样子。使用 Click 您可以继续这样做，但是通过 setuptools 有更好的方法。

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

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

第二个原因是 setuptools 脚本在 Unix 上与 virtualenv 一起工作，而不必激活 virtualenv。这是一个非常有用的概念，它允许您将具有所有要求的脚本捆绑到一个 virtualenv 中。

Click 非常适合使用它，事实上，文档的其余部分将假定您正在通过 setuptools 编写应用程序。

我强烈建议在阅读其余部分之前先阅读 Setuptools Integration 章节，因为示例假定您将使用 setuptools。

快速入门 — 单击文档

目录