单击命令行界面：如果未设置其他可选选项，则需要选项

Question

使用 Python click library 编写命令行界面 (CLI) 时，是否可以定义例如三个选项，其中仅当第一个（可选）未设置时才需要第二个和第三个选项？

我的用例是一个登录系统，它允许我通过 authentication token（选项 1）或通过 username（选项 2）和 [=13 进行身份验证=]（选项 3）。

如果给出了令牌，则无需检查是否定义了 username 和 password 或提示它们。否则，如果令牌被省略，则 username 和 password 成为必需的并且必须给出。

可以使用回调以某种方式完成吗？

我的入门代码当然没有反映预期的模式：

@click.command()
@click.option('--authentication-token', prompt=True, required=True)
@click.option('--username', prompt=True, required=True)
@click.option('--password', hide_input=True, prompt=True, required=True)
def login(authentication_token, username, password):
    print(authentication_token, username, password)

if __name__ == '__main__':
    login()

Answer 1

这可以通过构建一个派生自 click.Option 的自定义 class 来完成，并且 class 覆盖 click.Option.handle_parse_result() 方法，例如：

自定义 Class:

import click

class NotRequiredIf(click.Option):
    def __init__(self, *args, **kwargs):
        self.not_required_if = kwargs.pop('not_required_if')
        assert self.not_required_if, "'not_required_if' parameter required"
        kwargs['help'] = (kwargs.get('help', '') +
            ' NOTE: This argument is mutually exclusive with %s' %
            self.not_required_if
        ).strip()
        super(NotRequiredIf, self).__init__(*args, **kwargs)

    def handle_parse_result(self, ctx, opts, args):
        we_are_present = self.name in opts
        other_present = self.not_required_if in opts

        if other_present:
            if we_are_present:
                raise click.UsageError(
                    "Illegal usage: `%s` is mutually exclusive with `%s`" % (
                        self.name, self.not_required_if))
            else:
                self.prompt = None

        return super(NotRequiredIf, self).handle_parse_result(
            ctx, opts, args)

使用自定义 Class:

要使用自定义 class，请将 cls 参数传递给 click.option 装饰器，例如：

@click.option('--username', prompt=True, cls=NotRequiredIf,
              not_required_if='authentication_token')

这是如何工作的？

之所以可行，是因为 click 是一个设计良好的 OO 框架。 @click.option() 装饰器通常实例化一个 click.Option 对象，但允许使用 cls 参数覆盖此行为。因此，在我们自己的 class 中继承 click.Option 并覆盖所需的方法是一件相对容易的事情。

在这种情况下，如果 authentication-token 令牌存在，我们将超越 click.Option.handle_parse_result() 并禁用对 user/password 的需要，如果两个 user/password 都是 authentication-token 在场。

注意：此答案的灵感来自

测试代码：

@click.command()
@click.option('--authentication-token')
@click.option('--username', prompt=True, cls=NotRequiredIf,
              not_required_if='authentication_token')
@click.option('--password', prompt=True, hide_input=True, cls=NotRequiredIf,
              not_required_if='authentication_token')
def login(authentication_token, username, password):
    click.echo('t:%s  u:%s  p:%s' % (
        authentication_token, username, password))

if __name__ == '__main__':
    login('--username name --password pword'.split())
    login('--help'.split())
    login(''.split())
    login('--username name'.split())
    login('--authentication-token token'.split())

结果：

来自 login('--username name --password pword'.split()):

t:None  u:name  p:pword

来自 login('--help'.split()):

Usage: test.py [OPTIONS]

Options:
  --authentication-token TEXT
  --username TEXT              NOTE: This argument is mutually exclusive with
                               authentication_token
  --password TEXT              NOTE: This argument is mutually exclusive with
                               authentication_token
  --help                       Show this message and exit.

Answer 2

稍微改进以具有多个互斥参数。

import click

class Mutex(click.Option):
    def __init__(self, *args, **kwargs):
        self.not_required_if:list = kwargs.pop("not_required_if")

        assert self.not_required_if, "'not_required_if' parameter required"
        kwargs["help"] = (kwargs.get("help", "") + "Option is mutually exclusive with " + ", ".join(self.not_required_if) + ".").strip()
        super(Mutex, self).__init__(*args, **kwargs)

    def handle_parse_result(self, ctx, opts, args):
        current_opt:bool = self.name in opts
        for mutex_opt in self.not_required_if:
            if mutex_opt in opts:
                if current_opt:
                    raise click.UsageError("Illegal usage: '" + str(self.name) + "' is mutually exclusive with " + str(mutex_opt) + ".")
                else:
                    self.prompt = None
        return super(Mutex, self).handle_parse_result(ctx, opts, args)

这样使用：

@click.group()
@click.option("--username", prompt=True, cls=Mutex, not_required_if=["token"])
@click.option("--password", prompt=True, hide_input=True, cls=Mutex, not_required_if=["token"])
@click.option("--token", cls=Mutex, not_required_if=["username","password"])
def login(ctx=None, username:str=None, password:str=None, token:str=None) -> None:
    print("...do what you like with the params you got...")

Answer 3

这里还有一个变体，其中有not_required_if must be specified with the snake_case variant, required is used rather than prompt,重要的是，如果其他参数通过环境变量传递，它就可以工作而不是在命令行上使用 ctx.command.get_params(...) 和 param.consume_value(...):

import click


class Mutex(click.Option):
    def __init__(self, *args, **kwargs):
        self.not_required_if: list = kwargs.pop("not_required_if")

        assert self.not_required_if, "'not_required_if' parameter required"
        kwargs["help"] = (kwargs.get("help", "") + "Option is mutually exclusive with " + ", ".join(self.not_required_if) + ".").strip()
        super(Mutex, self).__init__(*args, **kwargs)

    def handle_parse_result(self, ctx, opts, args):
        current_opt: bool = self.consume_value(ctx, opts)
        for other_param in ctx.command.get_params(ctx):
            if other_param is self:
                continue
            if other_param.human_readable_name in self.not_required_if:
                other_opt: bool = other_param.consume_value(ctx, opts)
                if other_opt:
                    if current_opt:
                        raise click.UsageError(
                            "Illegal usage: '" + str(self.name)
                            + "' is mutually exclusive with "
                            + str(other_param.human_readable_name) + "."
                        )
                    else:
                        self.required = None
        return super(Mutex, self).handle_parse_result(ctx, opts, args)

单击命令行界面：如果未设置其他可选选项，则需要选项

Click Command Line Interfaces: Make options required if other optional option is unset

python

command-line-interface

python-click

自定义 Class:

使用自定义 Class:

这是如何工作的？

测试代码：

结果：