パラメータ—ドキュメントをクリックします
パラメーター
Clickは、スクリプトの2種類のパラメーター（オプションと引数）をサポートしています。 コマンドラインスクリプトの作成者の間では、どちらをいつ使用するかについて一般的に混乱が生じるため、違いの概要を簡単に説明します。 その名前が示すように、オプションはオプションです。 引数は理由の範囲内でオプションにすることができますが、オプションにする方法ははるかに制限されています。
オプションと引数のどちらを選択するかを決めるのに役立つように、サブコマンドへの移動やファイル名/ URLの入力などにのみ引数を使用し、代わりに他のすべてをオプションにすることをお勧めします。
違い
引数はオプションよりも少ないことができます。 次の機能は、オプションでのみ使用できます。
- 入力がない場合の自動プロンプト
- フラグとして機能します（ブール値またはその他）
- オプション値は環境変数から取得できますが、引数は取得できません
- オプションはヘルプページに完全に文書化されていますが、引数は文書化されていません（引数は具体的すぎて自動的に文書化できない可能性があるため、これは意図的なものです）
一方、引数は、オプションとは異なり、任意の数の引数を受け入れることができます。 オプションは厳密に固定数の引数のみを受け入れることができます（デフォルトは1）。
パラメータタイプ
パラメータはさまざまなタイプにすることができます。 タイプはさまざまな動作で実装でき、一部はそのままでサポートされます。
str/ click.STRING ：- Unicode文字列を示すデフォルトのパラメータタイプ。
int/ click.INT ：- 整数のみを受け入れるパラメーター。
float/ click.FLOAT ：- 浮動小数点値のみを受け入れるパラメーター。
bool/ click.BOOL ：- ブール値を受け入れるパラメーター。 これはブールフラグに自動的に使用されます。 文字列値
1、yes、y、およびtrueとともに使用すると、 True および0、[ X113X] 、n、falseは False に変換されます。 - click.UUID ：
- UUID値を受け入れるパラメーター。 これは自動的に推測されるのではなく、
uuid.UUIDとして表されます。
- class click.File(mode: str = 'r', encoding: Optional[str] = None, errors: Optional[str] = 'strict', lazy: Optional[bool] = None, atomic: bool = False)
パラメータを読み取りまたは書き込み用のファイルとして宣言します。 コンテキストが破棄されると（コマンドの動作が終了した後）、ファイルは自動的に閉じられます。
ファイルは、読み取りまたは書き込み用に開くことができます。 特別な値
-は、モードに応じてstdinまたはstdoutを示します。デフォルトでは、ファイルはテキストデータの読み取り用に開かれますが、バイナリモードまたは書き込み用に開くこともできます。 エンコーディングパラメータを使用して、特定のエンコーディングを強制できます。
lazy フラグは、ファイルをすぐに開くか、最初のIOで開くかを制御します。 デフォルトでは、標準の入力ストリームと出力ストリーム、および読み取り用に開かれたファイルの場合は遅延なし、それ以外の場合は遅延になります。 読み取りのためにファイルを遅延して開く場合でも、検証のために一時的に開かれますが、最初のIOまで開いたままになりません。 lazyは、必要になるまでファイルが作成されないようにするために、書き込み用に開くときに主に役立ちます。
Click 2.0以降、ファイルをアトミックに開くこともできます。その場合、すべての書き込みは同じフォルダー内の別のファイルに送られ、完了するとファイルは元の場所に移動されます。 これは、他のユーザーが定期的に読み取るファイルが変更されている場合に役立ちます。
詳細については、ファイル引数を参照してください。
- class click.Path(exists: bool = False, file_okay: bool = True, dir_okay: bool = True, writable: bool = False, readable: bool = True, resolve_path: bool = False, allow_dash: bool = False, path_type: Optional[Type] = None)
パスタイプはファイルタイプに似ていますが、異なるチェックを実行します。 まず、開いているファイルハンドルを返す代わりに、ファイル名だけを返します。 次に、ファイルまたはディレクトリがどうあるべきかについて、さまざまな基本的なチェックを実行できます。
- パラメーター
exists – trueに設定されている場合、この値を有効にするには、ファイルまたはディレクトリが存在している必要があります。 これが不要で、ファイルが実際に存在しない場合、それ以降のすべてのチェックはサイレントにスキップされます。
file_okay –ファイルが可能な値であるかどうかを制御します。
dir_okay –ディレクトリが可能な値であるかどうかを制御します。
writable – trueの場合、書き込み可能なチェックが実行されます。
読み取り可能 – trueの場合、読み取り可能チェックが実行されます。
resolve_path –これがtrueの場合、値が渡される前にパスが完全に解決されます。 これは、それが絶対的であり、シンボリックリンクが解決されることを意味します。 これはシェルによってのみ行われることになっているため、チルダプレフィックスは展開されません。
allow_dash –これが True に設定されている場合、標準ストリームを示す単一のダッシュが許可されます。
path_type –着信パス値をこのタイプに変換します。
Noneの場合、Pythonのデフォルトであるstrを維持します。pathlib.Pathに変換するのに便利です。
バージョン8.0で変更：
type=pathlib.Pathの受け渡しを許可します。バージョン6.0で変更：
allow_dashパラメーターが追加されました。
- class click.Choice(choices: Sequence[str], case_sensitive: bool = True)
選択タイプを使用すると、サポートされている値の固定セットに対して値をチェックできます。 これらの値はすべて文字列である必要があります。
選択肢のリストまたはタプルのみを渡す必要があります。 他の反復可能オブジェクト（ジェネレーターなど）は、驚くべき結果につながる可能性があります。
結果の値は、
case_sensitiveまたはctx.token_normalize_funcが指定されているかどうかに関係なく、常に最初に渡された選択肢の1つになります。例については、選択オプションを参照してください。
- パラメーター
case_sensitive –選択を大文字と小文字を区別しないようにするには、falseに設定します。 デフォルトはtrueです。
- class click.IntRange(min: Optional[float] = None, max: Optional[float] = None, min_open: bool = False, max_open: bool = False, clamp: bool = False)
click.INT 値を許容値の範囲に制限します。 範囲オプションを参照してください。
minまたはmaxが渡されない場合、その方向で任意の値が受け入れられます。min_openまたはmax_openが有効になっている場合、対応する境界は範囲に含まれません。clampが有効になっている場合、範囲外の値は失敗するのではなく、境界にクランプされます。バージョン8.0で変更：
min_openおよびmax_openパラメーターが追加されました。
カスタムパラメータタイプは、 click.ParamType をサブクラス化することで実装できます。 単純なケースでは、 ValueError で失敗するPython関数を渡すこともサポートされていますが、推奨されていません。
パラメータ名
パラメーター（オプションと引数の両方）は、パラメーター宣言であるいくつかの位置引数を受け入れます。 ダッシュが1つある各文字列は、短い引数として追加されます。 各文字列は、長いダッシュの2つのダッシュで始まります。 文字列をダッシュなしで追加すると、変数名としても使用される内部パラメータ名になります。
パラメータにダッシュなしで名前が付けられていない場合、最も長い引数を取り、すべてのダッシュをアンダースコアに変換することにより、名前が自動的に生成されます。 ('-f', '--foo-bar')のオプションの場合、パラメーター名は foo_bar です。 ('-x',)のオプションの場合、パラメーターは x です。 ('-f', '--filename', 'dest')のオプションの場合、パラメーターは dest と呼ばれます。
カスタムタイプの実装
カスタムタイプを実装するには、 ParamType クラスをサブクラス化する必要があります。 タイプは、コンテキストおよびパラメーターオブジェクトの有無にかかわらず呼び出すことができるため、これを処理できる必要があります。
次のコードは、通常の整数に加えて16進数と8進数を受け入れ、それらを通常の整数に変換する整数型を実装しています。
import click
class BasedIntParamType(click.ParamType):
name = 'integer'
def convert(self, value, param, ctx):
try:
if value[:2].lower() == '0x':
return int(value[2:], 16)
elif value[:1] == '0':
return int(value, 8)
return int(value, 10)
except ValueError:
self.fail('%s is not a valid integer' % value, param, ctx)
BASED_INT = BasedIntParamType()ご覧のとおり、サブクラスは ParamType.convert（）メソッドを実装し、オプションで ParamType.name 属性を提供する必要があります。 後者は、文書化の目的で使用できます。
