殻が完成する.¶
Bash(バージョン4.4以降)、Zsh、Fishにタブ完了サポートをクリックします。他のシェルのサポートを追加することもでき、複数のレベルでアドバイスをカスタマイズすることができます。
Shellは、アドバイス選択、ファイル、パスパラメータタイプのコマンド名、オプション名、値を完了します。少なくとも破れた番号が入力された場合にのみオプションが表示されます。隠されたコマンドやオプションは表示されません。
$ repo <TAB><TAB>
clone commit copy delete setuser
$ repo clone -<TAB><TAB>
--deep --help --rev --shallow -r
完了を有効にする¶
パスではなく、エントリポイントでインストールされ、スクリプトが呼び出された場合にのみ使用可能です。 python 指揮する。見 SetupTools統合 それがそうです。実行可能ファイルがインストールされると，特殊な環境変数呼び出しを用いてClickを完了モードにする.
In order for completion to be used, the user needs to register a special
function with their shell. The script is different for every shell, and
Click will output it when called with _{PROG_NAME}_COMPLETE set to
{shell}_source. {PROG_NAME} is the executable name in uppercase
with dashes replaced by underscores. The built-in shells are bash,
zsh, and fish.
お客様のユーザーに、以下のプログラム名のカスタマイズの説明を提供します。これは使うためのものです foo-bar 例を挙げましょう
これを追加して ~/.bashrc ：
eval "$(_FOO_BAR_COMPLETE=bash_source foo-bar)"
これを追加して ~/.zshrc ：
eval "$(_FOO_BAR_COMPLETE=zsh_source foo-bar)"
これを追加して ~/.config/fish/completions/foo-bar.fish ：
eval (env _FOO_BAR_COMPLETE=fish_source foo-bar)
これは，次のアクティベーションスクリプト手法で用いたファイルと同様である.Fishの場合、この方法を使用することはいつももっと簡単かもしれない。
Vbl.使用 eval Shellを起動するたびにその命令を呼び出して評価することを意味し，Shellの応答時間が遅延する可能性がある.高速化のためには，生成されたスクリプトを1つのファイルに作成し，ソースコードとしてください.これらのファイルを事前に生成し、あなたのプログラムと一緒に配布することで、ユーザーに一歩節約することができます。
スクリプトをどこかに保存する.
_FOO_BAR_COMPLETE=bash_source foo-bar > ~/.foo-bar-complete.bash
ファイルをソース位置に入れる ~/.bashrc それがそうです。
. ~/.foo-bar-complete.bash
スクリプトをどこかに保存する.
_FOO_BAR_COMPLETE=zsh_source foo-bar > ~/.foo-bar-complete.zsh
ファイルをソース位置に入れる ~/.zshrc それがそうです。
. ~/.foo-bar-complete.zsh
スクリプトを保存します ~/.config/fish/completions/foo-bar.fish ：
_FOO_BAR_COMPLETE=fish_source foo-bar > ~/.config/fish/completions/foo-bar.fish
シェル構成を変更すると、変更をロードするために新しいシェルを起動する必要があります。
カスタムタイプ完了¶
自己定義を作成しています ParamType それを書き直す shell_complete() 方法は、このタイプのパラメータを有するハウジング完了を提供する。この方法は戻らなければなりません CompletionItem 物体です。これらのオブジェクトは，値に加えて，shellが使用可能なメタデータを保持している.内蔵して使用する type 経路を指示する特別な処理と help サポートに対してアドバイスの横にヘルプ文字列を表示するShell.
本例では、このタイプは、不完全な値で始まる環境変数を提案する。
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をチェックして、すでに1つのパッケージにあなたのシェルへのサポートが追加されているかどうかをチェックしなければなりません。このテーマは非常に技術的で、Clickのソースコードを見て内蔵実装を検討する必要があります。
外殻支持 ShellComplete 登録されています add_completion_class() それがそうです。モードダウンが完了したときにClickを呼び出します source() 出力完了スクリプト、または complete() 出力が完了するには、以下の操作を実行してください。基本クラス提供は、いくつかのより小さい構成要素のデフォルト実装を実装する必要があります。
まず、シェルの完成システムがどのように動作しているかを明らかにし、Clickと統合するスクリプトを作成する必要があります。環境変数を使用してプログラムを呼び出す必要があります _{{PROG_NAME}}_COMPLETE とする. {{shell}}_complete 完全なパラメータと不完全な値を渡しますこれがどのようにこれらの値を伝達するか、Clickからの完了応答のフォーマットはあなたが決定します。
あなたのサブクラスでは、設定 source_template 完成スクリプトに追加します。デフォルトの実現は実行されます % 以下の変数設定フォーマットを使用します。
complete_func-スクリプトで定義された完了関数のセキュリティ名。complete_var-伝達のための{{shell}}_complete指令する。prog_name-完了中の実行可能ファイルの名前。
サンプルコードは、架空のシェル“my Shell”または単に“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 Env varは不完全パラメータのインデックスを含む.この方法は1つに戻らなければなりません (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は、改行で区切られた各部分を返します。 _ 占位符。このフォーマットは、スクリプトで解析された内容に完全に依存します。
♪the type 値は通常 plain しかし、これは、完了スクリプトが開くことができる別の値であってもよい。例えば file あるいは…。 dir Shellはこの点でClickよりもよくできているので、シェルに処理経路が完了したことを伝えることができる。
class MyshComplete(ShellComplete):
...
def format_completion(self, item):
return f"{item.type}\t{item.value}"
この3つのことが実現すると、新しいシェル支援の準備ができます。もしこれらが十分でなければ、もっと多くの部分をカバーすることができるが、これは必要ではないかもしれない。
起動指示は再びあなたのシェルの働き方にかかっています。以下のコードを用いて完了スクリプトを生成し，何らかの方法でシェルにロードする.
_FOO_BAR_COMPLETE=mysh_source foo-bar
