参数

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

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

差异

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

  • 自动提示输入丢失

  • 作为标志（布尔或其他）

  • 选项值可以从环境变量中提取，参数不能

  • 选项在帮助页中有完整的文档，参数没有 (this is intentional 因为参数可能太具体而无法自动记录）

另一方面，参数与选项不同，它可以接受任意数量的参数。严格来说，选项只能接受固定数量的参数（默认为1），也可以使用 多种选择方案 .

参数类型

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

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 .

click.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)

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

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

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

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

从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 -- 如果这是真的，那么在向前进传递值之前，将完全解析路径。这意味着它是绝对的，符号链接被解析。它不会扩展tilde前缀，因为这只由shell完成。

  • allow_dash -- 如果设置为 True ，允许使用一个短划线指示标准流。

  • path_type -- 将传入路径值转换为此类型。如果 None ，保留Python的默认值，即 str 。可用于转换为 pathlib.Path 。

在 8.0 版更改: 允许通过 type=pathlib.Path 。

Changelog

在 6.0 版更改: 添加了 allow_dash 参数。

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

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

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

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

见 选择选项 举个例子。

参数

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

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 物体。

选中的格式字符串是可配置的，但默认为某些常见的（不区分时区）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 也支持，尽管不鼓励。

参数名

参数（选项和参数）有一个名称，当使用值调用修饰函数时，该名称将用作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 在某些情况下，如提示。