选项 — 单击文档

来自菜鸟教程
Click/docs/7.x/options
跳转至：导航、​搜索

选项

向命令添加选项可以通过 option() 装饰器来完成。 由于选项可以有各种不同的版本，因此有大量参数可以配置它们的行为。 单击中的选项与 位置参数 不同。

命名您的选项

选项的名称将在调用装饰函数时用作 Python 参数名称。 这可以从选项名称推断或明确给出。 名称作为装饰器的位置参数给出。

按以下顺序选择名称

  1. 如果名称没有前缀，则将其用作 Python 参数名称，而不是在命令行中将其视为选项名称。
  2. 如果至少有一个名称以两个破折号为前缀，则使用第一个给定的名称作为名称。
  3. 否则使用带一个破折号前缀的名字。

要获取 Python 参数名称，将所选名称转换为小写，最多删除两个破折号作为前缀，其他破折号转换为下划线。 

@click.command()
@click.option('-s', '--string-to-echo')
def echo(string_to_echo):
    click.echo(string_to_echo)
@click.command()
@click.option('-s', '--string-to-echo', 'string')
def echo(string):
    click.echo(string)
  • "-f", "--foo-bar"，名称为foo_bar
  • "-x"，名称为x
  • "-f", "--filename", "dest"，名称为dest
  • "--CamelCase"，名称为camelcase
  • "-f", "-fb"，名称为f
  • "--f", "--foo-bar"，名称为f
  • "---f"，名称为_f


基本值选项

最基本的选项是值选项。 这些选项接受一个参数，即一个值。 如果未提供类型，则使用默认值的类型。 如果未提供默认值，则假定类型为 STRING。 除非明确指定名称，否则参数名称是定义的第一个长选项； 否则使用第一个短的。 默认情况下，选项不是必需的，但是要使选项成为必需，只需将 required=True 作为参数传递给装饰器。

在命令行上：

在这种情况下，该选项的类型为 INT，因为默认值是一个整数。

要在显示命令帮助时显示默认值，请使用 show_default=True


多值选项

有时，您的选择需要多个参数。 对于选项，仅支持固定数量的参数。 这可以通过 nargs 参数进行配置。 然后将这些值存储为元组。

在命令行上：


元组作为多值选项

4.0 版中的新功能。


如您所见，通过使用 nargs 设置为特定数字，结果元组中的每个项目都属于相同类型。 这可能不是您想要的。 通常，您可能希望对元组中的不同索引使用不同的类型。 为此，您可以直接将元组指定为类型：

在命令行上：

通过使用元组文字作为类型，nargs 自动设置为元组的长度，并自动使用 click.Tuple 类型。 因此，上面的示例等效于：


多种选择

与 nargs 类似，也存在希望支持多次提供参数并记录所有值的情况——而不仅仅是最后一个。 例如，git commit -m foo -m bar 会为提交消息记录两行：foo 和 bar。 这可以通过 multiple 标志来完成：

例子：

在命令行上：

当用 multiple=True 传递 default 时，默认值必须是列表或元组，否则会被解释为单个字符的列表。 

@click.option("--format", multiple=True, default=["json"])

计数

在一些非常罕见的情况下，使用重复选项来计算整数是很有趣的。 这可以用于详细标志，例如：

在命令行上：


布尔标志

布尔标志是可以启用或禁用的选项。 这可以通过一次定义两个标志来实现，用斜杠 (/) 分隔以启用或禁用该选项。 （如果斜杠在选项字符串中，Click 会自动知道它是一个布尔标志并将隐式传递 is_flag=True。）Click 总是希望您提供启用和禁用标志，以便您可以稍后更改默认值。

例子：

在命令行上：

如果你真的不想要一个关闭开关，你可以定义一个并手动通知 Click 某物是一个标志：

在命令行上：

请注意，如果您的选项中已包含斜杠（例如，如果您使用 Windows 样式的参数，其中 / 是前缀字符），您也可以通过 ; 拆分参数：

在 6.0 版中更改。


如果只想为第二个选项定义别名，则需要使用前导空格来消除格式字符串的歧义：

例子：


功能开关

除了布尔标志，还有功能开关。 这些是通过将多个选项设置为相同的参数名称并定义一个标志值来实现的。 请注意，通过提供 flag_value 参数，Click 将隐式设置 is_flag=True。

要设置默认标志，请将值 True 分配给应为默认值的标志。

在命令行上：


选择选项

有时，您希望参数是值列表的一个选择。 在这种情况下，您可以使用 Choice 类型。 它可以使用有效值列表进行实例化。 将返回最初传递的选择，而不是在命令行上传递的 str。 令牌归一化函数和 case_sensitive=False 可以导致两者不同但仍然匹配。

例子：

它的样子：

仅将选项作为列表或元组传递。 其他可迭代对象（如生成器）可能会导致意外结果。

选择与具有 multiple=True 的选项一起使用。 如果 default 值与 multiple=True 一起给出，它应该是有效选项的列表或元组。

在考虑 case_sensitive 和任何指定的令牌归一化函数的影响后，选择应该是唯一的。

在 7.1 版更改： 无论 case_sensitive 如何，选项的结果值将始终是最初传递的选项之一。


提示

在某些情况下，您需要可以从命令行提供的参数，但如果未提供，请改为要求用户输入。 这可以通过 Click 定义提示字符串来实现。

例子：

以及它的样子：

如果您对默认提示字符串不满意，可以要求使用不同的提示字符串：

它的样子：

建议不要将 prompt 与设置为 True 的 multiple 标志结合使用。 相反，以交互方式在函数中提示。


密码提示

Click 还支持隐藏提示和要求确认。 这对于密码输入很有用：

它的样子：

因为这种参数组合很常见，所以也可以用 password_option() 装饰器替换：


