オプション—ドキュメントをクリックします
オプション
コマンドにオプションを追加するには、 option()デコレータを使用します。 オプションにはさまざまなバージョンがありますので、それらの動作を構成するためのパラメーターがたくさんあります。 クリックのオプションは、位置引数とは異なります。
基本値オプション
最も基本的なオプションは値オプションです。 これらのオプションは、値である1つの引数を受け入れます。 タイプが指定されていない場合は、デフォルト値のタイプが使用されます。 デフォルト値が指定されていない場合、タイプは STRING であると見なされます。 デフォルトでは、パラメーターの名前は最初に定義された長いオプションです。 それ以外の場合は、最初の短いものが使用されます。
そしてコマンドラインで:
この場合、デフォルト値は整数であるため、オプションのタイプは INT です。
マルチバリューオプション
場合によっては、複数の引数を取るオプションがあります。 オプションの場合、固定数の引数のみがサポートされます。 これは、nargs
パラメーターで構成できます。 その後、値はタプルとして格納されます。
そしてコマンドラインで:
マルチバリューオプションとしてのタプル
バージョン4.0の新機能。
ご覧のとおり、 nargs を特定の番号に設定すると、結果のタプルの各アイテムは同じタイプになります。 これはあなたが望むものではないかもしれません。 通常、タプルのインデックスごとに異なるタイプを使用することをお勧めします。 このために、タイプとしてタプルを直接指定できます。
そしてコマンドラインで:
タプルリテラルをタイプとして使用することにより、 nargs はタプルの長さに自動的に設定され、 click.Tuple タイプが自動的に使用されます。 したがって、上記の例はこれと同等です。
複数のオプション
nargs
と同様に、複数回提供されるパラメーターをサポートし、最後の値だけでなくすべての値を記録したい場合もあります。 たとえば、git commit -m foo -m bar
は、コミットメッセージにfoo
とbar
の2行を記録します。 これは、multiple
フラグを使用して実行できます。
例:
そしてコマンドラインで:
カウント
非常にまれな状況では、オプションの繰り返しを使用して整数をカウントアップするのが興味深い場合があります。 これは、次のような詳細フラグに使用できます。
そしてコマンドラインで:
ブールフラグ
ブールフラグは、有効または無効にできるオプションです。 これは、オプションを有効または無効にするためにスラッシュ(/
)で区切って一度に2つのフラグを定義することで実現できます。 (スラッシュがオプション文字列に含まれている場合、Clickはそれがブールフラグであることを自動的に認識し、is_flag=True
を暗黙的に渡します。)Clickは常に、後でデフォルトを変更できるように、有効化フラグと無効化フラグを提供するように求めます。
例:
そしてコマンドラインで:
本当にオフスイッチが必要ない場合は、オフスイッチを定義して、何かがフラグであることを手動でClickに通知できます。
そしてコマンドラインで:
オプションにスラッシュがすでに含まれている場合(たとえば、/
がプレフィックス文字であるWindowsスタイルのパラメーターを使用する場合)、代わりに;
を介してパラメーターを分割できます。
バージョン6.0で変更されました。
2番目のオプションのエイリアスのみを定義する場合は、先頭の空白を使用してフォーマット文字列を明確にする必要があります。
例:
機能スイッチ
ブールフラグに加えて、機能スイッチもあります。 これらは、複数のオプションを同じパラメーター名に設定し、フラグ値を定義することによって実装されます。 flag_value
パラメーターを指定すると、Clickは暗黙的にis_flag=True
を設定することに注意してください。
デフォルトのフラグを設定するには、デフォルトにする必要のあるフラグに True の値を割り当てます。
そしてコマンドラインで:
選択オプション
場合によっては、パラメーターを値のリストの選択肢にしたいことがあります。 その場合は、 Choice タイプを使用できます。 有効な値のリストを使用してインスタンス化できます。
例:
それはどのようなものか:
プロンプト
場合によっては、コマンドラインから提供できるパラメーターが必要ですが、提供されていない場合は、代わりにユーザー入力を要求してください。 これは、プロンプト文字列を定義することにより、Clickで実装できます。
例:
そしてそれはどのように見えるか:
デフォルトのプロンプト文字列に満足できない場合は、別の文字列を要求できます。
それはどのようなものか:
パスワードプロンプト
Clickは、非表示のプロンプトと確認の要求もサポートしています。 これはパスワード入力に役立ちます。
それはどのようなものか:
このパラメーターの組み合わせは非常に一般的であるため、これを password_option()デコレーターに置き換えることもできます。
プロンプトの動的デフォルト
コンテキストのauto_envvar_prefix
およびdefault_map
オプションを使用すると、プログラムは環境または構成ファイルからオプション値を読み取ることができます。 ただし、これはプロンプトメカニズムをオーバーライドするため、ユーザーは値をインタラクティブに変更するオプションを取得できません。
ユーザーにデフォルト値を構成させたいが、コマンドラインでオプションが指定されていない場合でもプロンプトが表示される場合は、callableをデフォルト値として指定することでこれを行うことができます。 たとえば、環境からデフォルトを取得するには、次のようにします。
コールバックと熱心なオプション
パラメータで実行フローを完全に変更したい場合があります。 たとえば、これは、バージョンを出力してからアプリケーションを終了する--version
パラメーターが必要な場合です。
注:再利用可能な--version
パラメーターの実際の実装は、Click as click.version_option()で入手できます。 ここでのコードは、そのようなフラグを実装する方法の単なる例です。
このような場合、2つの概念が必要です。熱心なパラメーターとコールバックです。 熱心なパラメーターは他のパラメーターよりも先に処理されるパラメーターであり、コールバックはパラメーターが処理された後に実行されるパラメーターです。 以前に必要なパラメータがエラーメッセージを生成しないように、熱意が必要です。 たとえば、--version
が熱心でなく、パラメータ--foo
が以前に必要で定義されていた場合、--version
が機能するように指定する必要があります。 詳細については、コールバック評価順序を参照してください。
コールバックは、現在の Context と値の2つのパラメーターで呼び出される関数です。 コンテキストは、アプリケーションの終了などのいくつかの便利な機能を提供し、他のすでに処理されたパラメーターへのアクセスを提供します。
--version
フラグの例を次に示します。
expose_value パラメーターは、かなり無意味なversion
パラメーターがコールバックに渡されるのを防ぎます。 これが指定されていない場合、ブール値が hello スクリプトに渡されます。 resilient_parsing フラグは、Clickが実行フローを変更するような破壊的な動作なしにコマンドラインを解析する場合に、コンテキストに適用されます。 この場合、プログラムを終了するため、代わりに何もしません。
それはどのようなものか:
はいパラメータ
危険な操作の場合、ユーザーに確認を求めることができると非常に便利です。 これは、ブール--yes
フラグを追加し、ユーザーがそれを提供しなかったかどうかの確認を求め、コールバックに失敗することで実行できます。
そして、コマンドラインでどのように表示されるか:
このパラメーターの組み合わせは非常に一般的であるため、これを commentation_option()デコレーターに置き換えることもできます。
環境変数からの値
Clickの非常に便利な機能は、通常のパラメーターに加えて、環境変数からパラメーターを受け入れる機能です。 これにより、ツールをはるかに簡単に自動化できます。 たとえば、--config
パラメーターを使用して構成ファイルを渡すだけでなく、TOOL_CONFIG=hello.cfg
キーと値のペアのエクスポートをサポートして開発エクスペリエンスを向上させることもできます。
これは、Clickによって2つの方法でサポートされています。 1つは、オプションでのみサポートされる環境変数を自動的に作成することです。 この機能を有効にするには、呼び出されるスクリプトにauto_envvar_prefix
パラメーターを渡す必要があります。 次に、各コマンドとパラメーターは、大文字の下線で区切られた変数として追加されます。 bar
というオプションを使用するfoo
というサブコマンドがあり、プレフィックスがMY_TOOL
の場合、変数はMY_TOOL_FOO_BAR
です。
使用例:
そしてコマンドラインから:
2番目のオプションは、オプションで環境変数の名前を定義することにより、特定の環境変数から手動で値をプルすることです。
使用例:
そしてコマンドラインから:
その場合、最初の変数が選択されるさまざまな環境変数のリストにすることもできます。
環境値からの複数の値
オプションは複数の値を受け入れることができるため、環境変数(文字列)からそのような値を取得するのは少し複雑です。 Clickがこれを解決する方法は、この動作をカスタマイズするタイプに任せることです。 multiple
とnargs
の両方で、1
以外の値の場合、Clickは ParamType.split_envvar_value()メソッドを呼び出して分割を実行します。
すべてのタイプのデフォルトの実装は、空白で分割することです。 このルールの例外は、ファイルタイプとパスタイプで、どちらもオペレーティングシステムのパス分割ルールに従って分割されます。 LinuxやOSXなどのUnixシステムでは、分割はすべてのコロン(:
)で発生し、Windowsではすべてのセミコロン(;
)で発生します。
使用例:
そしてコマンドラインから:
その他のプレフィックス文字
クリックすると、オプションとして-
以外の代替プレフィックス文字を処理できます。 これは、たとえば、スラッシュをパラメーター/
などとして処理する場合に役立ちます。 Clickは開発者がPOSIXセマンティクスに近い状態を維持することを望んでいるため、これは一般的に強く推奨されないことに注意してください。 ただし、特定の状況では、これが役立つ場合があります。
そしてコマンドラインから:
プレフィックス文字として/
を使用していて、ブールフラグを使用する場合は、/
ではなく;
で区切る必要があることに注意してください。
範囲オプション
特筆すべきは、 IntRange タイプです。これは、 INT タイプと非常によく似ていますが、値が特定の範囲(両端を含む)に収まるように制限されています。 2つのモードがあります。
- 範囲外の値がエラーを引き起こすデフォルトモード(非クランプモード)。
- 範囲外の値がクランプされるオプションのクランプモード。 これは、
0-5
の範囲が、値10
に対して5
を返すか、値-1
に対して0
を返すことを意味します。
例:
そしてコマンドラインから:
いずれかのエッジにNone
を渡すと、その側で範囲が開いていることを意味します。
検証のためのコールバック
バージョン2.0で変更されました。
カスタム検証ロジックを適用する場合は、パラメーターコールバックでこれを行うことができます。 これらのコールバックは、値を変更するだけでなく、検証が機能しない場合にエラーを発生させる可能性があります。
Click 1.0では、 UsageError のみを発生させることができますが、Click 2.0以降では、 BadParameter エラーを発生させることもできます。これには、エラーメッセージを自動的にフォーマットするという追加の利点があります。パラメータ名も含まれます。
例:
そしてそれはどのように見えるか: