参数

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

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

差异

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

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

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

参数类型

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

str / click.STRING：: 表示 unicode 字符串的默认参数类型。
int / click.INT：: 一个只接受整数的参数。
float / click.FLOAT：: 仅接受浮点值的参数。
bool / click.BOOL: 接受布尔值的参数。这自动用于布尔标志。如果与字符串值一起使用 1、yes、y、t 和 true 转换为 True 和 [ X113X]、no、n、f和false转换为False。
点击.UUID：: 接受 UUID 值的参数。这不是自动猜测的，而是表示为 uuid.UUID。

class click.File(mode: str = 'r', encoding: Optional[str] = None, errors: Optional[str] = 'strict', lazy: Optional[bool] = None, atomic: bool = False)

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

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

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

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

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

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

class click.Path(exists: bool = False, file_okay: bool = True, dir_okay: bool = True, writable: bool = False, readable: bool = True, resolve_path: bool = False, allow_dash: bool = False, path_type: Optional[Type] = None)

路径类型类似于 File 类型，但它执行不同的检查。首先，它不返回打开的文件句柄，而是只返回文件名。其次，它可以执行关于文件或目录应该是什么的各种基本检查。

参数

exists – 如果设置为 true，则文件或目录需要存在才能使此值有效。如果这不是必需的并且文件确实不存在，那么所有进一步的检查都会被悄悄地跳过。
file_okay – 控制文件是否是可能的值。
dir_okay – 控制目录是否是可能的值。
writable – 如果为真，则执行可写检查。
readable – 如果为真，则执行可读检查。
resolve_path – 如果这是真的，那么在传递值之前路径被完全解析。这意味着它是绝对的并且符号链接已解决。它不会扩展波浪号前缀，因为这应该仅由 shell 完成。
allow_dash – 如果设置为 True，则允许使用单个破折号来指示标准流。
path_type – 将传入路径值转换为此类型。如果是 None，则保留 Python 的默认值，即 str。用于转换为 pathlib.Path。

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

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

class click.Choice(choices: Sequence[str], case_sensitive: bool = True)

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

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

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

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

参数: case_sensitive – 设置为 false 以使选择不区分大小写。默认为真。

class click.IntRange(min: Optional[float] = None, max: Optional[float] = None, min_open: bool = False, max_open: bool = False, clamp: bool = False)

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

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

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

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

class click.FloatRange(min: Optional[float] = None, max: Optional[float] = None, min_open: bool = False, max_open: bool = False, clamp: bool = False)

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

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

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

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

class click.DateTime(formats: Optional[Sequence[str]] = None)

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

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

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

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

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

参数: formats – 日期格式字符串的列表或元组，按照它们应该被尝试的顺序。默认为 '%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):
        try:
            if value[:2].lower() == "0x":
                return int(value[2:], 16)
            elif value[:1] == "0":
                return int(value, 8)
            return int(value, 10)
        except TypeError:
            self.fail(
                "expected string for int() conversion, got "
                f"{value!r} of type {type(value).__name__}",
                param,
                ctx,
            )
        except ValueError:
            self.fail(f"{value!r} is not a valid integer", param, ctx)

BASED_INT = BasedIntParamType()

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

参数 — 单击文档

参数

差异

参数类型

参数名称

实现自定义类型