python - 在点击中弃用参数别名的正确方法

Question

我想弃用 click 中的参数别名(例如，从下划线切换为破折号)。有一段时间，我希望这两种表述都有效，但是当使用即将弃用的别名调用参数时抛出一个 FutureWarning。但是，我还没有找到一种方法来访问调用参数时使用的实际别名。

简而言之，我想要:

click.command()
click.option('--old', '--new')
def cli(*args, **kwargs):
    ...

在使用 --old 调用选项时发出警告，但在使用 --new 调用选项时不会发出警告。有没有一种不太依赖未记录的行为的干净方法？

我尝试向 click.option 添加回调，但它似乎是在解析选项后调用的，并且参数不包含实际使用哪个别名的信息。解决方案可能会使 click.Option 甚至 click.Command 过载，但我不知道实际解析发生在何处。

Answer 1

为了能够知道用于选择特定选项的选项名称，我建议您使用一些自定义类猴子修补选项解析器。该解决方案最终继承自 click.Option 和 click.Command:

代码:

import click
import warnings

class DeprecatedOption(click.Option):

    def __init__(self, *args, **kwargs):
        self.deprecated = kwargs.pop('deprecated', ())
        self.preferred = kwargs.pop('preferred', args[0][-1])
        super(DeprecatedOption, self).__init__(*args, **kwargs)

class DeprecatedOptionsCommand(click.Command):

    def make_parser(self, ctx):
        """Hook 'make_parser' and during processing check the name
            used to invoke the option to see if it is preferred"""

        parser = super(DeprecatedOptionsCommand, self).make_parser(ctx)

        # get the parser options
        options = set(parser._short_opt.values())
        options |= set(parser._long_opt.values())

        for option in options:
            if not isinstance(option.obj, DeprecatedOption):
                continue

            def make_process(an_option):
                """ Construct a closure to the parser option processor """

                orig_process = an_option.process
                deprecated = getattr(an_option.obj, 'deprecated', None)
                preferred = getattr(an_option.obj, 'preferred', None)
                msg = "Expected `deprecated` value for `{}`"
                assert deprecated is not None, msg.format(an_option.obj.name)

                def process(value, state):
                    """The function above us on the stack used 'opt' to
                        pick option from a dict, see if it is deprecated """

                    # reach up the stack and get 'opt'
                    import inspect
                    frame = inspect.currentframe()
                    try:
                        opt = frame.f_back.f_locals.get('opt')
                    finally:
                        del frame

                    if opt in deprecated:
                        msg = "'{}' has been deprecated, use '{}'"
                        warnings.warn(msg.format(opt, preferred),
                                      FutureWarning)

                    return orig_process(value, state)

                return process

            option.process = make_process(option)

        return parser

使用自定义类:

首先向@click.command 添加一个cls 参数，例如:

@click.command(cls=DeprecatedOptionsCommand)

然后为每个具有弃用值的选项添加 cls 和 deprecated 值，例如:

@click.option('--old1', '--new1', cls=DeprecatedOption, deprecated=['--old1'])

并且您可以选择添加一个 preferred 值，例如:

@click.option('--old2', '-x', '--new2', cls=DeprecatedOption,
              deprecated=['--old2'], preferred='-x')

这是如何运作的？

这里有两个自定义类，它们派生自两个click类。自定义 click.Command 和 click.Option。这是可行的，因为 click 是一个设计良好的 OO 框架。 @click.command() 装饰器通常实例化一个 click.Command 对象，但允许使用 cls 参数覆盖此行为。 @click.option() 的工作原理类似。因此，在我们自己的类中继承 click.Command 和 click.Option 并覆盖所需的方法是一件相对容易的事情。

在自定义 click.Option: DeprecatedOption 的情况下，我们添加了两个新的关键字属性:deprecated 和 preferred。 deprecated 是必需的，它是将被警告的命令名称列表。 preferred 是可选的，指定推荐的命令名称。它是一个字符串，默认为选项行中的最后一个命令名称。

在自定义 click.Command 的情况下:DeprecatedOptionsCommand，我们覆盖了 make_parser() 方法。这允许我们在解析器实例中修补选项解析器实例。解析器并不是真正用于像 Command 和 Option 这样的扩展，所以我们必须更有创意。

在这种情况下，解析器中的所有选项处理都通过 process() 方法。在这里，我们猴子修补那个方法，在修补的方法中，我们在堆栈帧中查找一层以找到 opt 变量，这是用于查找选项的名称。然后，如果该值在 deprecated 列表中，我们会发出警告。

此代码会进入解析器中的某些私有(private) 结构，但这不太可能成为问题。此解析器代码最后一次更改是在 4 年前。解析器代码不太可能进行重大修改。

测试代码:

@click.command(cls=DeprecatedOptionsCommand)
@click.option('--old1', '--new1', cls=DeprecatedOption,
              deprecated=['--old1'])
@click.option('--old2', '-x', '--new2', cls=DeprecatedOption,
              deprecated=['--old2'], preferred='-x')
def cli(**kwargs):
    click.echo("{}".format(kwargs))

if __name__ == "__main__":
    commands = (
        '--old1 5',
        '--new1 6',
        '--old2 7',
        '--new2 8',
        '-x 9',
        '',
        '--help',
    )

    import sys, time

    time.sleep(1)
    print('Click Version: {}'.format(click.__version__))
    print('Python Version: {}'.format(sys.version))
    for cmd in commands:
        try:
            time.sleep(0.1)
            print('-----------')
            print('> ' + cmd)
            time.sleep(0.1)
            cli(cmd.split())

        except BaseException as exc:
            if str(exc) != '0' and \
                    not isinstance(exc, (click.ClickException, SystemExit)):
                raise

结果:

Click Version: 6.7
Python Version: 3.6.3 (v3.6.3:2c5fed8, Oct  3 2017, 18:11:49) [MSC v.1900 64 bit (AMD64)]
-----------
> --old1 5
{'new1': '5', 'new2': None}
C:/Users/stephen/Documents/src/testcode/test.py:71: FutureWarning: '--old1' has been deprecated, use '--new1'
  FutureWarning)
-----------
> --new1 6
{'new1': '6', 'new2': None}
-----------
> --old2 7
{'new2': '7', 'new1': None}
C:/Users/stephen/Documents/src/testcode/test.py:71: FutureWarning: '--old2' has been deprecated, use '-x'
  FutureWarning)
-----------
> --new2 8
{'new2': '8', 'new1': None}
-----------
> -x 9
{'new2': '9', 'new1': None}
-----------
> 
{'new1': None, 'new2': None}
-----------
> --help
Usage: test.py [OPTIONS]

Options:
  --old1, --new1 TEXT
  -x, --old2, --new2 TEXT
  --help                   Show this message and exit.