升级到新版本¶
Click尝试向后兼容的最高级别,但有时这并不完全可能。如果我们需要打破向后兼容性,本文档将向您提供有关如何正确升级或处理向后兼容性的信息。
升级到7.0¶
从修饰函数中取其名称的命令现在将下划线替换为破折号。例如,Python函数 run_server
将获得命令名 run-server
现在。有几个选项可以解决这个问题:
若要继续新行为,请将依赖项固定到
Click>=7
并更新任何文档以使用破折号。要保持现有行为,请添加一个带有下划线的显式命令名,如
@click.command("run_server")
.如果找不到带下划线的名称,请传递一个
token_normalize_func
根据上下文:def normalize(name): return name.replace("_", "-") @click.group(context_settings={"token_normalize_func": normalize}) def group(): ... @group.command() def run_server(): ...
升级到3.2¶
Click3.2必须对多命令执行两次更改,这是由Click2和Click3之间的更改触发的,其结果比预期的要大。
上下文调用¶
Click3.2包含 Context.invoke()
与其他命令一起使用时的函数。这个函数的最初目的是调用另一个命令,就像它来自命令行一样,当它被传递给上下文对象而不是函数时。这种使用在以前的文档中只有一处记录,而在API文档中没有对这种方法的适当解释。
核心问题是,在3.2之前,这一呼吁违背了意图:
ctx.invoke(other_command, 'arg1', 'arg2')
这从未打算起作用,因为它不允许Click操作参数。考虑到这个模式从来没有被记录下来,而且是无意的,在错误修复版本中做出了改变这个行为的决定,然后它意外地传播,开发人员依赖它。
对上述命令的正确调用如下:
ctx.invoke(other_command, name_of_arg1='arg1', name_of_arg2='arg2')
这还允许我们修复此函数未正确处理默认值的问题。
多命令链接API¶
Click3介绍的多命令链接。这需要更改Click内部分派的方式。不幸的是,这个更改没有正确实现,并且似乎可以提供一个API,它可以通知super命令将调用的所有子命令。
然而,这种假设并不适用于过去给出的一种API保证。因此,该功能已在3.2中删除,因为它已被破坏。而是 Context.invoked_subcommand
属性已还原。
如果您确实需要知道将调用哪些确切的命令,有不同的方法来处理这一问题。第一种方法是让子命令返回所有函数,然后调用 Context.resultcallback()
.
升级到2.0¶
click 2.0有一个中断更改,即参数回调的签名。在2.0之前,回调是用 (ctx, value)
而现在 (ctx, param, value)
. 这一变化是必要的,因为它使重新使用回调变得过于复杂。
要简化转换,Click将仍然接受旧的回调。从click 3.0开始,它将向stderr发出警告,鼓励您升级。
如果要同时支持click 1.0和click 2.0,可以制作一个简单的修饰器来调整签名:
import click
from functools import update_wrapper
def compatcallback(f):
# Click 1.0 does not have a version string stored, so we need to
# use getattr here to be safe.
if getattr(click, '__version__', '0.0') >= '2.0':
return f
return update_wrapper(lambda ctx, value: f(ctx, None, value), f)
有了这个助手,你就可以这样写:
@compatcallback
def callback(ctx, param, value):
return value.upper()
请注意,由于click 1.0没有传递参数,因此 param 这里的论点是 None ,因此兼容性回调无法使用该参数。