パラメーター

Clickは、スクリプトの2種類のパラメーター（オプションと引数）をサポートしています。コマンドラインスクリプトの作成者の間では、どちらをいつ使用するかについて一般的に混乱が生じるため、違いの概要を簡単に説明します。その名前が示すように、オプションはオプションです。引数は理由の範囲内でオプションにすることができますが、オプションにする方法ははるかに制限されています。

オプションと引数のどちらを選択するかを決めるのに役立つように、サブコマンドへの移動やファイル名/ URLの入力などにのみ引数を使用し、代わりに他のすべてをオプションにすることをお勧めします。

違い

引数はオプションよりも少ないことができます。次の機能は、オプションでのみ使用できます。

入力がない場合の自動プロンプト
フラグとして機能します（ブール値またはその他）
オプション値は環境変数から取得できますが、引数は取得できません
オプションはヘルプページに完全に文書化されていますが、引数は文書化されていません（これは意図的なものです引数は具体的すぎて自動的に文書化できない可能性があるため）

一方、引数は、オプションとは異なり、任意の数の引数を受け入れることができます。オプションは厳密に固定数の引数（デフォルトは1）のみを受け入れることができます。または、 Multiple Options を使用して複数回指定することもできます。

パラメータタイプ

パラメータはさまざまなタイプにすることができます。タイプはさまざまな動作で実装でき、一部はそのままでサポートされます。

str / click.STRING ：: Unicode文字列を示すデフォルトのパラメータタイプ。
int / click.INT ：: 整数のみを受け入れるパラメーター。
float / click.FLOAT ：: 浮動小数点値のみを受け入れるパラメーター。
bool / click.BOOL ：: ブール値を受け入れるパラメーター。これはブールフラグに自動的に使用されます。文字列値1、yes、y、t、およびtrueとともに使用すると、 True および[ X113X] 、no、n、f、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パラメーターが追加されました。

class click.FloatRange(min: Optional[float] = None, max: Optional[float] = None, min_open: bool = False, max_open: bool = False, clamp: bool = False)

click.FLOAT 値を許容値の範囲に制限します。範囲オプションを参照してください。

minまたはmaxが渡されない場合、その方向で任意の値が受け入れられます。 min_openまたはmax_openが有効になっている場合、対応する境界は範囲に含まれません。

clampが有効になっている場合、範囲外の値は失敗するのではなく、境界にクランプされます。いずれかの境界がopenとマークされている場合、これはサポートされません。

バージョン8.0で変更： min_openおよびmax_openパラメーターが追加されました。

class click.DateTime(formats: Optional[Sequence[str]] = None)

DateTime型は、日付文字列を datetime オブジェクトに変換します。

チェックされるフォーマット文字列は構成可能ですが、デフォルトではいくつかの一般的な（タイムゾーンに対応しない）ISO8601フォーマットになっています。

DateTime 形式を指定するときは、リストまたはタプルのみを渡す必要があります。ジェネレーターのような他の反復可能オブジェクトは、驚くべき結果につながる可能性があります。

フォーマット文字列はdatetime.strptimeを使用して処理されるため、許可されるフォーマット文字列が定義されます。

各形式を順番に使用して解析が試行され、正常に解析された最初の形式が使用されます。

パラメーター: format –試行する順序での日付フォーマット文字列のリストまたはタプル。デフォルトは'%Y-%m-%d'、'%Y-%m-%dT%H:%M:%S'、'%Y-%m-%d %H:%M:%S'です。

カスタムパラメータタイプは、 click.ParamType をサブクラス化することで実装できます。単純なケースでは、 ValueError で失敗するPython関数を渡すこともサポートされていますが、推奨されていません。

パラメータ名

パラメータ（オプションと引数の両方）には、値を使用して装飾された関数を呼び出すときにPython引数名として使用される名前があります。

引数は1つの位置名のみを取ります。ヘルプテキストで使用する別の名前を指定するには、ヘルプテキストの切り捨てを参照してください。

オプションには、1つまたは2つのダッシュを前に付けることができる多くの名前を付けることができます。ダッシュが1つある名前は短いオプションとして解析され、ダッシュが2つある名前は長いオプションとして解析されます。名前にプレフィックスが付いていない場合、その名前はPython引数名として使用され、オプション名として解析されません。それ以外の場合は、2つのダッシュプレフィックスが付いた名が使用されます。2つのダッシュプレフィックスが付いていない場合は、1つのダッシュプレフィックスが付いた最初の名前が使用されます。プレフィックスが削除され、ダッシュがアンダースコアに変換されてPython引数名が取得されます。

カスタムタイプの実装

カスタムタイプを実装するには、 ParamType クラスをサブクラス化する必要があります。 convert（）メソッドをオーバーライドして、値を文字列から正しい型に変換します。

次のコードは、通常の整数に加えて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 TypeError:
            self.fail(
                "expected string for int() conversion, got "
                f"{value!r} of type {type(value).__name__}",
                param,
                ctx,
            )
        except ValueError:
            self.fail(f"{value!r} is not a valid integer", param, ctx)

BASED_INT = BasedIntParamType()

name 属性はオプションであり、ドキュメントに使用されます。変換に失敗した場合は、 fail（）を呼び出します。 paramおよびctx引数は、プロンプトなどの場合にはNoneになることがあります。

パラメータ—ドキュメントをクリックします

目次

パラメーター

違い

パラメータタイプ

パラメータ名

カスタムタイプの実装