在点击中弃用参数别名的正确方法
Correct way to deprecate parameter alias in click
我想弃用 click 中的参数别名（例如，从下划线切换为破折号）。有一段时间，我希望这两个公式都有效，但是当使用将被弃用的别名调用参数时抛出一个 FutureWarning 。但是，我还没有找到一种方法来访问调用参数的实际别名。
总之，我要：
click.command()
click.option('--old', '--new')
def cli(*args, **kwargs):
...
在使用 --old 调用选项时发出警告，但在使用 --new 调用选项时不会发出警告。有没有一种不太依赖未记录的行为的干净方法？
我尝试向 click.option 添加回调，但它似乎是在解析选项后调用的，并且参数不包含实际使用了哪个别名的信息。解决方案可能会使 click.Option 甚至 click.Command 过载，但我不知道实际解析发生在何处。
为了能够知道 select 特定选项使用了哪个选项名称，我建议您使用一些自定义 类 猴子修补选项解析器。该解决方案最终继承自 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 列表中，我们发出警告。
此代码进入解析器中的某些 私有 结构，但这不太可能成为问题。此解析器代码最后一次更改是在 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.
我想弃用 click 中的参数别名（例如，从下划线切换为破折号）。有一段时间，我希望这两个公式都有效，但是当使用将被弃用的别名调用参数时抛出一个 FutureWarning 。但是，我还没有找到一种方法来访问调用参数的实际别名。
总之，我要：
click.command()
click.option('--old', '--new')
def cli(*args, **kwargs):
...
在使用 --old 调用选项时发出警告，但在使用 --new 调用选项时不会发出警告。有没有一种不太依赖未记录的行为的干净方法？
我尝试向 click.option 添加回调，但它似乎是在解析选项后调用的，并且参数不包含实际使用了哪个别名的信息。解决方案可能会使 click.Option 甚至 click.Command 过载，但我不知道实际解析发生在何处。
为了能够知道 select 特定选项使用了哪个选项名称，我建议您使用一些自定义 类 猴子修补选项解析器。该解决方案最终继承自 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 列表中，我们发出警告。
此代码进入解析器中的某些 私有 结构，但这不太可能成为问题。此解析器代码最后一次更改是在 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.