参数类型

当使用设置参数类型时 type ，Click将利用该类型让您的生活更轻松，例如将数据添加到您的帮助页面。大多数示例都是使用选项完成的，但类型可用于选项和参数。

内置类型示例

选择

有时，您希望将参数作为值列表的选择。在这种情况下，您可以使用 Choice 类型. 它可以用有效值列表实例化。 将返回最初传递的选择，而不是命令行上传递的字符串。 代币规范化功能和 case_sensitive=False 可以导致两者不同但仍然匹配。 Choice.normalize_choice() 的位置更佳

示例：

import enum

class HashType(enum.Enum):
    MD5 = enum.auto()
    SHA1 = enum.auto()

@click.command()
@click.option('--hash-type',
              type=click.Choice(HashType, case_sensitive=False))
def digest(hash_type: HashType):
    click.echo(hash_type)

它看起来是什么样子：

$ digest --hash-type=MD5

$ digest --hash-type=md5

$ digest --hash-type=foo

$ digest --help

任何可迭代项都可以传递给 Choice .如果 Enum 则enum成员的名称将被用作有效选择。

选择与具有以下功能的选项一起工作 multiple=True .如果 default 值是用 multiple=True ，它应该是有效选择的列表或元组。

规范化后的选择应该是唯一的，请参阅 Choice.normalize_choice() 的位置更佳

Changelog

在 7.1 版本发生变更: 选项的结果值将始终是最初传递的选择之一，无论 case_sensitive .

Int和Float范围

的 IntRange 类型扩展了 INT 类型以确保该值包含在给定范围中。的 FloatRange 类型对于 FLOAT .

如果 min 或 max 被省略，那一边是 unbounded .该方向的任何价值观都是被接受的。默认情况下，这两个边界都是 closed ，这意味着边界值包含在可接受的范围内。 min_open 和 max_open 可用于将该边界从范围中排除。

如果 clamp 模式被启用时，范围之外的值被设置为边界而不是失败。例如数据 0, 5 会回来 5 的价值 10 ，或者 0 的价值 -1 .当使用 FloatRange , clamp 只有当两个边界都是时才能启用 closed (the默认）。

@click.command()
@click.option("--count", type=click.IntRange(0, 20, clamp=True))
@click.option("--digit", type=click.IntRange(0, 9))
def repeat(count, digit):
    click.echo(str(digit) * count)

$ repeat --count=100 --digit=5
55555555555555555555
$ repeat --count=6 --digit=12
Usage: repeat [OPTIONS]
Try 'repeat --help' for help.

Error: Invalid value for '--digit': 12 is not in the range 0<=x<=9.

内置类型列表

支持的参数 类型 是：

• str / click.STRING ：默认参数类型，指示unicode字符串。

• int / click.INT ：仅接受integer的参数。

• float / click.FLOAT ：仅接受浮点值的参数。

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

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

• class click.Choice(choices, case_sensitive=True)

  选择类型允许针对固定的支持值集检查值。所有这些值都必须是字符串。

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

  产生的值始终是最初传递的选择之一，无论 case_sensitive 或任何 ctx.token_normalize_func 正在指定。

  看到 选择 举个例子。

  参数:

  • case_sensitive (bool) -- 设置为假以使选择不区分大小写。完全正确。

  • choices (Sequence[str])

• class click.DateTime(formats=None)

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

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

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

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

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

  参数:

  formats (Sequence[str] | None) -- 日期格式字符串的列表或数组，按照尝试它们的顺序。默认为 '%Y-%m-%d' , '%Y-%m-%dT%H:%M:%S' , '%Y-%m-%d %H:%M:%S' .

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

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

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

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

  的 lazy 标记控制是否应立即打开文件还是在第一次IO时打开文件。默认情况是对于标准输入和输出流以及打开以读取的文件来说是非懒惰的， lazy 否则。当懒惰地打开文件进行读取时，它仍然会暂时打开以进行验证，但直到第一次IO才会保持打开状态。lazy主要在打开写入时有用，以避免在需要之前创建文件。

  文件也可以原子打开，在这种情况下，所有写入都会进入同一文件夹中的单独文件，完成后，文件将被移动到原始位置。 如果其他用户定期读取的文件被修改，这很有用。

  看到 文件参数 for more information.

  Changelog

  在 2.0 版本发生变更: 添加了 atomic 参数.

  参数:

  • mode (str)

  • encoding (str | None)

  • errors (str | None)

  • lazy (bool | None)

  • atomic (bool)

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

  限制一 click.FLOAT 值到一系列可接受的值。看到 Int和Float范围 .

  如果 min 或 max 不传递，则在该方向上接受任何值。如果 min_open 或 max_open 则相应的边界不包括在范围中。

  如果 clamp 启用时，范围外的值将被限制到边界而不是失败。如果标记了任何一个边界，则不支持此操作 open .

  Changelog

  在 8.0 版本发生变更: 添加了 min_open 和 max_open 参数

  参数:

  • min (float | None)

  • max (float | None)

  • min_open (bool)

  • max_open (bool)

  • clamp (bool)

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

  限制 click.INT 值到一系列可接受的值。看到 Int和Float范围 .

  如果 min 或 max 不传递，则在该方向上接受任何值。如果 min_open 或 max_open 则相应的边界不包括在范围中。

  如果 clamp 启用时，范围外的值将被限制到边界而不是失败。

  Changelog

  在 8.0 版本发生变更: 添加了 min_open 和 max_open 参数

  参数:

  • min (float | None)

  • max (float | None)

  • min_open (bool)

  • max_open (bool)

  • clamp (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, executable=False)

  的 Path 类型类似于 File 类型，但返回文件名而不是打开的文件。可以启用各种检查来验证文件类型和权限。

  参数:

  • exists (bool) -- 文件或目录需要存在才能使值有效。如果未设置为 True ，并且该文件不存在，则所有进一步的检查都会自动跳过。

  • file_okay (bool) -- 允许文件作为值。

  • dir_okay (bool) -- 允许目录作为值。

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

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

  • executable (bool) -- 如果为真，则执行可执行检查。

  • resolve_path (bool) -- 使值为绝对值并解析任何符号链接。一 ~ 没有扩展，因为这应该只由shell完成。

  • allow_dash (bool) -- 允许单个破折号作为值，这指示标准流（但不会打开它）。使用 open_file() 以处理打开此值。

  • path_type (Type[Any] | None) -- 将输入路径值转换为此类型。如果 None ，保留Python的默认值，即 str .转换为有用 pathlib.Path .

  在 8.1 版本发生变更: 添加了 executable 参数.

  Changelog

  在 8.0 版本发生变更: 允许通过 path_type=pathlib.Path .

  在 6.0 版本发生变更: 添加了 allow_dash 参数.

如何实现自定义类型

要实现自定义类型，您需要将 ParamType 课对于简单的情况，传递失败的Python函数 ValueError 尽管不鼓励，但也得到了支持。覆盖 convert() 方法将值从字符串转换为正确的类型。

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

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参数可能已经是正确的类型。自定义类型应该在顶部检查该值是否已经有效，并将其传递以支持这些情况。