参数 — 单击文档

参数

Click 支持两种类型的脚本参数：选项和参数。 命令行脚本的作者通常对何时使用 which 存在一些混淆，因此这里是差异的快速概述。 顾名思义，选项是可选的。 虽然参数在合理范围内可以是可选的，但它们的可选性受到更多限制。

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

差异

参数可以做的比选项少。 以下功能仅适用于选项：

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

另一方面，与选项不同，参数可以接受任意数量的参数。 选项只能接受固定数量的参数（默认为 1），或者可以使用 Multiple Options 多次指定。

参数类型

参数可以是不同的类型。 类型可以用不同的行为来实现，有些是开箱即用的：

str / click.STRING：

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

int / click.INT：

一个只接受整数的参数。

float / click.FLOAT：

仅接受浮点值的参数。

bool / click.BOOL

接受布尔值的参数。 这自动用于布尔标志。 字符串值“1”、“true”、“t”、“yes”、“y”和“on”转换为 True。 “0”、“false”、“f”、“no”、“n”和“off”转换为 False。

点击.UUID：

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

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

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

可以打开文件进行读取或写入。 特殊值 - 根据模式指示标准输入或标准输出。

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

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

从 Click 2.0 开始，还可以自动打开文件，在这种情况下，所有写入都会进入同一文件夹中的单独文件，完成后文件将移至原始位置。 如果修改了其他用户定期读取的文件，这将非常有用。

有关详细信息，请参阅 文件参数 。

参数

• 模式 (str) –

• 编码 (可选[str]) –

• errors (Optional[str]) –

• lazy (可选[bool]) –

• atomic (bool) –

返回类型

没有任何

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 类型，但它执行不同的检查。 首先，它不返回打开的文件句柄，而是只返回文件名。 其次，它可以执行关于文件或目录应该是什么的各种基本检查。

参数

• exists (bool) – 如果设置为 true，则文件或目录需要存在才能使该值有效。 如果这不是必需的并且文件确实不存在，那么所有进一步的检查都将被静默跳过。

• file_okay (bool) – 控制文件是否是可能的值。

• dir_okay (bool) – 控制目录是否是可能的值。

• writable (bool) – 如果为真，则执行可写检查。

• readable (bool) – 如果为真，则执行可读检查。

• resolve_path (bool) – 如果这是真的，那么在传递值之前路径被完全解析。 这意味着它是绝对的并且符号链接已解决。 它不会扩展波浪号前缀，因为这应该仅由 shell 完成。

• allow_dash (bool) – 如果设置为 True，则允许使用单个破折号来指示标准流。

• path_type (Optional[Type]) – 将传入路径值转换为此类型。 如果是 None，则保留 Python 的默认值，即 str。 用于转换为 pathlib.Path。

8.0 版本变更：允许通过 type=pathlib.Path。

6.0 版本变化： 增加了 allow_dash 参数。

class click.Choice(choices, case_sensitive=True)

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

您应该只传递选择列表或元组。 其他可迭代对象（如生成器）可能会导致令人惊讶的结果。

无论指定 case_sensitive 或任何 ctx.token_normalize_func，结果值将始终是最初传递的选项之一。

有关示例，请参阅 选择选项 。

参数

• case_sensitive (bool) – 设置为 false 使选择不区分大小写。 默认为真。

• 选择 (序列[str]) –

返回类型

没有任何

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

将 click.INT 值限制为可接受值的范围。 请参阅 范围选项 。

如果未通过 min 或 max，则在该方向上接受任何值。 如果启用了 min_open 或 max_open，则相应的边界不包含在范围内。

如果启用 clamp，超出范围的值将被限制在边界上而不是失败。

8.0 版本变更： 增加了 min_open 和 max_open 参数。

参数

• min (可选[float]) –

• max (可选[float]) –

• min_open (bool) –

• max_open (bool) –

• clamp (bool) –

返回类型

没有任何

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

将 click.FLOAT 值限制为可接受值的范围。 请参阅 范围选项 。

如果未通过 min 或 max，则在该方向上接受任何值。 如果启用了 min_open 或 max_open，则相应的边界不包含在范围内。

如果启用 clamp，超出范围的值将被限制在边界上而不是失败。 如果任一边界标记为 open，则不支持此操作。

8.0 版本变更： 增加了 min_open 和 max_open 参数。

参数

• min (可选[float]) –

• max (可选[float]) –

• min_open (bool) –

• max_open (bool) –

• clamp (bool) –

返回类型

没有任何

class click.DateTime(formats=None)

DateTime 类型将日期字符串转换为 datetime 对象。

检查的格式字符串是可配置的，但默认为一些常见的（非时区感知）ISO 8601 格式。

当指定 DateTime 格式时，您应该只传递一个列表或一个元组。 其他迭代器，如生成器，可能会导致令人惊讶的结果。

使用 datetime.strptime 处理格式字符串，因此定义了允许的格式字符串。

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

参数

格式（可选[序列[str] ]) – 日期格式字符串的列表或元组，按照它们应该被尝试的顺序。 默认为 '%Y-%m-%d'、'%Y-%m-%dT%H:%M:%S'、'%Y-%m-%d %H:%M:%S'。

自定义参数类型可以通过子类化 click.ParamType 来实现。 对于简单的情况，虽然不鼓励，但也支持传递以 ValueError 失败的 Python 函数。

参数名称

参数（选项和参数）都有一个名称，当调用带值的装饰函数时，该名称将用作 Python 参数名称。

参数只使用一个位置名称。 要在帮助文本中使用不同的名称，请参阅 截断帮助文本 。

选项可以有许多名称，可以以一两个破折号为前缀。 带有一个破折号的名称被解析为短选项，带有两个破折号的名称被解析为长选项。 如果名称没有前缀，则将其用作 Python 参数名称，而不被解析为选项名称。 否则，使用带有两个破折号前缀的名字，或者如果没有两个破折号前缀，则使用第一个带有一个破折号前缀的名字。 删除前缀并将破折号转换为下划线以获取 Python 参数名称。

实现自定义类型

要实现自定义类型，您需要继承 ParamType 类。 覆盖 convert() 方法以将值从字符串转换为正确的类型。

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

import click

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

    def convert(self, value, param, ctx):
        if isinstance(value, int):
            return value

        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(f"{value!r} is not a valid integer", param, ctx)

BASED_INT = BasedIntParamType()

name 属性是可选的，用于文档。 如果转换失败，则调用 fail()。 param 和 ctx 参数在某些情况下可能是 None，例如提示。

来自用户输入或命令行的值将是字符串，但默认值和 Python 参数可能已经是正确的类型。 自定义类型应该在顶部检查值是否已经有效并将其传递以支持这些情况。