参数

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 值设置为可接受的值范围。看见 范围选项 .

如果 minmax 不传递,则在该方向上接受任何值。如果 min_openmax_open 则相应的边界不包括在该范围内。

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

在 8.0 版更改: 增加了 min_openmax_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 值设置为可接受的值范围。看见 范围选项 .

如果 minmax 不传递,则在该方向上接受任何值。如果 min_openmax_open 则相应的边界不包括在该范围内。

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

在 8.0 版更改: 增加了 min_openmax_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() 如果转换失败。这个 paramctx 论点可能是 None 在某些情况下,如提示。