Question

Click 支持两种类型的脚本参数：选项和参数。在命令行脚本的作者中，关于何时使用哪个命令行脚本通常会有一些混淆，因此这里简要概述了这些区别。顾名思义，选项是可选的。虽然在理性中参数可以是可选的，但在可选性方面它们受到了更大的限制。

为了帮助您在选项和参数之间做出决定，建议将参数专门用于诸如转到子命令或输入文件名/URL 之类的事情，并将其他所有内容都作为选项。

差异

参数的作用不能小于选项。以下功能仅可用于选项：

• 自动提示输入丢失
• 作为标志（布尔或其他）
• 选项值可以从环境变量中提取，参数不能
• 选项完全记录在帮助页面中，参数不是（这是故意的，因为参数可能太具体，无法自动记录）

另一方面，与选项不同，参数可以接受任意数量的参数。选项只能严格接受固定数量的参数（默认为 1）。

参数类型

参数可以是不同的类型。可以使用不同的行为实现类型，并且一些类型是开箱即用支持的：

str / click.STRING ：

表示 Unicode 字符串的默认参数类型。

int / click.INT ：

只接受整数的参数。

float / click.FLOAT ：

只接受浮点值的参数。

bool / click.BOOL ：

接受布尔值的参数。这将自动用于布尔标志。如果与字符串值一起使用 1 ， yes ， y ， t 和 true 转换为 True 和 0 ， no ， n ， f 和 false 转换为 False .

click.UUID ：

接受 UUID 值的参数。这不是自动猜测，而是表示为 uuid.UUID .

class click.File (mode='r', encoding=None, errors='strict', lazy=None, atomic=False)

将参数声明为用于读取或写入的文件。上下文关闭后（命令完成工作后），文件将自动关闭。

可以打开文件进行读写。特殊价值 - 根据模式指示 stdin 或 stdout。

默认情况下，打开文件是为了读取文本数据，但也可以以二进制模式打开或写入。编码参数可用于强制特定编码。

这个 lazy 标志控制是否应立即或在第一个 IO 时打开文件。对于标准输入和输出流以及为读取而打开的文件，默认值为非惰性。 lazy 否则。当延迟打开一个文件进行读取时，它仍会临时打开进行验证，但直到第一个 IO 时才会保持打开状态。lazy 主要用于打开进行写入，以避免在需要之前创建文件。

从 click 2.0 开始，文件也可以自动打开，在这种情况下，所有的写操作都将进入同一文件夹中的一个单独的文件，完成后，文件将移到原始位置。如果修改了其他用户定期读取的文件，则此功能非常有用。

见 文件参数 更多信息。

class click.Path (exists=False, file_okay=True, dir_okay=True, writable=False, readable=True, resolve_path=False, allow_dash=False, path_type=None)

路径类型与 File 但它执行不同的检查。首先，它不返回打开的文件句柄，只返回文件名。其次，它可以对文件或目录进行各种基本检查。

在 6.0 版更改: allow_dash 加入。

参数

• exists -- 如果设置为 true，则该文件或目录需要存在才能使该值有效。如果这不是必需的，并且文件确实不存在，那么将自动跳过所有进一步的检查。
• file_okay -- 控制文件是否为可能值。
• dir_okay -- 控制目录是否为可能值。
• writable -- 如果为真，则执行可写检查。
• readable -- 如果为真，则执行可读检查。
• resolve_path -- 如果这是真的，那么在向前进传递值之前，将完全解析路径。这意味着它是绝对的，符号链接被解析。它不会扩展 tilde 前缀，因为这只由 shell 完成。
• allow_dash -- 如果设置为 True ，允许使用一个短划线指示标准流。
• path_type -- （可选）应用于表示路径的字符串类型。默认值为 None 这意味着返回值可以是字节，也可以是 Unicode，这取决于 Click 处理的输入数据最有意义的是什么。

class click.Choice (choices, case_sensitive=True)

选项类型允许根据一组固定的支持值检查值。所有这些值都必须是字符串。

您应该只传递选项列表或元组。其他 iTerables（如发电机）可能会产生令人惊讶的结果。

见 选择选项 举个例子。

参数

case_sensitive -- 设置为 false 可使选项不区分大小写。默认为 true。

class click.IntRange (min=None, max=None, clamp=False)

工作原理类似于 click.INT 但限制该值适应范围。如果值超出范围，默认行为将失败，但也可以在两条边之间静默夹持。

见 范围选项 举个例子。

class click.FloatRange (min=None, max=None, clamp=False)

工作原理类似于 click.FLOAT 但限制该值适应范围。如果值超出范围，默认行为将失败，但也可以在两条边之间静默夹持。

见 范围选项 举个例子。

class click.DateTime (formats=None)

日期时间类型将日期字符串转换为 datetime 物体。

选中的格式字符串是可配置的，但默认为某些常见的（不区分时区）ISO 8601 格式。

指定时 DateTime 格式化时，只应传递一个列表或一个元组。其他的 iTerables，如发电机，可能会导致令人惊讶的结果。

格式字符串使用 datetime.strptime 从而定义允许的格式字符串。

按顺序尝试使用每种格式进行分析，并使用成功分析的第一种格式。

参数

formats -- 日期格式字符串的列表或元组，按尝试的顺序排列。默认为 '%Y-%m-%d' ， '%Y-%m-%dT%H:%M:%S' ， '%Y-%m-%d %H:%M:%S' .

自定义参数类型可以通过子类化实现 click.ParamType . 对于简单的情况，传递一个在 ValueError 也支持，尽管不鼓励。

参数名

参数（选项和参数）接受作为参数传递给命令函数的多个位置参数。每个只有一个破折号的字符串都作为一个短参数添加；每个以双破折号开头的字符串都作为一个长参数添加。

如果添加的字符串没有任何破折号，则它将成为内部参数名，该参数名也用作变量名。

如果参数的所有名称都包含短划线，则会自动生成内部名称，方法是采用最长的参数并将所有短划线转换为下划线。

内部名称转换为小写。

实例：

• 对于具有 ('-f', '--foo-bar') ，参数名称为 foo_bar .
• 对于具有 ('-x',) ，参数为 x .
• 对于具有 ('-f', '--filename', 'dest') ，参数名称为 dest .
• 对于具有 ('--CamelCaseOption',) ，参数为 camelcaseoption .
• 关于 (`foogle`) ，参数名称为 foogle . 要在帮助文本中提供不同的人类可读名称，请参阅关于 截断帮助文本 .

实现自定义类型

要实现自定义类型，需要将 ParamType 类。可以使用或不使用上下文和参数对象来调用类型，这就是它们需要能够处理这一问题的原因。

下面的代码实现了一个整数类型，它除了接受普通整数外，还接受十六进制和八进制数字，并将它们转换为普通整数：

import click

class BasedIntParamType(click.ParamType):
    name = 'integer'

    def convert(self, value, param, ctx):
        try:
            if value[:2].lower() == '0x':
                return int(value[2:], 16)
            elif value[:1] == '0':
                return int(value, 8)
            return int(value, 10)
        except ValueError:
            self.fail('%s is not a valid integer' % value, param, ctx)

BASED_INT = BasedIntParamType()

如您所见，子类需要实现 ParamType.convert() 方法并可选地提供 ParamType.name 属性。后者可用于文档目的。