参数 — 单击文档

来自菜鸟教程
Click/docs/6.x/parameters
跳转至:导航、​搜索

参数

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

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

差异

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

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

另一方面,与选项不同,参数可以接受任意数量的参数。 选项只能接受固定数量的参数(默认为 1)。


参数类型

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

str / click.STRING
表示 unicode 字符串的默认参数类型。
int / click.INT
一个只接受整数的参数。
float / click.FLOAT
仅接受浮点值的参数。
bool / click.BOOL
接受布尔值的参数。 这自动用于布尔标志。 如果与字符串值一起使用 1yesytrue 转换为 True 和 0、[ X113X]、nfalse 转换为 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 值限制为可接受值的范围。 请参阅 范围选项

如果未通过 minmax,则在该方向上接受任何值。 如果启用了 min_openmax_open,则相应的边界不包含在范围内。

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

8.0 版本变更: 增加了 min_openmax_open 参数。

自定义参数类型可以通过子类化 click.ParamType 来实现。 对于简单的情况,虽然不鼓励,但也支持传递以 ValueError 失败的 Python 函数。


参数名称

参数(选项和参数)接受许多作为参数声明的位置参数。 每个带有一个破折号的字符串都被添加为短参数; 每个字符串以双破折号开头。 如果添加的字符串没有任何破折号,则它成为内部参数名称,也用作变量名称。

如果没有给参数指定一个不带破折号的名称,则会通过采用最长的参数并将所有破折号转换为下划线来自动生成一个名称。 对于带有 ('-f', '--foo-bar') 的选项,参数名称为 foo_bar。 对于带有 ('-x',) 的选项,参数为 x。 对于带有 ('-f', '--filename', 'dest') 的选项,该参数称为 dest。


实现自定义类型

要实现自定义类型,您需要继承 ParamType 类。 类型可以在有或没有上下文和参数对象的情况下被调用,这就是为什么它们需要能够处理这个问题。

下面的代码实现了一个整数类型,除了普通整数之外还接受十六进制和八进制数,并将它们转换为常规整数:

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 ValueError:
            self.fail('%s is not a valid integer' % value, param, ctx)

BASED_INT = BasedIntParamType()

如您所见,子类需要实现 ParamType.convert() 方法并可选择提供 ParamType.name 属性。 后者可用于文档目的。