シェルの完成

バージョン2.0の新機能。

クリックすると、コマンド、オプション、および選択値のタブ補完を提供できます。 Bash、Zsh、Fishがサポートされています

完了は、pythonコマンドではなく、エントリポイントを介してスクリプトがインストールおよび呼び出された場合にのみ使用できます。 Setuptools Integration を参照してください。

それが完了するもの

通常、シェル補完サポートは、コマンド、オプション、およびタイプが click.Choice であるオプションまたは引数の値を補完します。オプションは、少なくともダッシュが入力されている場合にのみリストされます。

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

文字列のリストを返すautocompletion関数を提供することにより、引数とオプションの値にカスタム補完を提供できます。これは、提案を動的に生成される完了時間にする必要がある場合に役立ちます。コールバック関数には、次の3つのキーワード引数が渡されます。

ctx-現在のコマンドコンテキスト。
args-渡された引数のリスト。
incomplete-完成している部分的な単語。文字がまだ入力されていない場合は、空の文字列である可能性があります。

コールバック関数を使用して動的な提案を生成する例を次に示します。

import os

def get_env_vars(ctx, args, incomplete):
    return [k for k in os.environ.keys() if incomplete in k]

@click.command()
@click.argument("envvar", type=click.STRING, autocompletion=get_env_vars)
def cmd1(envvar):
    click.echo('Environment variable: %s' % envvar)
    click.echo('Value: %s' % os.environ[envvar])

完了ヘルプ文字列

ZSHとfishは、完了用のドキュメント文字列の表示をサポートしています。これらは、オプションとサブコマンドのヘルプパラメータから取得されます。動的に生成された補完の場合、文字列の代わりにタプルを返すことでヘルプ文字列を提供できます。タプルの最初の要素は補完であり、2番目の要素は表示するヘルプ文字列です。

コールバック関数を使用して、ヘルプ文字列を使用して動的な提案を生成する例を次に示します。

import os

def get_colors(ctx, args, incomplete):
    colors = [('red', 'a warm color'),
              ('blue', 'a cool color'),
              ('green', 'the other starter color')]
    return [c for c in colors if incomplete in c[0]]

@click.command()
@click.argument("color", type=click.STRING, autocompletion=get_colors)
def cmd1(color):
    click.echo('Chosen color is %s' % color)

アクティベーション

シェルの完了をアクティブにするには、スクリプトで完了が利用可能であることをシェルに通知する必要があります。 Clickアプリケーションは、自動的にそのサポートを提供します。プログラムが特別な_<PROG_NAME>_COMPLETE変数を使用して実行されると、通常のコマンドの代わりに完了メカニズムがトリガーされます。 <PROG_NAME>は、ダッシュがアンダースコアに置き換えられた大文字の実行可能ファイル名です。

ツールの名前がfoo-barの場合、変数の名前は_FOO_BAR_COMPLETEです。 source_{shell}値でエクスポートすると、評価するアクティベーションスクリプトが出力されます。

foo-barスクリプトの例を次に示します。

Bashの場合、これを~/.bashrcに追加します。

eval "$(_FOO_BAR_COMPLETE=source_bash foo-bar)"

Zshの場合、これを~/.zshrcに追加します。

eval "$(_FOO_BAR_COMPLETE=source_zsh foo-bar)"

Fishの場合、これを~/.config/fish/completions/foo-bar.fishに追加します。

eval (env _FOO_BAR_COMPLETE=source_fish foo-bar)

新しいシェルを開いて完了できるようにします。または、現在のシェルでevalコマンドを直接実行して、一時的に有効にします。

アクティベーションスクリプト

上記のevalの例では、シェルが開始されるたびにアプリケーションが呼び出されます。これにより、シェルの起動時間が大幅に遅くなる可能性があります。

または、生成された完了コードを静的スクリプトとしてエクスポートして実行します。このファイルはビルドと一緒に出荷できます。 Gitのようなツールがこれを行います。少なくともZshは完了ファイルの結果もキャッシュしますが、evalスクリプトはキャッシュしません。

Bashの場合：

_FOO_BAR_COMPLETE=source_bash foo-bar > foo-bar-complete.sh

Zshの場合：

_FOO_BAR_COMPLETE=source_zsh foo-bar > foo-bar-complete.sh

魚の場合：

_FOO_BAR_COMPLETE=source_zsh foo-bar > foo-bar-complete.sh

.bashrcまたは.zshrcで、evalコマンドの代わりにスクリプトを入手します。

. /path/to/foo-bar-complete.sh

Fishの場合、ファイルをcompletionsディレクトリに追加します。

_FOO_BAR_COMPLETE=source_fish foo-bar > ~/.config/fish/completions/foo-bar-complete.fish

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

シェルの完成

それが完了するもの

完了ヘルプ文字列

アクティベーション

アクティベーションスクリプト

目次