新しいリリースへのアップグレード

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へのアップグレード

クリック3.2は、クリック2とクリック3の間の変更によってトリガーされたマルチコマンドに対して、予想よりも大きな結果をもたらす2つの変更を実行する必要がありました。

コンテキスト呼び出し

クリック3.2には、他のコマンドで使用した場合のContext.invoke()関数の修正が含まれています。この関数の本来の目的は、関数ではなくコンテキストオブジェクトが渡されたときに、コマンドラインから送信されたかのように他のコマンドを呼び出すことでした。この使用法は、以前のドキュメントの1つの場所にのみ記載されており、APIドキュメントのメソッドに関する適切な説明はありませんでした。

中心的な問題は、3.2より前では、この呼び出しが意図に反して機能したことです。

ctx.invoke(other_command, 'arg1', 'arg2')

Clickがパラメータを操作できないため、これは機能することを意図したものではありませんでした。このパターンが文書化されておらず、意図的に悪かったことを考えると、バグ修正リリースでこの動作を変更することが決定されたのは、偶然に広まり、開発者がそれに依存する前です。

上記のコマンドの正しい呼び出しは次のとおりです。

ctx.invoke(other_command, name_of_arg1='arg1', name_of_arg2='arg2')

これにより、デフォルトがこの関数によって適切に処理されないという問題を修正することもできました。

マルチコマンドチェーンAPI

クリック3で導入されたマルチコマンドチェーン。これには、Clickが内部的にディスパッチする方法を変更する必要がありました。残念ながら、この変更は正しく実装されておらず、呼び出されるすべてのサブコマンドについてスーパーコマンドに通知できるAPIを提供できるようでした。

ただし、この仮定は、過去に提供されたAPI保証の1つでは機能しません。そのため、この機能はすでに壊れていたため、3.2で削除されました。代わりに、Context.invoked_subcommand属性の誤って壊れた機能が復元されました。

どの正確なコマンドが呼び出されるかを知る必要がある場合は、これに対処するさまざまな方法があります。 1つ目は、サブコマンドすべてに関数を返させてから、Context.resultcallback()の関数を呼び出すことです。

2.0へのアップグレード

Click 2.0には、パラメータコールバックのシグネチャである重大な変更が1つあります。 2.0より前は、コールバックは(ctx, value)で呼び出されていましたが、現在は(ctx, param, value)です。この変更は、コールバックの再利用が複雑になりすぎるために必要でした。

移行を容易にするために、Clickは引き続き古いコールバックを受け入れます。 Click 3.0以降、アップグレードを促す警告がstderrに発行され始めます。

Click1.0とClick2.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 になり、互換性コールバックはその引数を使用できなかったことに注意してください。

新しいリリースへのアップグレード—ドキュメントをクリックします

目次