提示的动态默认值

上下文的 auto_envvar_prefix 和 default_map 选项允许程序从环境或配置文件中读取选项值。 但是，这会覆盖提示机制，因此用户无法以交互方式更改值。

如果您想让用户配置默认值，但在命令行上未指定选项时仍会收到提示，您可以通过提供可调用作为默认值来实现。 例如，要从环境中获取默认值：

要描述默认值，请将其设置在 show_default 中。


回调和热切选项

有时，您需要一个参数来完全改变执行流程。 例如，当您想要一个 --version 参数打印出版本然后退出应用程序时，就是这种情况。

注意：可重用的 --version 参数的实际实现可在 Click 中作为 click.version_option() 获得。 这里的代码只是如何实现这样一个标志的一个例子。

在这种情况下，您需要两个概念：急切参数和回调。 急切参数是在其他参数之前处理的参数，回调是在处理参数之后执行的。 急切是必要的，以便较早的必需参数不会产生错误消息。 例如，如果 --version 不是急切的，并且需要一个参数 --foo 并且之前定义过，那么您需要指定它以使 --version 工作。 有关详细信息，请参阅 回调评估顺序 。

回调是使用两个参数调用的函数：当前 Context 和值。 上下文提供了一些有用的功能，例如退出应用程序并允许访问其他已处理的参数。

这是 --version 标志的示例：

expose_value 参数可防止将毫无意义的 version 参数传递给回调。 如果未指定，则将布尔值传递给 hello 脚本。 resilient_parsing 标志应用于上下文，如果 Click 想要解析命令行而没有任何会改变执行流程的破坏性行为。 在这种情况下，因为我们将退出程序，所以我们什么都不做。

它的样子：

回调签名更改

在 Click 2.0 中，回调的签名发生了变化。 有关这些更改的更多信息，请参阅 升级到 2.0。


是 参数

对于危险操作，能够要求用户确认非常有用。 这可以通过添加一个布尔值 --yes 标志并在用户未提供它并在回调中失败时要求确认来完成：

以及它在命令行上的样子：

因为这种参数组合很常见，所以也可以用 confirmation_option() 装饰器代替：

回调签名更改

在 Click 2.0 中，回调的签名发生了变化。 有关这些更改的更多信息，请参阅 升级到 2.0。


来自环境变量的值

Click 的一个非常有用的功能是除了常规参数之外，还能够接受来自环境变量的参数。 这使得工具更容易自动化。 例如，您可能希望传递带有 --config 参数的配置文件，但也支持导出 TOOL_CONFIG=hello.cfg 键值对以获得更好的开发体验。

Click 以两种方式支持这一点。 一种是自动构建仅受选项支持的环境变量。 要启用此功能，需要将 auto_envvar_prefix 参数传递给调用的脚本。 然后将每个命令和参数添加为大写下划线分隔的变量。 如果您有一个名为 run 的子命令采用名为 reload 的选项且前缀为 WEB，则变量为 WEB_RUN_RELOAD。

用法示例：

从命令行：

在命令组中使用 auto_envvar_prefix 时，命令名需要包含在环境变量中，在前缀和参数名之间，ie PREFIX_COMMAND_VARIABLE。 如果您有一个名为 run-server 的子命令采用名为 host 的选项且前缀为 WEB，则变量为 WEB_RUN_SERVER_HOST。

例子：

第二个选项是通过在选项上定义环境变量的名称来手动从特定环境变量中提取值。

用法示例：

从命令行：

在这种情况下，它也可以是选择第一个的不同环境变量的列表。


来自环境值的多个值

由于选项可以接受多个值，因此从环境变量（它们是字符串）中提取这些值有点复杂。 Click 解决此问题的方法是将其留给自定义此行为的类型。 对于 multiple 和 nargs 的值不是 1，Click 将调用 ParamType.split_envvar_value() 方法来执行拆分。

所有类型的默认实现是在空格上拆分。 此规则的例外是 File 和 Path 类型，它们都根据操作系统的路径拆分规则进行拆分。 在 Linux 和 OS X 等 Unix 系统上，拆分发生在每个冒号 (:) 上，而对于 Windows，则发生在每个分号 (;) 上。

用法示例：

从命令行：


其他前缀字符

单击可以处理选项中除 - 以外的替代前缀字符。 例如，如果您想将斜杠作为参数 / 或类似的东西处理，这很有用。 请注意，通常强烈建议不要这样做，因为 Click 希望开发人员保持接近 POSIX 语义。 但是，在某些情况下，这可能很有用：

从命令行：

请注意，如果您使用 / 作为前缀字符并且想要使用布尔标志，则需要将其与 ; 而不是 / 分开：


范围选项

应该特别提及 IntRange 类型，它的工作方式与 INT 类型非常相似，但将值限制在特定范围内（包括两端）。 它有两种模式：

  • 默认模式（非钳位模式），其中超出范围的值将导致错误。
  • 一种可选的钳制模式，其中超出范围的值将被钳制。 这意味着 0-5 的范围将返回值 10 的 5 或值 -1 的 0（例如）。

例子：

从命令行：

如果您为任何边传递 None，则意味着该范围在该侧是开放的。


验证回调

在 2.0 版本中更改。


如果要应用自定义验证逻辑，可以在参数回调中执行此操作。 如果验证不起作用，这些回调既可以修改值，也可以引发错误。

在 Click 1.0 中，您只能引发 UsageError 但从 Click 2.0 开始，您还可以引发 BadParameter 错误，这有一个额外的好处，它会自动将错误消息格式化为还包含参数名称。

例子：

以及它的样子：



取自“https://cainiaojiaocheng.com/index.php?title=Click/docs/7.x/options&oldid=20107”
Powered by MediaWiki