参数

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='r', encoding=None, errors='strict', lazy=None, atomic=False)

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

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

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

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

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

见 文件参数 更多信息。

参数:

  • mode (str) --

  • encoding (str | None) --

  • errors (str | None) --

  • lazy (bool | None) --

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

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

参数:

  • exists (bool) -- 要使该值有效，文件或目录必须存在。如果未将其设置为 True ，并且该文件不存在，则会以静默方式跳过所有进一步检查。

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

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

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

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

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

  • resolve_path (bool) -- 将该值设为绝对值并解析所有符号链接。一个 ~ 不会展开，因为这应该只由Shell程序来完成。

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

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

Changelog

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

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

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

class click.Choice(choices, case_sensitive=True)

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

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

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

见 选择选项 举个例子。

参数:

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

  • choices (cabc.Sequence[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 启用时，范围外的值将被钳制到边界，而不是失败。

Changelog

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

参数:
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 .

Changelog

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

参数:
class click.DateTime(formats=None)

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

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

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

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

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

参数:

formats (cabc.Sequence[str] | None) -- 日期格式字符串的列表或元组，按尝试的顺序排列。默认为 '%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):
        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参数可能已经是正确的类型。自定义类型应该在顶部检查该值是否已经有效，并将其传递以支持这些情况。