在单击中弃用参数别名的正确方法

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

使用自定义类：

首先添加一个cls参数来@click.command喜欢：

@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列表中，我们就会发出警告。

此代码进入解析器中的一些私有结构，但这不太可能成为问题。此解析器代码上次更改是在 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.