シェルの完成

Clickは、Bash（バージョン4.4以降）、Zsh、およびFishのタブ補完サポートを提供します。他のシェルのサポートを追加することも可能であり、提案は複数のレベルでカスタマイズできます。

シェルの完了により、コマンド名、オプション名、および選択肢、ファイル、パスのパラメータータイプの値が提案されます。オプションは、少なくともダッシュが入力されている場合にのみリストされます。非表示のコマンドとオプションは表示されません。

$ repo <TAB><TAB>
clone  commit  copy  delete  setuser
$ repo clone -<TAB><TAB>
--deep  --help  --rev  --shallow  -r

完了の有効化

完了は、pythonコマンドではなく、エントリポイントを介してスクリプトがインストールおよび呼び出された場合にのみ使用できます。 Setuptools Integration を参照してください。実行可能ファイルがインストールされたら、特別な環境変数を使用して実行可能ファイルを呼び出すと、Clickが完了モードになります。

完了を使用するには、ユーザーはシェルに特別な関数を登録する必要があります。スクリプトはシェルごとに異なり、_{PROG_NAME}_COMPLETEを{shell}_sourceに設定して呼び出すと、Clickが出力します。 {PROG_NAME}は、ダッシュがアンダースコアに置き換えられた大文字の実行可能ファイル名です。組み込みシェルは、bash、zsh、およびfishです。

プログラム名に合わせてカスタマイズされた次の手順をユーザーに提供します。これは例としてfoo-barを使用します。

evalを使用すると、シェルが開始されるたびにコマンドが呼び出されて評価されるため、シェルの応答が遅れる可能性があります。速度を上げるには、生成されたスクリプトをファイルに書き込んでから、それを入手します。事前にファイルを生成し、プログラムと一緒に配布して、ユーザーを一歩節約することができます。

シェル構成を変更した後、変更をロードするために新しいシェルを開始する必要があります。

カスタムタイプの完了

カスタム ParamType を作成するときは、その shell_complete（）メソッドをオーバーライドして、その型のパラメーターにシェル補完を提供します。このメソッドは、 CompletionItem オブジェクトのリストを返す必要があります。値に加えて、これらのオブジェクトは、シェルサポートが使用する可能性のあるメタデータを保持します。組み込みの実装では、typeを使用してパスの特別な処理を示し、helpを使用して提案の横にヘルプ文字列を表示することをサポートします。

この例では、タイプは不完全な値で始まる環境変数を提案します。

class EnvVarType(ParamType):
    def shell_complete(self, ctx, param, incomplete):
        return [
            CompletionItem(name)
            for name in os.environ if name.startswith(incomplete)
        ]

@click.command()
@click.option("--ev", type=EnvVarType())
def cli(ev):
    click.echo(os.environ[ev])

値の完了のオーバーライド

shell_complete関数を提供することにより、パラメーターの値の補完をカスタムタイプなしでカスタマイズできます。この関数は、タイプによって提供される補完の代わりに使用されます。 3つのキーワード引数が渡されます。

ctx-現在のコマンドコンテキスト。
param-完了を要求している現在のパラメーター。
incomplete-完成している部分的な単語。文字がまだ入力されていない場合は、空の文字列である可能性があります。

CompletionItem オブジェクトのリストを返す必要があります。または、ショートカットとして文字列のリストを返すことができます。

この例では、コマンドは不完全な値で始まる環境変数を提案します。

def complete_env_vars(ctx, param, incomplete):
    return [k for k in os.environ if k.startswith(incomplete)]

@click.command()
@click.argument("name", shell_complete=complete_env_vars)
def cli(name):
    click.echo(f"Name: {name}")
    click.echo(f"Value: {os.environ[name]}")

シェルのサポートの追加

組み込まれていないシェルのサポートを追加できます。 PyPIをチェックして、シェルのサポートを追加するパッケージがすでにあるかどうかを確認してください。このトピックは非常に技術的です。組み込みの実装を調べるには、Clickのソースを確認することをお勧めします。

シェルのサポートは、 add_completion_class（）に登録されている ShellComplete のサブクラスによって提供されます。 Clickが完了モードで呼び出されると、 source（）を呼び出して完了スクリプトを出力するか、 complete（）を呼び出して完了を出力します。基本クラスは、いくつかの小さなパーツの実装を必要とするデフォルトの実装を提供します。

まず、シェルの完了システムがどのように機能するかを理解し、それをClickと統合するためのスクリプトを作成する必要があります。環境変数_{PROG_NAME}_COMPLETEを{shell}_completeに設定してプログラムを呼び出し、完全な引数と不完全な値を渡す必要があります。それらの値をどのように渡すか、およびClickからの完了応答の形式はあなた次第です。

サブクラスで、 source_template を完了スクリプトに設定します。デフォルトの実装では、次の変数を使用して%フォーマットを実行します。

complete_func-スクリプトで定義された完了関数の安全な名前。
complete_var-{shell}_complete命令を渡すための環境変数名。
prog_name-完了している実行可能ファイルの名前。

サンプルコードは、構成されたシェル「MyShell」または略して「mysh」用です。

from click.shell_completion import add_completion_class
from click.shell_completion import ShellComplete

_mysh_source = """\
%(complete_func)s {
    response=$(%(complete_var)s=mysh_complete %(prog_name)s)
    # parse response and set completions somehow
}
call-on-complete %(prog_name)s %(complete_func)s
"""

@add_completion_class
class MyshComplete(ShellComplete):
    name = "mysh"
    source_template = _mysh_source

次に、 get_completion_args（）を実装します。これは、完了スクリプトから完全な引数と不完全な値を取得、解析、および返す必要があります。たとえば、Bash実装の場合、COMP_WORDS env varには文字列としてコマンドライン引数が含まれ、COMP_CWORD envvarには不完全なargのインデックスが含まれます。このメソッドは、(args, incomplete)タプルを返す必要があります。

import os
from click.parser import split_arg_string

class MyshComplete(ShellComplete):
    ...

    def get_completion_args(self):
        args = split_arg_string(os.environ["COMP_WORDS"])

        if os.environ["COMP_PARTIAL"] == "1":
            incomplete = args.pop()
            return args, incomplete

        return args, ""

最後に、 format_completion（）を実装します。これは、各 CompletionItem を文字列にフォーマットするために呼び出されます。たとえば、Bash実装はf"{item.type},{item.value}（ヘルプ文字列をサポートしていません）を返し、Zsh実装は改行で区切られた各部分を返し、空のヘルプを_プレースホルダーに置き換えます。この形式は、完了スクリプトで解析するものに完全に依存します。

typeの値は通常plainですが、完了スクリプトでオンにできる別の値にすることもできます。たとえば、fileまたはdirは、パスの完了を処理するようにシェルに指示できます。これは、シェルがClickよりも優れているためです。

class MyshComplete(ShellComplete):
    ...

    def format_completion(self, item):
        return f"{item.type}\t{item.value}"

これらの3つが実装されると、新しいシェルサポートの準備が整います。それらが十分でない場合は、オーバーライドできる部分がさらにありますが、おそらくそれは必要ありません。

アクティベーションの手順も、シェルの動作によって異なります。以下を使用して完了スクリプトを生成し、それを何らかの方法でシェルにロードします。

_FOO_BAR_COMPLETE=mysh_source foo-bar

シェルの完了—ドキュメントをクリックします

目次

シェルの完成

完了の有効化

カスタムタイプの完了

値の完了のオーバーライド

シェルのサポートの追加