シェルの完了—ドキュメントをクリックします
シェルの完成
バージョン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