升级到新版本

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 ,因此兼容性回调无法使用该参数。