オプション—ドキュメントをクリックします
オプション
コマンドにオプションを追加するには、 option()デコレータを使用します。 オプションにはさまざまなバージョンがありますので、それらの動作を構成するためのパラメーターがたくさんあります。 クリックのオプションは、位置引数とは異なります。
オプションに名前を付ける
オプションには、decorated関数を呼び出すときにPython引数名として使用される名前があります。 これは、オプション名から推測することも、明示的に指定することもできます。 名前は、デコレータへの位置引数として指定されます。
名前は次の順序で選択されます
- 名前の前に付けられていない場合、その名前はPython引数名として使用され、コマンドラインではオプション名として扱われません。
- 2つのダッシュが前に付いた名前が少なくとも1つある場合は、最初に指定された名前が名前として使用されます。
- それ以外の場合は、ダッシュが1つ付いた名が使用されます。
Python引数名を取得するには、選択した名前を小文字に変換し、プレフィックスとして最大2つのダッシュを削除し、他のダッシュをアンダースコアに変換します。
@click.command()
@click.option('-s', '--string-to-echo')
def echo(string_to_echo):
click.echo(string_to_echo)
@click.command()
@click.option('-s', '--string-to-echo', 'string')
def echo(string):
click.echo(string)
"-f", "--foo-bar"
、名前はfoo_bar
です。"-x"
、名前はx
です。"-f", "--filename", "dest"
、名前はdest
です。"--CamelCase"
、名前はcamelcase
です。"-f", "-fb"
、名前はf
です。"--f", "--foo-bar"
、名前はf
です。"---f"
、名前は_f
です。
基本値オプション
最も基本的なオプションは値オプションです。 これらのオプションは、値である1つの引数を受け入れます。 タイプが指定されていない場合は、デフォルト値のタイプが使用されます。 デフォルト値が指定されていない場合、タイプは STRING であると見なされます。 名前が明示的に指定されていない限り、パラメーターの名前は最初に定義された長いオプションです。 それ以外の場合は、最初の短いものが使用されます。 デフォルトでは、オプションは必須ではありませんが、オプションを必須にするには、デコレータへの引数として required = True を渡すだけです。
そしてコマンドラインで:
この場合、デフォルト値は整数であるため、オプションのタイプは INT です。
コマンドヘルプを表示するときにデフォルト値を表示するには、show_default=True
を使用します
マルチバリューオプション
場合によっては、複数の引数を取るオプションがあります。 オプションの場合、固定数の引数のみがサポートされます。 これは、nargs
パラメーターで構成できます。 その後、値はタプルとして格納されます。
そしてコマンドラインで:
マルチバリューオプションとしてのタプル
バージョン4.0の新機能。
ご覧のとおり、 nargs を特定の番号に設定すると、結果のタプルの各アイテムは同じタイプになります。 これはあなたが望むものではないかもしれません。 通常、タプルのインデックスごとに異なるタイプを使用することをお勧めします。 このために、タイプとしてタプルを直接指定できます。
そしてコマンドラインで:
タプルリテラルをタイプとして使用することにより、 nargs はタプルの長さに自動的に設定され、 click.Tuple タイプが自動的に使用されます。 したがって、上記の例はこれと同等です。
複数のオプション
nargs
と同様に、複数回提供されるパラメーターをサポートし、最後の値だけでなくすべての値を記録したい場合もあります。 たとえば、git commit -m foo -m bar
は、コミットメッセージに対してfoo
とbar
の2行を記録します。 これは、multiple
フラグを使用して実行できます。
例:
そしてコマンドラインで:
default
をmultiple=True
と一緒に渡す場合、デフォルト値はリストまたはタプルである必要があります。そうでない場合、単一文字のリストとして解釈されます。
@click.option("--format", multiple=True, default=["json"])
カウント
非常にまれな状況では、オプションの繰り返しを使用して整数をカウントアップするのが興味深い場合があります。 これは、次のような詳細フラグに使用できます。
そしてコマンドラインで:
ブールフラグ
ブールフラグは、有効または無効にできるオプションです。 これは、オプションを有効または無効にするためにスラッシュ(/
)で区切って一度に2つのフラグを定義することで実現できます。 (スラッシュがオプション文字列に含まれている場合、Clickはそれがブールフラグであることを自動的に認識し、is_flag=True
を暗黙的に渡します。)Clickは常に、後でデフォルトを変更できるように、有効化フラグと無効化フラグを提供するように求めます。
例:
そしてコマンドラインで:
本当にオフスイッチが必要ない場合は、オフスイッチを定義して、何かがフラグであることを手動でClickに通知できます。
そしてコマンドラインで:
オプションにスラッシュがすでに含まれている場合(たとえば、/
がプレフィックス文字であるWindowsスタイルのパラメーターを使用する場合)、代わりに;
でパラメーターを分割できます。
バージョン6.0で変更されました。
2番目のオプションのエイリアスのみを定義する場合は、先頭の空白を使用してフォーマット文字列を明確にする必要があります。
例:
機能スイッチ
ブールフラグに加えて、機能スイッチもあります。 これらは、複数のオプションを同じパラメーター名に設定し、フラグ値を定義することによって実装されます。 flag_value
パラメーターを指定すると、Clickは暗黙的にis_flag=True
を設定することに注意してください。
デフォルトのフラグを設定するには、デフォルトにする必要のあるフラグに True の値を割り当てます。
そしてコマンドラインで:
選択オプション
場合によっては、パラメーターを値のリストの選択肢にしたいことがあります。 その場合は、 Choice タイプを使用できます。 有効な値のリストを使用してインスタンス化できます。 コマンドラインで渡されたstrではなく、最初に渡された選択肢が返されます。 トークン正規化関数とcase_sensitive=False
により、2つは異なっていても、一致している可能性があります。
例:
それはどのようなものか:
リストまたはタプルとしてのみ選択肢を渡します。 他の反復可能オブジェクト(ジェネレーターなど)は、予期しない結果につながる可能性があります。
選択肢は、multiple=True
のあるオプションで機能します。 default
値がmultiple=True
で指定されている場合、それは有効な選択肢のリストまたはタプルである必要があります。
case_sensitive
と指定されたトークン正規化関数の効果を考慮した後、選択肢は一意である必要があります。
バージョン7.1で変更:オプションの結果の値は、case_sensitive
に関係なく、常に最初に渡された選択肢の1つになります。
プロンプト
場合によっては、コマンドラインから提供できるパラメーターが必要ですが、提供されていない場合は、代わりにユーザー入力を要求してください。 これは、プロンプト文字列を定義することにより、Clickで実装できます。
例:
そしてそれはどのように見えるか:
デフォルトのプロンプト文字列に満足できない場合は、別の文字列を要求できます。
それはどのようなものか:
プロンプトは、Trueに設定された複数フラグと組み合わせて使用しないことをお勧めします。 代わりに、関数でインタラクティブにプロンプトを表示します。
パスワードプロンプト
Clickは、非表示のプロンプトと確認の要求もサポートしています。 これはパスワード入力に役立ちます。
それはどのようなものか:
このパラメーターの組み合わせは非常に一般的であるため、これを password_option()デコレーターに置き換えることもできます。
プロンプトの動的デフォルト
コンテキストのauto_envvar_prefix
およびdefault_map
オプションを使用すると、プログラムは環境または構成ファイルからオプション値を読み取ることができます。 ただし、これはプロンプトメカニズムをオーバーライドするため、ユーザーは値をインタラクティブに変更するオプションを取得できません。
ユーザーにデフォルト値を構成させたいが、コマンドラインでオプションが指定されていない場合でもプロンプトが表示される場合は、callableをデフォルト値として指定することでこれを行うことができます。 たとえば、環境からデフォルトを取得するには、次のようにします。
デフォルト値を説明するには、show_default
で設定します。
コールバックと熱心なオプション
パラメータで実行フローを完全に変更したい場合があります。 たとえば、これは、バージョンを出力してからアプリケーションを終了する--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
パラメーターを渡す必要があります。 次に、各コマンドとパラメーターは、大文字の下線で区切られた変数として追加されます。 reload
というオプションを使用するrun
というサブコマンドがあり、プレフィックスがWEB
の場合、変数はWEB_RUN_RELOAD
です。
使用例:
そしてコマンドラインから:
コマンドグループでauto_envvar_prefix
を使用する場合、コマンド名は、環境変数のプレフィックスとパラメーター名 ie PREFIX_COMMAND_VARIABLE
の間に含める必要があります。 host
というオプションを使用するrun-server
というサブコマンドがあり、プレフィックスがWEB
の場合、変数はWEB_RUN_SERVER_HOST
です。
例:
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 エラーを発生させることもできます。これには、エラーメッセージを自動的にフォーマットするという追加の利点があります。パラメータ名も含まれます。
例:
そしてそれはどのように見えるか: