API —ドキュメントをクリックします
API
ドキュメントのこの部分には、すべてのパブリッククラスと関数の完全なAPIリファレンスがリストされています。
デコレータ
- click.command(name: Optional[str] = None, cls: Optional[Type[click.core.Command]] = None, **attrs: Any) Callable[[click.decorators.F], click.core.Command]
新しいコマンドを作成し、装飾された関数をコールバックとして使用します。 これにより、装飾されたすべての option()と arguments()がパラメーターとしてコマンドに自動的にアタッチされます。
コマンドの名前は、デフォルトで関数の名前になり、アンダースコアがダッシュに置き換えられます。 これを変更したい場合は、最初の引数として目的の名前を渡すことができます。
すべてのキーワード引数は、基になるコマンドクラスに転送されます。
装飾されると、関数は Command インスタンスに変わり、コマンドラインユーティリティとして呼び出すか、コマンド Group にアタッチできます。
- パラメーター
name –コマンドの名前。 これはデフォルトで関数名になり、アンダースコアがダッシュに置き換えられます。
cls –インスタンス化するコマンドクラス。 これはデフォルトでコマンドになります。
- click.group(name: Optional[str] = None, **attrs: Any) Callable[[click.decorators.F], click.core.Group]
- コールバックとしての関数を使用して、新しい Group を作成します。 これは、 cls パラメーターが Group に設定されていることを除けば、 command()と同じように機能します。
- click.argument(*param_decls: str, **attrs: Any) Callable[[click.decorators.FC], click.decorators.FC]
- コマンドに引数を付加します。 すべての位置引数は、パラメーター宣言として引数に渡されます。 すべてのキーワード引数は変更されずに転送されます(
cls
を除く)。 これは、 Argument インスタンスを手動で作成し、それを Command.params リストに添付するのと同じです。
- パラメーター
- cls –インスタンス化する引数クラス。 これはデフォルトで引数になります。
- click.option(*param_decls: str, **attrs: Any) Callable[[click.decorators.FC], click.decorators.FC]
- コマンドにオプションを付加します。 すべての位置引数は、パラメーター宣言として Option に渡されます。 すべてのキーワード引数は変更されずに転送されます(
cls
を除く)。 これは、 Option インスタンスを手動で作成し、それを Command.params リストに添付するのと同じです。
- パラメーター
- cls –インスタンス化するオプションクラス。 これはデフォルトで Option になります。
- click.password_option(*param_decls: str, **kwargs: Any) Callable[[click.decorators.FC], click.decorators.FC]
--password
オプションを追加して、パスワードの入力を求め、入力を非表示にして、確認のために値をもう一度入力するように求めます。
- パラメーター
- ;;* param_decls –1つ以上のオプション名。 デフォルトは単一の値
"--password"
です。
- kwargs –追加の引数が option()に渡されます。
- click.confirmation_option(*param_decls: str, **kwargs: Any) Callable[[click.decorators.FC], click.decorators.FC]
--yes
オプションを追加して、渡されなかった場合に続行する前にプロンプトを表示します。 プロンプトが拒否された場合、プログラムは終了します。
- パラメーター
- ;;* param_decls –1つ以上のオプション名。 デフォルトは単一の値
"--yes"
です。
- kwargs –追加の引数が option()に渡されます。
- click.version_option(version: Optional[str] = None, *param_decls: str, package_name: Optional[str] = None, prog_name: Optional[str] = None, message: Optional[str] = None, **kwargs: Any) Callable[[click.decorators.FC], click.decorators.FC]
--version
オプションを追加すると、バージョン番号がすぐに出力され、プログラムが終了します。version
が提供されていない場合、Clickはimportlib.metadata.version()
を使用してそれを検出し、package_name
のバージョンを取得しようとします。 Python <3.8では、importlib_metadata
バックポートをインストールする必要があります。package_name
が指定されていない場合、Clickはスタックフレームを検査して検出を試みます。 これはバージョンの検出に使用されるため、インストールされているパッケージの名前と一致する必要があります。- パラメーター
version –表示するバージョン番号。 指定されていない場合、Clickはそれを検出しようとします。
param_decls –1つ以上のオプション名。 デフォルトは単一の値
"--version"
です。package_name –バージョンを検出するためのパッケージ名。 指定されていない場合、Clickはそれを検出しようとします。
prog_name –メッセージに表示するCLIの名前。 指定しない場合は、コマンドから検出されます。
message –表示するメッセージ。 値
%(prog)s
、%(package)s
、および%(version)s
が使用可能です。 デフォルトは"%(prog)s, version %(version)s"
です。kwargs –追加の引数が option()に渡されます。
- 上げる
RuntimeError –
version
を検出できませんでした。
バージョン8.0で変更:メッセージの
package_name
パラメーターと%(package)s
値を追加します。バージョン8.0で変更:
pkg_resources
の代わりにimportlib.metadata
を使用します。 バージョンは、エントリポイント名ではなく、パッケージ名に基づいて検出されます。 Pythonパッケージ名は、インストールされているパッケージ名と一致するか、package_name=
で渡される必要があります。
- click.help_option(*param_decls: str, **kwargs: Any) Callable[[click.decorators.FC], click.decorators.FC]
--help
オプションを追加すると、ヘルプページがすぐに印刷され、プログラムが終了します。add_help_option=False
が渡されない限り、--help
オプションが各コマンドに自動的に追加されるため、これは通常不要です。- パラメーター
param_decls –1つ以上のオプション名。 デフォルトは単一の値
"--help"
です。kwargs –追加の引数が option()に渡されます。
- click.pass_context(f: click.decorators.F) click.decorators.F
- 現在のコンテキストオブジェクトを最初の引数として受け取りたいとしてコールバックをマークします。
- click.pass_obj(f: click.decorators.F) click.decorators.F
- pass_context()に似ていますが、コンテキスト以降のオブジェクト( Context.obj )のみを渡します。 これは、そのオブジェクトがネストされたシステムの状態を表す場合に役立ちます。
- click.make_pass_decorator(object_type: Type, ensure: bool = False) Callable[[click.decorators.F], click.decorators.F]
オブジェクトタイプが与えられると、これは pass_obj()と同様に機能するデコレータを作成しますが、現在のコンテキストのオブジェクトを渡す代わりに、タイプ
object_type()
の最も内側のコンテキストを見つけます。これにより、おおよそ次のように機能するデコレータが生成されます。
from functools import update_wrapper def decorator(f): @pass_context def new_func(ctx, *args, **kwargs): obj = ctx.find_object(object_type) return ctx.invoke(f, obj, *args, **kwargs) return update_wrapper(new_func, f) return decorator
- パラメーター
object_type –渡すオブジェクトのタイプ。
sure – True に設定すると、新しいオブジェクトが作成され、まだ存在しない場合はコンテキストに記憶されます。
ユーティリティ
- click.echo(message: Optional[Any] = None, file: Optional[IO] = None, nl: bool = True, err: bool = False, color: Optional[bool] = None) None
メッセージと改行をstdoutまたはファイルに出力します。 これは、
print()
の代わりに使用する必要があります。これは、さまざまなデータ、ファイル、および環境に対するサポートが向上するためです。print()
と比較すると、これは次のことを行います。Linuxで出力エンコーディングが誤って構成されていないことを確認します。
WindowsコンソールでUnicodeをサポートします。
バイナリ出力への書き込みをサポートし、テキスト出力へのバイトの書き込みをサポートします。
Windowsで色とスタイルをサポートします。
出力がインタラクティブ端末のように見えない場合は、ANSIカラーコードとスタイルコードを削除します。
常に出力をフラッシュします。
- パラメーター
message –出力する1つまたは複数の文字列。 他のオブジェクトは文字列に変換されます。
file –書き込むファイル。 デフォルトは
stdout
です。err –
stdout
の代わりにstderr
に書き込みます。nl –メッセージの後に改行を出力します。 デフォルトで有効になっています。
color –色やその他のスタイルを強制的に表示または非表示にします。 デフォルトでは、出力がインタラクティブ端末のように見えない場合、Clickは色を削除します。
バージョン6.0で変更: WindowsコンソールでUnicode出力をサポートします。 Clickは
sys.stdout
を変更しないため、sys.stdout.write()
およびprint()
は引き続きUnicodeをサポートしません。バージョン4.0で変更:
color
パラメーターが追加されました。バージョン3.0の新機能:
err
パラメーターが追加されました。バージョン2.0で変更: coloramaがインストールされている場合、Windowsで色をサポートします。
- click.echo_via_pager(text_or_generator: Union[Iterable[str], Callable[[], Iterable[str]], str], color: Optional[bool] = None) None
この関数はテキストを受け取り、stdoutの環境固有のページャーを介して表示します。
バージョン3.0で変更: color フラグが追加されました。
- パラメーター
text_or_generator –テキストからページ、またはテキストをページに出力するジェネレーター。
color –ページャーがANSIカラーをサポートするかどうかを制御します。 デフォルトは自動検出です。
- click.prompt(text: str, default: Optional[Any] = None, hide_input: bool = False, confirmation_prompt: Union[bool, str] = False, type: Optional[click.types.ParamType] = None, value_proc: Optional[Callable[[str], Any]] = None, prompt_suffix: str = ': ', show_default: bool = True, err: bool = False, show_choices: bool = True) Any
ユーザーに入力を求めます。 これは、後でユーザーに入力を求めるために使用できる便利な機能です。
ユーザーが割り込み信号を送信して入力を中止すると、この関数は入力をキャッチして Abort 例外を発生させます。
- パラメーター
text –プロンプトに表示するテキスト。
default –入力が発生しない場合に使用するデフォルト値。 これが指定されていない場合は、中止されるまでプロンプトが表示されます。
hide_input –これがtrueに設定されている場合、入力値は非表示になります。
commentation_prompt –値を確認するためにもう一度プロンプトを表示します。
True
の代わりに文字列に設定して、メッセージをカスタマイズできます。type –値をチェックするために使用するタイプ。
value_proc –このパラメーターが指定されている場合、値を変換するために型変換の代わりに呼び出される関数です。
prompt_suffix –プロンプトに追加する必要のあるサフィックス。
show_default –プロンプトのデフォルト値を表示または非表示にします。
err – trueに設定すると、ファイルは、echoの場合と同じように、デフォルトで
stdout
ではなくstderr
になります。show_choices –渡されたタイプがChoiceの場合、選択肢を表示または非表示にします。 たとえば、typeがdayまたはweekのいずれかの選択肢であり、show_choicesがtrueで、テキストが「Group by」の場合、プロンプトは「Group by(day、week):」になります。
バージョン8.0の新機能:
confirmation_prompt
はカスタム文字列にすることができます。バージョン7.0の新機能:
show_choices
パラメーターが追加されました。バージョン6.0の新機能: Windowsでのcmd.exeのUnicodeサポートが追加されました。
バージョン4.0の新機能: err パラメーターが追加されました。
- click.confirm(text: str, default: Optional[bool] = False, abort: bool = False, prompt_suffix: str = ': ', show_default: bool = True, err: bool = False) bool
確認のプロンプト(はい/質問なし)。
ユーザーが割り込み信号を送信して入力を中止すると、この関数は入力をキャッチして Abort 例外を発生させます。
- パラメーター
text –尋ねる質問。
default –入力が与えられていないときに使用するデフォルト値。
None
の場合は、入力が行われるまで繰り返します。abort –これが True に設定されている場合、否定的な回答は Abort を発生させて例外を中止します。
prompt_suffix –プロンプトに追加する必要のあるサフィックス。
show_default –プロンプトのデフォルト値を表示または非表示にします。
err – trueに設定すると、ファイルは、echoの場合と同じように、デフォルトで
stdout
ではなくstderr
になります。
バージョン8.0で変更:
default
がNone
の場合、入力が行われるまで繰り返します。バージョン4.0の新機能:
err
パラメーターが追加されました。
- click.progressbar(iterable: Optional[Iterable[click.termui.V]] = None, length: Optional[int] = None, label: Optional[str] = None, show_eta: bool = True, show_percent: Optional[bool] = None, show_pos: bool = False, item_show_func: Optional[Callable[[Optional[click.termui.V]], Optional[str]]] = None, fill_char: str = '#', empty_char: str = '-', bar_template: str = '%(label)s [%(bar)s] %(info)s', info_sep: str = ' ', width: int = 36, file: Optional[TextIO] = None, color: Optional[bool] = None, update_min_steps: int = 1) ProgressBar[V]
この関数は、プログレスバーを表示しながら何かを反復処理するために使用できる反復可能なコンテキストマネージャーを作成します。 iterable または length アイテム(カウントアップされている)を繰り返し処理します。 反復が発生している間、この関数はレンダリングされたプログレスバーを指定されたファイル(デフォルトはstdout)に出力し、残り時間などの計算を試みます。 デフォルトでは、ファイルがターミナルでない場合、このプログレスバーは表示されません。
コンテキストマネージャーはプログレスバーを作成します。 コンテキストマネージャーに入ると、プログレスバーがすでに作成されています。 プログレスバーを反復するたびに、バーに渡された反復可能オブジェクトが進められ、バーが更新されます。 コンテキストマネージャが終了すると、改行が出力され、進行状況バーが画面に表示されます。
注:プログレスバーは現在、全体の進行に少なくとも数秒かかると予想されるユースケース向けに設計されています。 このため、ProgressBarクラスオブジェクトは、速すぎると見なされる進行状況と、ステップ間の時間が1秒未満の進行状況を表示しません。
印刷を行わないでください。そうしないと、プログレスバーが意図せずに破壊されます。
使用例:
with progressbar(items) as bar: for item in bar: do_something_with(item)
または、反復可能オブジェクトが指定されていない場合は、プログレスバーを直接反復する代わりに、 update()メソッドを使用してプログレスバーを手動で更新できます。 updateメソッドは、次のようにバーをインクリメントするためのステップ数を受け入れます。
with progressbar(length=chunks.total_bytes) as bar: for chunk in chunks: process_chunk(chunk) bar.update(chunks.bytes)
update()
メソッドも、新しい位置でcurrent_item
を指定するオプションの値を取ります。 これは、item_show_func
と一緒に使用して、各手動ステップの出力をカスタマイズする場合に役立ちます。with click.progressbar( length=total_size, label='Unzipping archive', item_show_func=lambda a: a.filename ) as bar: for archive in zip_file: archive.extract() bar.update(archive.size, archive)
- パラメーター
iterable –反復可能です。 指定されていない場合、長さが必要です。
length –反復するアイテムの数。 デフォルトでは、プログレスバーはイテレータにその長さを尋ねようとしますが、これは機能する場合と機能しない場合があります。 iterableも提供されている場合は、このパラメーターを使用して長さをオーバーライドできます。 反復可能が提供されていない場合、プログレスバーはその長さの範囲で反復します。
label –プログレスバーの横に表示するラベル。
show_eta –推定時間の表示を有効または無効にします。 長さが決定できない場合、これは自動的に無効になります。
show_percent –パーセンテージ表示を有効または無効にします。 デフォルトは、イテラブルの長さが True の場合は True 、そうでない場合は False です。
show_pos –絶対位置表示を有効または無効にします。 デフォルトは False です。
item_show_func –現在のアイテムで呼び出される関数で、進行状況バーの横に表示する文字列を返すことができます。 関数が
None
を返す場合、何も表示されません。 現在のアイテムは、バーに出入りするときなど、None
にすることができます。fill_char –プログレスバーの塗りつぶされた部分を表示するために使用する文字。
empty_char –プログレスバーの塗りつぶされていない部分を表示するために使用する文字。
bar_template –バーのテンプレートとして使用するフォーマット文字列。 その中のパラメータは、ラベルの場合は
label
、プログレスバーの場合はbar
、情報セクションの場合はinfo
です。info_sep –複数の情報アイテム(etaなど)間の区切り文字
width –プログレスバーの幅(文字数)。0は端末の全幅を意味します
file –書き込むファイル。 これが端末でない場合は、ラベルのみが印刷されます。
color –端末がANSIカラーをサポートするかどうかを制御します。 デフォルトは自動検出です。 これは、ANSIコードがプログレスバー出力のどこかに含まれている場合にのみ必要ですが、デフォルトではそうではありません。
update_min_steps –この数の更新が完了した場合にのみレンダリングします。 これにより、非常に高速なイテレータのチューニングが可能になります。
バージョン8.0で変更:実行時間が0.5秒未満の場合でも出力が表示されます。
バージョン8.0で変更:
item_show_func
は、前のアイテムではなく、現在のアイテムを表示します。バージョン8.0で変更:出力がTTYでない場合、ラベルがエコーされます。 すべての出力を削除した7.0での変更を元に戻します。
バージョン8.0の新機能:
update_min_steps
パラメーターが追加されました。バージョン4.0で変更:
color
パラメーターが追加されました。update
メソッドをオブジェクトに追加しました。バージョン2.0の新機能。
- click.clear() None
ターミナル画面をクリアします。 これにより、端末の表示スペース全体がクリアされ、カーソルが左上に移動します。 端末に接続されていない場合、これは何もしません。
バージョン2.0の新機能。
- click.style(text: Any, fg: Optional[Union[int, Tuple[int, int, int], str]] = None, bg: Optional[Union[int, Tuple[int, int, int], str]] = None, bold: Optional[bool] = None, dim: Optional[bool] = None, underline: Optional[bool] = None, overline: Optional[bool] = None, italic: Optional[bool] = None, blink: Optional[bool] = None, reverse: Optional[bool] = None, strikethrough: Optional[bool] = None, reset: bool = True) str
ANSIスタイルでテキストのスタイルを設定し、新しい文字列を返します。 デフォルトでは、スタイリングは自己完結型です。つまり、文字列の最後にリセットコードが発行されます。 これは、
reset=False
を渡すことで防ぐことができます。例:
click.echo(click.style('Hello World!', fg='green')) click.echo(click.style('ATTENTION!', blink=True)) click.echo(click.style('Some things', reverse=True, fg='cyan')) click.echo(click.style('More colors', fg=(255, 12, 128), bg=117))
サポートされている色の名前:
black
(灰色の場合があります)red
green
yellow
(オレンジ色の場合があります)blue
magenta
cyan
white
(薄い灰色の場合があります)bright_black
bright_red
bright_green
bright_yellow
bright_blue
bright_magenta
bright_cyan
bright_white
reset
(カラーコードのみをリセット)
端末がそれをサポートしている場合、色は次のように指定することもできます。
間隔[0、255]の整数。 端末は8ビット/ 256色モードをサポートする必要があります。
[0、255]の3つの整数のRGBタプル。 端末は24ビット/トゥルーカラーモードをサポートしている必要があります。
詳細については、 https://en.wikipedia.org/wiki/ANSI_colorおよび https://gist.github.com/XVilka/8346728 を参照してください。
- パラメーター
text –ANSIコードでスタイルを設定する文字列。
fg –指定されている場合、これは前景色になります。
bg –指定されている場合、これが背景色になります。
太字 –指定されている場合、太字モードが有効または無効になります。
dim –指定されている場合、これはdimモードを有効または無効にします。 これは十分にサポートされていません。
下線 –指定されている場合、下線が有効または無効になります。
overline –指定されている場合、これによりオーバーラインが有効または無効になります。
斜体 –指定されている場合、斜体が有効または無効になります。
点滅 –指定されている場合、点滅が有効または無効になります。
reverse –指定されている場合、これにより逆レンダリングが有効または無効になります(前景が背景になり、その逆になります)。
取り消し線 –指定されている場合、これによりテキストの取り消し線が有効または無効になります。
reset –デフォルトでは、すべてリセットコードが文字列の最後に追加されます。これは、スタイルが引き継がれないことを意味します。 これを無効にして、スタイルを作成できます。
バージョン8.0で変更:非文字列
message
は文字列に変換されます。バージョン8.0で変更: 256およびRGBカラーコードのサポートが追加されました。
バージョン8.0で変更:
strikethrough
、italic
、およびoverline
パラメーターが追加されました。バージョン7.0で変更:明るい色のサポートが追加されました。
バージョン2.0の新機能。
- click.unstyle(text: str) str
文字列からANSIスタイリング情報を削除します。 Clickのエコー機能は必要に応じて自動的にスタイリングを削除するため、通常はこの機能を使用する必要はありません。
バージョン2.0の新機能。
- パラメーター
text –スタイル情報を削除するテキスト。
- click.secho(message: Optional[Any] = None, file: Optional[IO] = None, nl: bool = True, err: bool = False, color: Optional[bool] = None, **styles: Any) None
この関数は、 echo()と style()を1つの呼び出しに結合します。 そのため、次の2つの呼び出しは同じです。
click.secho('Hello World!', fg='green') click.echo(click.style('Hello World!', fg='green'))
すべてのキーワード引数は、使用する関数に応じて、基になる関数に転送されます。
文字列以外のタイプは
str
に変換されます。 ただし、bytes
は、スタイルを適用せずに echo()に直接渡されます。 テキストを表すバイトのスタイルを設定する場合は、最初にbytes.decode()
を呼び出します。バージョン8.0で変更:非文字列
message
は文字列に変換されます。 バイトはスタイルを適用せずに渡されます。バージョン2.0の新機能。
- click.edit(text: Optional[AnyStr] = None, editor: Optional[str] = None, env: Optional[Mapping[str, str]] = None, require_save: bool = True, extension: str = '.txt', filename: Optional[str] = None) Optional[AnyStr]
定義されたエディターで指定されたテキストを編集します。 エディターが指定されている場合(実行可能ファイルへのフルパスである必要がありますが、実行可能ファイルの検索には通常のオペレーティングシステム検索パスが使用されます)、検出されたエディターをオーバーライドします。 オプションで、いくつかの環境変数を使用できます。 エディターを変更せずに閉じると、 None が返されます。 ファイルを直接編集する場合、戻り値は常に None であり、 require_save および extension は無視されます。
エディタを開くことができない場合、 UsageError が発生します。
Windowsに関する注意:クロスプラットフォームの使用を簡素化するために、改行はPOSIXからWindowsに、またはその逆に自動的に変換されます。 そのため、ここでのメッセージには、改行マーカーとして
\n
が含まれます。- パラメーター
text –編集するテキスト。
editor –オプションで使用するエディター。 デフォルトは自動検出です。
env –エディターに転送する環境変数。
require_save –これがtrueの場合、エディターに保存しないと、戻り値は None になります。
extension –編集者に通知する拡張機能。 これはデフォルトで .txt になりますが、これを変更すると構文の強調表示が変わる可能性があります。
filename –指定されている場合、提供されたテキストコンテンツの代わりにこのファイルを編集します。 その場合、一時ファイルを間接参照として使用しません。
- click.launch(url: str, wait: bool = False, locate: bool = False) int
この関数は、このファイルタイプのデフォルトのビューアアプリケーションで指定されたURL(またはファイル名)を起動します。 これが実行可能ファイルの場合、新しいセッションで実行可能ファイルを起動する可能性があります。 戻り値は、起動されたアプリケーションの終了コードです。 通常、
0
は成功を示します。例:
click.launch('https://click.palletsprojects.com/') click.launch('/my/downloaded/file', locate=True)
バージョン2.0の新機能。
- パラメーター
url –起動するもののURLまたはファイル名。
wait –プログラムが終了するのを待ってから戻ってください。 これは、起動されたプログラムがブロックされた場合にのみ機能します。 特に、Linux上の
xdg-open
はブロックしません。Locate –これが True に設定されている場合、URLに関連付けられたアプリケーションを起動する代わりに、ファイルが配置された状態でファイルマネージャーを起動しようとします。 URLがファイルシステムを指していない場合、これは奇妙な影響を与える可能性があります。
- click.getchar(echo: bool = False) str
端末から1文字をフェッチして返します。 これは常にUnicode文字を返し、特定のまれな状況では、これは複数の文字を返す場合があります。 複数の文字が返される状況は、何らかの理由で複数の文字が端末バッファーに格納されるか、標準入力が実際には端末ではなかった場合です。
何かが標準入力にパイプされている場合でも、これは常に端末から読み取られることに注意してください。
Windowsに関する注意:まれに、ASCII以外の文字を入力するときに、この関数は2番目の文字を待ってから、両方を同時に返す場合があります。 これは、特定のUnicode文字が特殊キーマーカーのように見えるためです。
バージョン2.0の新機能。
- パラメーター
echo – True に設定すると、読み取った文字も端末に表示されます。 デフォルトでは表示されません。
- click.pause(info: Optional[str] = None, err: bool = False) None
このコマンドは実行を停止し、ユーザーがいずれかのキーを押して続行するのを待ちます。 これは、Windowsのバッチ「一時停止」コマンドに似ています。 プログラムが端末を介して実行されていない場合、このコマンドは代わりに何もしません。
バージョン2.0の新機能。
バージョン4.0の新機能: err パラメーターが追加されました。
- パラメーター
info –一時停止する前に印刷するメッセージ。 デフォルトは
"Press any key to continue..."
です。err –メッセージに設定されている場合、エコーの場合と同じように、
stdout
ではなくstderr
に移動します。
- click.get_terminal_size() os.terminal_size
端末の現在のサイズをタプルとして
(width, height)
の形式で列と行に返します。バージョン8.0以降非推奨: Click8.1で削除されます。 代わりに
shutil.get_terminal_size()
を使用してください。
- click.get_binary_stream(name: te.Literal[stdin, stdout, stderr]) BinaryIO
- バイト処理用のシステムストリームを返します。
- パラメーター
- name –開くストリームの名前。 有効な名前は、
'stdin'
、'stdout'
、および'stderr'
です。
- click.get_text_stream(name: te.Literal[stdin, stdout, stderr], encoding: Optional[str] = None, errors: Optional[str] = 'strict') TextIO
- テキスト処理用のシステムストリームを返します。 これは通常、 get_binary_stream()から返されたバイナリストリームの周りにラップされたストリームを返しますが、すでに正しく構成されているストリームへのショートカットを取ることもできます。
- パラメーター
- ;;* name –開くストリームの名前。 有効な名前は、
'stdin'
、'stdout'
、および'stderr'
です。
- encoding –検出されたデフォルトのエンコーディングを上書きします。
- errors –デフォルトのエラーモードを上書きします。
- click.open_file(filename: str, mode: str = 'r', encoding: Optional[str] = None, errors: Optional[str] = 'strict', lazy: bool = False, atomic: bool = False) IO
これは、ファイルの動作と似ていますが、手動で使用します。 デフォルトでは、ファイルは遅延なしで開かれます。 これにより、
'-'
が渡された場合、stdin / stdoutだけでなく通常のファイルも開くことができます。stdin / stdoutが返されると、コンテキストマネージャーが誤ってストリームを閉じないように、ストリームがラップされます。 これにより、標準ストリームを誤って閉じることを心配することなく、常に次のような関数を使用できます。
with open_file(filename) as f: ...
バージョン3.0の新機能。
- パラメーター
filename –開くファイルの名前(またはstdin / stdoutの場合は
'-'
)。mode –ファイルを開くモード。
encoding –使用するエンコーディング。
errors –このファイルのエラー処理。
lazy – trueに反転して、ファイルを遅延して開くことができます。
atomic –アトミックモードでは、書き込みは一時ファイルに送られ、閉じるときに移動されます。
- click.get_app_dir(app_name: str, roaming: bool = True, force_posix: bool = False) str
アプリケーションのconfigフォルダーを返します。 デフォルトの動作では、オペレーティングシステムに最も適切なものを返します。
アイデアを与えるために、
"Foo Bar"
というアプリの場合、次のフォルダーのようなものが返される可能性があります。- Mac OS X:
~/Library/Application Support/Foo Bar
- Mac OS X(POSIX):
~/.foo-bar
- Unix:
~/.config/foo-bar
- Unix(POSIX):
~/.foo-bar
- Windows(ローミング):
C:\Users\<user>\AppData\Roaming\Foo Bar
- Windows(ローミングではない):
C:\Users\<user>\AppData\Local\Foo Bar
バージョン2.0の新機能。
- パラメーター
app_name –アプリケーション名。 これは適切に大文字にする必要があり、空白を含めることができます。
ローミング –Windowsでフォルダーをローミングするかどうかを制御します。 それ以外の影響はありません。
force_posix –これが True に設定されている場合、POSIXシステムでは、フォルダーはXDG構成ホームまたはdarwinのアプリケーションサポートフォルダーではなく、先頭にドットが付いたホームフォルダーに保存されます。
- click.format_filename(filename: Union[str, bytes, os.PathLike], shorten: bool = False) str
- ユーザーが表示できるようにファイル名をフォーマットします。 この関数の主な目的は、ファイル名を表示できるようにすることです。 これにより、失敗しないように、必要に応じてファイル名がUnicodeにデコードされます。 オプションで、ファイル名を短くして、ファイル名へのフルパスを含めないようにすることができます。
- パラメーター
- ;;* filename –UI表示用のファイル名をフォーマットします。 これにより、ファイル名が失敗することなくユニコードに変換されます。
- shorten –これは、オプションで、ファイル名を短縮して、それにつながるパスを削除します。
コマンド
- class click.BaseCommand(name: Optional[str], context_settings: Optional[Dict[str, Any]] = None)
基本コマンドは、コマンドの最小限のAPIコントラクトを実装します。 ほとんどのコードは、多くの便利な機能を実装していないため、これを使用することはありませんが、クリックパーサーに依存しない代替の解析メソッドの直接のサブクラスとして機能できます。
たとえば、これを使用して、Clickとargparseやdocoptなどの他のシステムをブリッジできます。
基本コマンドは、Clickの他の部分が当然と考える多くのAPIを実装していないため、すべての操作でサポートされているわけではありません。 たとえば、通常はデコレータと一緒に使用することはできず、コールバックシステムが組み込まれていません。
バージョン2.0で変更: context_settings パラメーターが追加されました。
- パラメーター
name –グループがコマンドをオーバーライドしない限り使用するコマンドの名前。
context_settings –コンテキストオブジェクトに渡されるデフォルトのオプションの辞書。
- allow_extra_args = False
Context.allow_extra_args フラグのデフォルト。
- allow_interspersed_args = True
Context.allow_interspersed_args フラグのデフォルト。
- context_class
make_context()で作成するコンテキストクラス。
バージョン8.0の新機能。
click.core.Context のエイリアス
- context_settings: Dict[str, Any]
デフォルトがコンテキストに渡されるオプションの辞書。
- ignore_unknown_options = False
Context.ignore_unknown_options フラグのデフォルト。
- invoke(ctx: click.core.Context) Any
コンテキストが与えられると、これはコマンドを呼び出します。 デフォルトの実装では、実装されていないエラーが発生します。
- main(args: Optional[Sequence[str]] = None, prog_name: Optional[str] = None, complete_var: Optional[str] = None, standalone_mode: bool = True, windows_expand_args: bool = True, **extra: Any) Any
これは、コマンドラインアプリケーションとしてすべてのベルとホイッスルを使用してスクリプトを呼び出す方法です。 これにより、呼び出し後に常にアプリケーションが終了します。 これが望ましくない場合は、
SystemExit
をキャッチする必要があります。このメソッドは、コマンドのインスタンスを直接呼び出すことによっても使用できます。
- パラメーター
args –解析に使用する必要のある引数。 指定しない場合は、
sys.argv[1:]
が使用されます。prog_name –使用する必要のあるプログラム名。 デフォルトでは、プログラム名は
sys.argv[0]
からファイル名を取得して作成されます。complete_var –bash完了サポートを制御する環境変数。 デフォルトは
"_<prog_name>_COMPLETE"
で、prog_nameは大文字です。Standalone_mode –デフォルトの動作では、スタンドアロンモードでスクリプトを呼び出します。 Clickは例外を処理し、それらをエラーメッセージに変換します。関数は決して戻りませんが、インタープリターをシャットダウンします。 これが False に設定されている場合、それらは呼び出し元に伝播され、この関数の戻り値は invoke()の戻り値になります。
windows_expand_args – Windowsのコマンドライン引数でglobパターン、ユーザーdir、およびenv変数を展開します。
extra –追加のキーワード引数がコンテキストコンストラクターに転送されます。 詳細については、コンテキストを参照してください。
バージョン8.0.1で変更:
windows_expand_args
パラメーターを追加して、Windowsでコマンドライン引数の拡張を無効にできるようにしました。バージョン8.0で変更: Windowsで
sys.argv
から引数を取得すると、globパターン、ユーザーdir、およびenv変数が展開されます。バージョン3.0で変更:
standalone_mode
パラメーターが追加されました。
- make_context(info_name: Optional[str], args: List[str], parent: Optional[click.core.Context] = None, **extra: Any) click.core.Context
この関数に情報名と引数を指定すると、解析が開始され、新しいコンテキストが作成されます。 ただし、実際のコマンドコールバックは呼び出されません。
このメソッドをオーバーライドせずに使用されるコンテキストクラスをすばやくカスタマイズするには、 context_class 属性を設定します。
- パラメーター
info_name –この呼び出しの情報名。 通常、これはスクリプトまたはコマンドの最もわかりやすい名前です。 トップレベルのスクリプトの場合、通常はスクリプトの名前であり、その下のコマンドの場合はコマンドの名前です。
args –文字列のリストとして解析する引数。
parent –利用可能な場合は親コンテキスト。
extra –コンテキストコンストラクターに転送される追加のキーワード引数。
バージョン8.0で変更: context_class 属性が追加されました。
- name
コマンドが持つと考える名前。 グループにコマンドを登録すると、グループはこの情報を使用してコマンド名をデフォルトにします。 代わりに、 Context ' s info_name 属性を使用する必要があります。
- parse_args(ctx: click.core.Context, args: List[str]) List[str]
コンテキストと引数のリストが与えられると、これはパーサーを作成して引数を解析し、必要に応じてコンテキストを変更します。 これは、 make_context()によって自動的に呼び出されます。
- shell_complete(ctx: click.core.Context, incomplete: str) List[CompletionItem]
不完全な値の完了のリストを返します。 チェーンされたマルチコマンドの名前を調べます。
どのコマンドも連鎖マルチコマンドの一部である可能性があるため、兄弟コマンドはコマンド補完中の任意の時点で有効です。 他のコマンドクラスは、より多くの補完を返します。
- パラメーター
ctx –このコマンドの呼び出しコンテキスト。
不完全 –値が完了しています。 空の可能性があります。
バージョン8.0の新機能。
- to_info_dict(ctx: click.core.Context) Dict[str, Any]
ユーザー向けのドキュメントを生成するツールに役立つ可能性のある情報を収集します。 これは、このコマンドの下の構造全体をトラバースします。
click.Context.to_info_dict()を使用して、CLI構造全体をトラバースします。
- パラメーター
ctx –このコマンドを表すコンテキスト。
バージョン8.0の新機能。
- class click.Command(name: Optional[str], context_settings: Optional[Dict[str, Any]] = None, callback: Optional[Callable[[...], Any]] = None, params: Optional[List[click.core.Parameter]] = None, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False)
コマンドは、Clickのコマンドラインインターフェイスの基本的な構成要素です。 基本的なコマンドはコマンドライン解析を処理し、その下にネストされたコマンドにより多くの解析をディスパッチする場合があります。
バージョン2.0で変更: context_settings パラメーターが追加されました。
バージョン8.0で変更:コマンド名を示すreprを追加
バージョン7.1で変更: no_args_is_help パラメーターが追加されました。
- パラメーター
name –グループがコマンドをオーバーライドしない限り使用するコマンドの名前。
context_settings –コンテキストオブジェクトに渡されるデフォルトのオプションの辞書。
callback –呼び出すコールバック。 これはオプションです。
params –このコマンドに登録するパラメーター。 これは、 Option または Argument オブジェクトのいずれかです。
help –このコマンドに使用するヘルプ文字列。
epilog –ヘルプ文字列と同様ですが、他のすべての後にヘルプページの最後に出力されます。
short_help –このコマンドに使用する短いヘルプ。 これは、親コマンドのコマンドリストに表示されます。
add_help_option –デフォルトでは、各コマンドは
--help
オプションを登録します。 これは、このパラメーターによって無効にできます。no_args_is_help –これは引数が指定されていない場合に何が起こるかを制御します。 このオプションはデフォルトで無効になっています。 有効にすると、引数が渡されない場合、引数として
--help
が追加されますhidden –このコマンドをヘルプ出力から非表示にします。
deprecated –コマンドが非推奨であることを示すメッセージを発行します。
- callback
コマンドが起動したときに実行するコールバック。 これはなしである可能性があり、その場合は何も起こりません。
- collect_usage_pieces(ctx: click.core.Context) List[str]
使用ラインに入るすべての部分を返し、それを文字列のリストとして返します。
- format_epilog(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) None
エピローグが存在する場合は、フォーマッターに書き込みます。
- format_help(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) None
ヘルプが存在する場合は、フォーマッタに書き込みます。
これは、 get_help()によって呼び出される低レベルのメソッドです。
これにより、次のメソッドが呼び出されます。
- format_help_text(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) None
ヘルプテキストが存在する場合は、フォーマッタに書き込みます。
- format_options(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) None
すべてのオプションが存在する場合は、フォーマッターに書き込みます。
- format_usage(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) None
使用ラインをフォーマッタに書き込みます。
これは、 get_usage()によって呼び出される低レベルのメソッドです。
- get_help(ctx: click.core.Context) str
ヘルプを文字列にフォーマットして返します。
内部で format_help()を呼び出します。
- get_help_option(ctx: click.core.Context) Optional[click.core.Option]
ヘルプオプションオブジェクトを返します。
- get_help_option_names(ctx: click.core.Context) List[str]
ヘルプオプションの名前を返します。
- get_short_help_str(limit: int = 45) str
コマンドの短いヘルプを取得するか、長いヘルプ文字列を短くして作成します。
- get_usage(ctx: click.core.Context) str
使用ラインを文字列にフォーマットして返します。
内部で format_usage()を呼び出します。
- invoke(ctx: click.core.Context) Any
コンテキストが与えられると、これは添付されたコールバック(存在する場合)を正しい方法で呼び出します。
- make_parser(ctx: click.core.Context) click.parser.OptionParser
このコマンドの基礎となるオプションパーサーを作成します。
- params: List[click.core.Parameter]
ヘルプページに表示されて実行される順序でのこのコマンドのパラメーターのリスト。 熱心なパラメータは、熱心でないパラメータよりも先に自動的に処理されます。
- parse_args(ctx: click.core.Context, args: List[str]) List[str]
コンテキストと引数のリストが与えられると、これはパーサーを作成して引数を解析し、必要に応じてコンテキストを変更します。 これは
make_context()
によって自動的に呼び出されます。
- shell_complete(ctx: click.core.Context, incomplete: str) List[CompletionItem]
不完全な値の完了のリストを返します。 オプションとチェーンされたマルチコマンドの名前を調べます。
- パラメーター
ctx –このコマンドの呼び出しコンテキスト。
不完全 –値が完了しています。 空の可能性があります。
バージョン8.0の新機能。
- to_info_dict(ctx: click.core.Context) Dict[str, Any]
ユーザー向けのドキュメントを生成するツールに役立つ可能性のある情報を収集します。 これは、このコマンドの下の構造全体をトラバースします。
click.Context.to_info_dict()を使用して、CLI構造全体をトラバースします。
- パラメーター
ctx –このコマンドを表すコンテキスト。
バージョン8.0の新機能。
- class click.MultiCommand(name: Optional[str] = None, invoke_without_command: bool = False, no_args_is_help: Optional[bool] = None, subcommand_metavar: Optional[str] = None, chain: bool = False, result_callback: Optional[Callable[[...], Any]] = None, **attrs: Any)
マルチコマンドは、サブコマンドにディスパッチするコマンドの基本的な実装です。 最も一般的なバージョンはグループです。
- パラメーター
invoke_without_command –これはマルチコマンド自体の呼び出し方法を制御します。 デフォルトでは、サブコマンドが指定されている場合にのみ呼び出されます。
no_args_is_help –これは引数が指定されていない場合に何が起こるかを制御します。 このオプションは、 invoke_without_command が無効になっている場合はデフォルトで有効になっており、有効になっている場合は無効になっています。 有効にすると、引数が渡されない場合、引数として
--help
が追加されます。subcommand_metavar –サブコマンドの場所を示すためにドキュメントで使用される文字列。
chain –これが True に設定されている場合、複数のサブコマンドの連鎖が有効になります。 これにより、オプションの引数を持つことができないという点でコマンドの形式が制限されますが、複数のコマンドをチェーン化することはできます。
result_callback –このマルチコマンドにアタッチする結果コールバック。 これは、後で result_callback()デコレータを使用して設定または変更できます。
- collect_usage_pieces(ctx: click.core.Context) List[str]
使用ラインに入るすべての部分を返し、それを文字列のリストとして返します。
- format_commands(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) None
オプションの後にすべてのコマンドを追加するマルチメソッドの追加フォーマットメソッド。
- format_options(ctx: click.core.Context, formatter: click.formatting.HelpFormatter) None
すべてのオプションが存在する場合は、フォーマッターに書き込みます。
- get_command(ctx: click.core.Context, cmd_name: str) Optional[click.core.Command]
コンテキストとコマンド名を指定すると、 Command オブジェクトが存在する場合はそれを返すか、 None を返します。
- invoke(ctx: click.core.Context) Any
コンテキストが与えられると、これは添付されたコールバック(存在する場合)を正しい方法で呼び出します。
- list_commands(ctx: click.core.Context) List[str]
表示される順序でサブコマンド名のリストを返します。
- parse_args(ctx: click.core.Context, args: List[str]) List[str]
コンテキストと引数のリストが与えられると、これはパーサーを作成して引数を解析し、必要に応じてコンテキストを変更します。 これは
make_context()
によって自動的に呼び出されます。
- result_callback(replace: bool = False) Callable[[click.core.F], click.core.F]
コマンドに結果コールバックを追加します。 デフォルトでは、結果コールバックがすでに登録されている場合、これはそれらをチェーンしますが、これは replace パラメーターで無効にできます。 結果のコールバックは、サブコマンドの戻り値(または、チェーンが有効になっている場合はすべてのサブコマンドからの戻り値のリスト)と、メインのコールバックに渡されるパラメーターを使用して呼び出されます。
例:
@click.group() @click.option('-i', '--input', default=23) def cli(input): return 42 @cli.result_callback() def process_result(result, input): return result + input
- パラメーター
replace – True に設定すると、既存の結果コールバックが削除されます。
バージョン8.0で変更:
resultcallback
から名前が変更されました。バージョン3.0の新機能。
- shell_complete(ctx: click.core.Context, incomplete: str) List[CompletionItem]
不完全な値の完了のリストを返します。 オプション、サブコマンド、および連鎖マルチコマンドの名前を確認します。
- パラメーター
ctx –このコマンドの呼び出しコンテキスト。
不完全 –値が完了しています。 空の可能性があります。
バージョン8.0の新機能。
- to_info_dict(ctx: click.core.Context) Dict[str, Any]
ユーザー向けのドキュメントを生成するツールに役立つ可能性のある情報を収集します。 これは、このコマンドの下の構造全体をトラバースします。
click.Context.to_info_dict()を使用して、CLI構造全体をトラバースします。
- パラメーター
ctx –このコマンドを表すコンテキスト。
バージョン8.0の新機能。
- class click.Group(name: Optional[str] = None, commands: Optional[Union[Dict[str, click.core.Command], Sequence[click.core.Command]]] = None, **attrs: Any)
グループを使用すると、コマンドにサブコマンドを添付できます。 これは、Clickでネストを実装するための最も一般的な方法です。
- パラメーター
name –グループコマンドの名前。
コマンド –名前をコマンドオブジェクトにマッピングするdict。 コマンドのリストにすることもできます。これは、
Command.name
を使用してdictを作成します。attrs – MultiCommand 、 Command 、および BaseCommand で説明されているその他のコマンド引数。
バージョン8.0で変更:
commmands
引数は、コマンドオブジェクトのリストにすることができます。- add_command(cmd: click.core.Command, name: Optional[str] = None) None
このグループに別のコマンドを登録します。 名前が指定されていない場合は、コマンドの名前が使用されます。
- command(*args: Any, **kwargs: Any) Callable[[Callable[[...], Any]], click.core.Command]
コマンドを宣言してグループにアタッチするためのショートカットデコレータ。 これは command()と同じ引数を取り、 add_command()を呼び出すことにより、作成されたコマンドをこのグループにすぐに登録します。
使用するコマンドクラスをカスタマイズするには、 command_class 属性を設定します。
バージョン8.0で変更: command_class 属性が追加されました。
- command_class: Optional[Type[click.core.Command]] = None
設定されている場合、これはグループの command()デコレータによってデフォルトの Command クラスとして使用されます。 これは、すべてのサブコマンドでカスタムコマンドクラスを使用する場合に役立ちます。
バージョン8.0の新機能。
- commands: Dict[str, click.core.Command]
エクスポートされた名前で登録されたサブコマンド。
- get_command(ctx: click.core.Context, cmd_name: str) Optional[click.core.Command]
コンテキストとコマンド名を指定すると、 Command オブジェクトが存在する場合はそれを返すか、 None を返します。
- group(*args: Any, **kwargs: Any) Callable[[Callable[[...], Any]], click.core.Group]
グループを宣言してグループにアタッチするためのショートカットデコレータ。 これは group()と同じ引数を取り、 add_command()を呼び出すことにより、作成されたグループをこのグループにすぐに登録します。
使用するグループクラスをカスタマイズするには、 group_class 属性を設定します。
バージョン8.0で変更: group_class 属性が追加されました。
- group_class: Optional[Union[Type[click.core.Group], Type[type]]] = None
設定されている場合、これはグループの group()デコレータによってデフォルトの Group クラスとして使用されます。 これは、すべてのサブグループにカスタムグループクラスを使用させるのに役立ちます。
特別な値
type
(文字通りgroup_class = type
)に設定すると、このグループのクラスがデフォルトのクラスとして使用されます。 これにより、カスタムグループクラスは引き続きカスタムグループを作成します。バージョン8.0の新機能。
- list_commands(ctx: click.core.Context) List[str]
表示される順序でサブコマンド名のリストを返します。
- class click.CommandCollection(name: Optional[str] = None, sources: Optional[List[click.core.MultiCommand]] = None, **attrs: Any)
コマンドコレクションは、複数のマルチコマンドを1つにマージするマルチコマンドです。 これは、さまざまなマルチコマンドのリストをソースとして受け入れ、それぞれにすべてのコマンドを提供する簡単な実装です。
- add_source(multi_cmd: click.core.MultiCommand) None
チェーンディスパッチャに新しいマルチコマンドを追加します。
- get_command(ctx: click.core.Context, cmd_name: str) Optional[click.core.Command]
コンテキストとコマンド名を指定すると、 Command オブジェクトが存在する場合はそれを返すか、 None を返します。
- list_commands(ctx: click.core.Context) List[str]
表示される順序でサブコマンド名のリストを返します。
- sources: List[click.core.MultiCommand]
登録されているマルチコマンドのリスト。
パラメーター
- class click.Parameter(param_decls: Optional[Sequence[str]] = None, type: Optional[Union[click.types.ParamType, Any]] = None, required: bool = False, default: Optional[Union[Any, Callable[[], Any]]] = None, callback: Optional[Callable[[click.core.Context, Parameter, Any], Any]] = None, nargs: Optional[int] = None, multiple: bool = False, metavar: Optional[str] = None, expose_value: bool = True, is_eager: bool = False, envvar: Optional[Union[Sequence[str], str]] = None, shell_complete: Optional[Callable[[click.core.Context, Parameter, str], Union[List[CompletionItem], List[str]]]] = None, autocompletion: Optional[Callable[[click.core.Context, List[str], str], List[Union[Tuple[str, str], str]]]] = None)
コマンドのパラメーターには、 Option または Argument の2つのバージョンがあります。 他のサブクラスは、解析の内部の一部が意図的に確定されていないため、現在、設計ではサポートされていません。
一部の設定は、オプションと引数の両方でサポートされています。
- パラメーター
param_decls –このオプションまたは引数のパラメーター宣言。 これは、フラグまたは引数名のリストです。
type –使用する必要のあるタイプ。 ParamType またはPythonタイプのいずれか。 サポートされている場合、後者は自動的に前者に変換されます。
required –これがオプションかどうかを制御します。
default –省略した場合のデフォルト値。 これは呼び出し可能にすることもできます。その場合、引数なしでデフォルトが必要なときに呼び出されます。
callback –型変換後に値をさらに処理または検証する関数。
f(ctx, param, value)
と呼ばれ、値を返す必要があります。 プロンプトを含むすべてのソースに対して呼び出されます。nargs –一致する引数の数。
1
でない場合、戻り値は単一の値ではなくタプルになります。 nargsのデフォルトは1
です(タイプがタプルの場合を除いて、それはタプルのアリティです)。nargs=-1
の場合、残りのすべてのパラメーターが収集されます。metavar –ヘルプページでの値の表示方法。
expose_value –これが True の場合、値はコマンドコールバックに渡され、コンテキストに保存されます。それ以外の場合はスキップされます。
is_eager –熱心な値は非熱心な値の前に処理されます。 これは引数に設定しないでください。設定しないと、処理の順序が逆になります。
envvar –チェックする必要のある環境変数である文字列または文字列のリスト。
shell_complete –カスタムシェル補完を返す関数。 指定されている場合、paramの型補完の代わりに使用されます。
ctx, param, incomplete
を取り、CompletionItem
のリストまたは文字列のリストを返す必要があります。
バージョン8.0で変更:
process_value
は、必要なパラメーターと境界nargs
を検証し、値を返す前にパラメーターコールバックを呼び出します。 これにより、コールバックでプロンプトを検証できます。full_process_value
が削除されました。バージョン8.0で変更:
autocompletion
はshell_complete
に名前が変更され、上記の新しいセマンティクスが追加されました。 古い名前は非推奨になり、8.1で削除されます。それまでは、新しい要件に一致するようにラップされます。バージョン8.0で変更:
multiple=True, nargs>1
の場合、デフォルトはタプルのリストである必要があります。バージョン8.0で変更:
nargs>1
のデフォルトを設定する必要がなくなり、デフォルトでNone
になります。multiple=True
またはnargs=-1
は、デフォルトで()
になります。バージョン7.1で変更:空の文字列値を取得するのではなく、空の環境変数が無視されます。 これにより、スクリプトで変数の設定を解除できない場合でも、変数をクリアすることができます。
バージョン2.0で変更:パラメーターコールバックのシグネチャも変更され、パラメーターも渡されるようになりました。 古いコールバック形式は引き続き機能しますが、コードを簡単に移行する機会を与える警告が表示されます。
- get_default(ctx: click.core.Context, call: bool = True) Optional[Union[Any, Callable[[], Any]]]
パラメータのデフォルトを取得します。 最初に
Context.lookup_value()
を試行し、次にローカルデフォルトを試行します。- パラメーター
ctx –現在のコンテキスト。
call –デフォルトが呼び出し可能である場合は、それを呼び出します。 代わりに呼び出し可能オブジェクトを返す場合は無効にします。
バージョン8.0.1で変更:型キャストは復元力のある解析モードで失敗する可能性があります。 デフォルトが無効な場合でも、ヘルプテキストの表示が妨げられることはありません。
バージョン8.0で変更:最初に
ctx.default_map
を確認します。バージョン8.0で変更:
call
パラメーターが追加されました。
- get_error_hint(ctx: click.core.Context) str
エラーメッセージで使用するパラメータの文字列バージョンを取得して、エラーの原因となったパラメータを示します。
- property human_readable_name: str
このパラメータの人間が読める形式の名前を返します。 これはオプションの名前と同じですが、引数のメタ変数です。
- shell_complete(ctx: click.core.Context, incomplete: str) List[CompletionItem]
不完全な値の完了のリストを返します。 初期化中に
shell_complete
関数が指定された場合は、それが使用されます。 それ以外の場合は、type
shell_complete()
機能が使用されます。- パラメーター
ctx –このコマンドの呼び出しコンテキスト。
不完全 –値が完了しています。 空の可能性があります。
バージョン8.0の新機能。
- to_info_dict() Dict[str, Any]
ユーザー向けのドキュメントを生成するツールに役立つ可能性のある情報を収集します。
click.Context.to_info_dict()を使用して、CLI構造全体をトラバースします。
バージョン8.0の新機能。
- type_cast_value(ctx: click.core.Context, value: Any) Any
オプションの
type
、multiple
、およびnargs
に対して値を変換して検証します。
- class click.Option(param_decls: Optional[Sequence[str]] = None, show_default: bool = False, prompt: Union[bool, str] = False, confirmation_prompt: Union[bool, str] = False, prompt_required: bool = True, hide_input: bool = False, is_flag: Optional[bool] = None, flag_value: Optional[Any] = None, multiple: bool = False, count: bool = False, allow_from_autoenv: bool = True, type: Optional[Union[click.types.ParamType, Any]] = None, help: Optional[str] = None, hidden: bool = False, show_choices: bool = True, show_envvar: bool = False, **attrs: Any)
オプションは通常、コマンドラインのオプション値であり、引数にはない追加機能がいくつかあります。
他のすべてのパラメーターは、パラメーターコンストラクターに渡されます。
- パラメーター
show_default –デフォルト値をヘルプページに表示するかどうかを制御します。 通常、デフォルトは表示されません。 この値が文字列の場合、値の代わりに文字列が表示されます。 これは、動的オプションで特に役立ちます。
show_envvar –環境変数をヘルプページに表示するかどうかを制御します。 通常、環境変数は表示されません。
prompt – True または空でない文字列に設定されている場合、ユーザーは入力を求められます。 True に設定すると、プロンプトは大文字のオプション名になります。
commentation_prompt –プロンプトが表示された場合は、値を確認するためにもう一度プロンプトを表示します。
True
の代わりに文字列に設定して、メッセージをカスタマイズできます。prompt_required –
False
に設定すると、オプションが値のないフラグとして指定された場合にのみ、ユーザーは入力を求められます。hide_input –これが True の場合、プロンプトの入力はユーザーから非表示になります。 これはパスワード入力に役立ちます。
is_flag –このオプションを強制的にフラグとして機能させます。 デフォルトは自動検出です。
flag_value –有効になっている場合、このフラグに使用する値。 オプション文字列に2つのオプションをマークするスラッシュが含まれている場合、これは自動的にブール値に設定されます。
multiple –これが True に設定されている場合、引数は複数回受け入れられ、記録されます。 これは、動作方法が
nargs
に似ていますが、任意の数の引数をサポートします。count –このフラグは、オプションのインクリメントを整数にします。
allow_from_autoenv –これが有効になっている場合、コンテキストでプレフィックスが定義されていると、このパラメーターの値が環境変数から取得されます。
help –ヘルプ文字列。
hidden –このオプションをヘルプ出力から非表示にします。
バージョン8.0.1で変更:
type
は、指定されている場合、flag_value
から検出されます。
- class click.Argument(param_decls: Sequence[str], required: Optional[bool] = None, **attrs: Any)
引数は、コマンドの定位置パラメーターです。 これらは通常、オプションよりも少ない機能を提供しますが、無限の
nargs
を持つことができ、デフォルトで必要です。すべてのパラメーターは、パラメーターコンストラクターに渡されます。
コンテクスト
- class click.Context(command: click.core.Command, parent: Optional[click.core.Context] = None, info_name: Optional[str] = None, obj: Optional[Any] = None, auto_envvar_prefix: Optional[str] = None, default_map: Optional[Dict[str, Any]] = None, terminal_width: Optional[int] = None, max_content_width: Optional[int] = None, resilient_parsing: bool = False, allow_extra_args: Optional[bool] = None, allow_interspersed_args: Optional[bool] = None, ignore_unknown_options: Optional[bool] = None, help_option_names: Optional[List[str]] = None, token_normalize_func: Optional[Callable[[str], str]] = None, color: Optional[bool] = None, show_default: Optional[bool] = None)
コンテキストは、すべての単一レベルでのスクリプト実行に関連する状態を保持する特別な内部オブジェクトです。 コマンドへのアクセスをオプトインしない限り、通常はコマンドからは見えません。
コンテキストは、内部オブジェクトを渡したり、環境変数からのデータの読み取りなどの特別な実行機能を制御したりできるので便利です。
コンテキストはコンテキストマネージャーとして使用できます。その場合、ティアダウン時に close()が呼び出されます。
- パラメーター
command –このコンテキストのコマンドクラス。
parent –親コンテキスト。
info_name –この呼び出しの情報名。 通常、これはスクリプトまたはコマンドの最もわかりやすい名前です。 トップレベルのスクリプトの場合、通常はスクリプトの名前であり、その下のコマンドの場合はスクリプトの名前です。
obj –ユーザーデータの任意のオブジェクト。
auto_envvar_prefix –自動環境変数に使用するプレフィックス。 これが None の場合、環境変数からの読み取りは無効になります。 これは、常に読み取られる手動で設定された環境変数には影響しません。
default_map –パラメーターのデフォルト値を持つディクショナリ(オブジェクトなど)。
terminal_width –端末の幅。 デフォルトは、親コンテキストから継承します。 端子幅を定義するコンテキストがない場合は、自動検出が適用されます。
max_content_width –クリックによってレンダリングされるコンテンツの最大幅(これは現在、ヘルプページにのみ影響します)。 オーバーライドされない場合、これはデフォルトで80文字になります。 つまり、端末がそれよりも大きい場合でも、Clickはデフォルトで80文字を超えるものをフォーマットしません。 それに加えて、フォーマッターは右側にいくつかの安全マッピングを追加する場合があります。
resilient_parsing –このフラグが有効になっている場合、Clickは対話性やコールバックの呼び出しなしで解析します。 デフォルト値も無視されます。 これは、完了サポートなどの実装に役立ちます。
allow_extra_args –これが True に設定されている場合、最後に追加の引数を指定してもエラーは発生せず、コンテキストに保持されます。 デフォルトでは、コマンドから継承します。
allow_interspersed_args –これが False に設定されている場合、オプションと引数を混在させることはできません。 デフォルトでは、コマンドから継承します。
ignore_unknown_options –不明なオプションを無視するようにクリックに指示し、後の処理のためにそれらを保持します。
help_option_names –オプションで、デフォルトのヘルプパラメーターの命名方法を定義する文字列のリスト。 デフォルトは
['--help']
です。token_normalize_func –トークン(オプション、選択肢など)を正規化するために使用されるオプションの関数。 たとえば、これを使用して、大文字と小文字を区別しない動作を実装できます。
color –端末がANSIカラーをサポートするかどうかを制御します。 デフォルトは自動検出です。 これは、クリックが印刷するテキストでANSIコードが使用されている場合にのみ必要ですが、デフォルトではそうではありません。 これは、たとえばヘルプ出力に影響します。
show_default –すべてのオプションのデフォルトを表示します。 設定されていない場合、デフォルトで親コンテキストの値になります。 オプションの
show_default
引数をオーバーライドします。
バージョン8.0で変更:
show_default
パラメーターは、デフォルトで親コンテキストの値になります。バージョン7.1で変更:
show_default
パラメーターが追加されました。バージョン4.0で変更:
color
、ignore_unknown_options
、およびmax_content_width
パラメーターが追加されました。バージョン3.0で変更:
allow_extra_args
およびallow_interspersed_args
パラメーターが追加されました。バージョン2.0で変更:
resilient_parsing
、help_option_names
、およびtoken_normalize_func
パラメーターが追加されました。- abort() te.NoReturn
スクリプトを中止します。
- allow_extra_args
コンテキストが追加の引数を許可するかどうか、または解析に失敗する必要があるかどうかを示します。
バージョン3.0の新機能。
- allow_interspersed_args: bool
コンテキストで引数とオプションの混合が許可されているかどうかを示します。
バージョン3.0の新機能。
- args: List[str]
残りの引数。
- call_on_close(f: Callable[[...], Any]) Callable[[...], Any]
コンテキストが破棄されたときに呼び出される関数を登録します。
これは、スクリプトの実行中に開かれたリソースを閉じるために使用できます。
with
ステートメントで使用されるPythonのコンテキストマネージャープロトコルをサポートするリソースは、代わりに with_resource()に登録する必要があります。- パラメーター
f –ティアダウン時に実行する関数。
- close() None
call_on_close()で登録されたすべてのクローズコールバックを呼び出し、 with_resource()で入力されたすべてのコンテキストマネージャーを終了します。
- color: Optional[bool]
スタイリング出力が必要かどうかを制御します。
- command
このコンテキストのコマンド。
- property command_path: str
計算されたコマンドパス。 これは、ヘルプページの
usage
情報に使用されます。 コンテキストチェーンの情報名をルートに結合することにより、自動的に作成されます。
- ensure_object(object_type: Type[click.core.V]) click.core.V
find_object()と同様ですが、最も内側のオブジェクトが存在しない場合は、 object_type の新しいインスタンスに設定します。
- exit(code: int = 0) te.NoReturn
指定された終了コードでアプリケーションを終了します。
- fail(message: str) te.NoReturn
特定のエラーメッセージを表示してプログラムの実行を中止します。
- パラメーター
message –失敗するエラーメッセージ。
- find_object(object_type: Type[click.core.V]) Optional[click.core.V]
指定されたタイプの最も近いオブジェクトを検索します。
- find_root() click.core.Context
最も外側のコンテキストを検索します。
- formatter_class
- forward(_Context__cmd: click.core.Command, *args: Any, **kwargs: Any) Any
invoke()に似ていますが、他のコマンドが予期する場合、現在のコンテキストからデフォルトのキーワード引数を入力します。 これはコールバックを直接呼び出すことはできず、他のコマンドのみを呼び出すことができます。
バージョン8.0で変更:すべての
kwargs
は params で追跡されるため、forward
が複数のレベルで呼び出された場合に渡されます。
- get_help() str
現在のコンテキストとコマンドのフォーマットされたヘルプページを取得するためのヘルパーメソッド。
- get_parameter_source(name: str) Optional[click.core.ParameterSource]
パラメータのソースを取得します。 これは、パラメーターの値が取得された場所を示します。
これは、ユーザーがコマンドラインでデフォルト値と同じ値をいつ指定したかを判断するのに役立ちます。 値が実際にデフォルトから取得された場合にのみ、
DEFAULT
になります。- パラメーター
name –パラメーターの名前。
- リターンタイプ
ParameterSource
バージョン8.0で変更:パラメーターがどのソースからも提供されなかった場合は
None
を返します。
- get_usage() str
現在のコンテキストとコマンドのフォーマットされた使用法文字列を取得するためのヘルパーメソッド。
- help_option_names: List[str]
ヘルプオプションの名前。
- ignore_unknown_options: bool
コマンドが理解できないオプションを無視するようにクリックするように指示し、後で処理するためにコンテキストに保存します。 これは主に、外部プログラムを呼び出したい状況で役立ちます。 一般に、このパターンは、すべての引数をロスレスで転送することはできないため、強くお勧めしません。
バージョン4.0の新機能。
- info_name
説明情報の名前
- invoke(_Context__callback: Union[click.core.Command, Callable[[...], Any]], *args: Any, **kwargs: Any) Any
期待どおりにコマンドコールバックを呼び出します。 このメソッドを呼び出すには、次の2つの方法があります。
最初の引数はコールバックにすることができ、他のすべての引数とキーワード引数は関数に直接転送されます。
最初の引数はクリックコマンドオブジェクトです。 その場合、すべての引数も転送されますが、適切なクリックパラメータ(オプションとクリック引数)はキーワード引数である必要があり、Clickはデフォルトを入力します。
Click 3.2より前は、このコードの意図に反してキーワード引数が適切に入力されておらず、コンテキストが作成されていないことに注意してください。 この変更とバグ修正リリースで行われた理由の詳細については、 3.2 へのアップグレードを参照してください。
- invoked_subcommand: Optional[str]
このフラグは、サブコマンドが実行されるかどうかを示します。 グループコールバックは、この情報を使用して、直接実行されているのか、実行フローがサブコマンドに渡されるのかを判断できます。 デフォルトではNoneですが、実行するサブコマンドの名前にすることもできます。
チェーンが有効になっている場合、コマンドが実行された場合に備えて、これは
'*'
に設定されます。 しかし、どれを見つけることはできません。 この知識が必要な場合は、result_callback()
を使用する必要があります。
- lookup_default(name: str, call: bool = True) Optional[Any]
default_map
からパラメータのデフォルトを取得します。- パラメーター
name –パラメーターの名前。
call –デフォルトが呼び出し可能である場合は、それを呼び出します。 代わりに呼び出し可能オブジェクトを返す場合は無効にします。
バージョン8.0で変更:
call
パラメーターが追加されました。
- make_formatter() click.formatting.HelpFormatter
ヘルプと使用法の出力用に HelpFormatter を作成します。
このメソッドをオーバーライドせずに使用するフォーマッタークラスをすばやくカスタマイズするには、 formatter_class 属性を設定します。
バージョン8.0で変更: formatter_class 属性が追加されました。
- max_content_width: Optional[int]
フォーマットされたコンテンツの最大幅(ほとんどの場合80である実用的なデフォルトを意味するものはありません)。
- property meta: Dict[str, Any]
これは、ネストされているすべてのコンテキストと共有される辞書です。 クリックユーティリティが必要に応じてここに状態を保存できるようにするために存在します。 ただし、この辞書を適切に管理するのは、そのコードの責任です。
キーは一意の点線の文字列であると想定されています。 たとえば、モジュールパスはそのための良い選択です。 そこに保存されているものは、クリックの操作とは無関係です。 ただし、重要なのは、ここにデータを配置するコードがシステムの一般的なセマンティクスに準拠していることです。
使用例:
LANG_KEY = f'{__name__}.lang' def set_language(value): ctx = get_current_context() ctx.meta[LANG_KEY] = value def get_language(): return get_current_context().meta.get(LANG_KEY, 'en_US')
バージョン5.0の新機能。
- obj: Any
保存されているユーザーオブジェクト。
- params: Dict[str, Any]
パラメータ名の解析値へのマップ。
expose_value=False
のパラメーターは保存されません。
- parent
親コンテキスト、または存在しない場合は None 。
- protected_args: List[str]
保護された引数。 これらは、特定の解析シナリオが発生したときに args の前に付加される引数ですが、別の引数に伝播してはなりません。 これは、ネストされた解析を実装するために使用されます。
- resilient_parsing: bool
復元力のある解析が有効になっているかどうかを示します。 その場合、Clickは失敗を引き起こさないように最善を尽くし、デフォルト値は無視されます。 完了に役立ちます。
- scope(cleanup: bool = True) Iterator[click.core.Context]
このヘルパーメソッドをコンテキストオブジェクトとともに使用して、現在のスレッドローカルにプロモートできます( get_current_context()を参照)。 これのデフォルトの動作は、 cleanup を False に設定することで無効にできるクリーンアップ関数を呼び出すことです。 クリーンアップ関数は通常、ファイルハンドルを閉じるなどの目的で使用されます。
クリーンアップが意図されている場合は、コンテキストオブジェクトをコンテキストマネージャーとして直接使用することもできます。
使用例:
with ctx.scope(): assert get_current_context() is ctx
これは同等です:
with ctx: assert get_current_context() is ctx
バージョン5.0の新機能。
- パラメーター
cleanup –クリーンアップ機能を実行するかどうかを制御します。 デフォルトでは、これらの関数を実行します。 状況によっては、コンテキストを一時的にプッシュしたいだけの場合があります。その場合、これを無効にすることができます。 ネストされたプッシュは、クリーンアップを自動的に延期します。
- set_parameter_source(name: str, source: click.core.ParameterSource) None
パラメータのソースを設定します。 これは、パラメーターの値が取得された場所を示します。
- パラメーター
name –パラメーターの名前。
source –
ParameterSource
のメンバー。
- show_default: Optional[bool]
ヘルプテキストをフォーマットするときにオプションのデフォルト値を表示します。
- terminal_width: Optional[int]
端末の幅(自動検出はありません)。
- to_info_dict() Dict[str, Any]
ユーザー向けのドキュメントを生成するツールに役立つ可能性のある情報を収集します。 これにより、CLI構造全体がトラバースされます。
with Context(cli) as ctx: info = ctx.to_info_dict()
バージョン8.0の新機能。
- token_normalize_func: Optional[Callable[[str], str]]
トークンのオプションの正規化関数。 これは、オプション、選択肢、コマンドなどです。
- with_resource(context_manager: ContextManager[click.core.V]) click.core.V
with
ステートメントで使用されているかのようにリソースを登録します。 コンテキストがポップされると、リソースがクリーンアップされます。contextlib.ExitStack.enter_context()
を使用します。 リソースの__enter__()
メソッドを呼び出し、結果を返します。 コンテキストがポップされると、スタックが閉じられ、リソースの__exit__()
メソッドが呼び出されます。コンテキストマネージャではないもののクリーンアップ関数を登録するには、 call_on_close()を使用します。 または、
contextlib
の何かを使用して、最初にコンテキストマネージャーに変換します。@click.group() @click.option("--name") @click.pass_context def cli(ctx): ctx.obj = ctx.with_resource(connect_db(name))
- パラメーター
context_manager –入力するコンテキストマネージャー。
- 戻り値
context_manager.__enter__()
が返すものは何でも。
バージョン8.0の新機能。
- click.get_current_context(silent: bool = False) Optional[Context]
現在のクリックコンテキストを返します。 これは、どこからでも現在のコンテキストオブジェクトにアクセスする方法として使用できます。 これは、 pass_context()デコレータのより暗黙的な代替手段です。 この関数は主に、現在のコンテキストに基づいて動作を変更することに関心がある echo()などのヘルパーに役立ちます。
現在のコンテキストをプッシュするには、 Context.scope()を使用できます。
バージョン5.0の新機能。
- パラメーター
silent – True に設定されている場合、使用可能なコンテキストがない場合、戻り値は None です。 デフォルトの動作では、
RuntimeError
が発生します。
種類
- click.STRING = STRING
- click.INT = INT
- click.FLOAT = FLOAT
- click.BOOL = BOOL
- click.UUID = UUID
- click.UNPROCESSED = UNPROCESSED
- 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.Tuple(types: Sequence[Union[Type, click.types.ParamType]])
Clickのデフォルトの動作は、値にタイプを直接適用することです。 これは、 nargs が固定カウントに設定されており、アイテムごとに異なるタイプを使用する必要がある場合を除いて、ほとんどの場合にうまく機能します。 この場合、タプルタイプを使用できます。 このタイプは、 nargs が固定数に設定されている場合にのみ使用できます。
詳細については、マルチバリューオプションとしてのタプルを参照してください。
これは、Pythonタプルリテラルを型として使用して選択できます。
- パラメーター
types –タプルアイテムに使用する必要があるタイプのリスト。
- class click.ParamType
パラメータのタイプを表します。 コマンドラインまたはPythonからの値を検証し、正しいタイプに変換します。
カスタム型を実装するには、サブクラス化して、少なくとも以下を実装します。
name クラス属性を設定する必要があります。
None
を使用してタイプのインスタンスを呼び出すと、None
が返される必要があります。 これはすでにデフォルトで実装されています。convert()は、文字列値を正しいタイプに変換する必要があります。
convert()は、すでに正しいタイプの値を受け入れる必要があります。
ctx
およびparam
引数がNone
の場合、値を変換できる必要があります。 これは、プロンプト入力を変換するときに発生する可能性があります。
- convert(value: Any, param: Optional[Parameter], ctx: Optional[Context]) Any
値を正しいタイプに変換します。 値が
None
(欠落している値)の場合、これは呼び出されません。これは、コマンドラインからの文字列値と、すでに正しいタイプの値を受け入れる必要があります。 また、他の互換性のあるタイプを変換する場合もあります。
param
およびctx
引数は、プロンプト入力を変換する場合など、特定の状況ではNone
になる場合があります。値を変換できない場合は、説明メッセージを付けて fail()を呼び出します。
- パラメーター
value –変換する値。
param –このタイプを使用して値を変換しているパラメーター。
None
の可能性があります。ctx –この値に到達した現在のコンテキスト。
None
の可能性があります。
- envvar_list_splitter: ClassVar[Optional[str]] = None
このタイプのリストが予期され、値が文字列環境変数から取得される場合、これがそれを分割するものです。 なしは空白を意味します。 すべてのパラメーターについて、一般的な規則は、空白がそれらを分割することです。 例外は、デフォルトで
os.path.pathsep
によって分割されるパスとファイルです(Unixでは「:」、Windowsでは「;」)。
- fail(message: str, param: Optional[Parameter] = None, ctx: Optional[Context] = None) t.NoReturn
無効な値のメッセージで失敗するヘルパーメソッド。
- get_metavar(param: Parameter) Optional[str]
このパラメータが提供されている場合は、このパラメータのデフォルトのmetavarを返します。
- get_missing_message(param: Parameter) Optional[str]
オプションで、欠落しているパラメーターに関する追加情報を返す場合があります。
バージョン2.0の新機能。
- name: str
このタイプの説明的な名前
- shell_complete(ctx: Context, param: Parameter, incomplete: str) List[CompletionItem]
不完全な値の
CompletionItem
オブジェクトのリストを返します。 ほとんどのタイプは補完を提供しませんが、一部は補完を提供します。これにより、カスタムタイプでもカスタム補完を提供できます。- パラメーター
ctx –このコマンドの呼び出しコンテキスト。
param –完了を要求しているパラメーター。
不完全 –値が完了しています。 空の可能性があります。
バージョン8.0の新機能。
- split_envvar_value(rv: str) Sequence[str]
環境変数からの値が与えられると、これは定義されたenvvarリストスプリッターに応じてそれを小さなチャンクに分割します。
スプリッターが None に設定されている場合、つまり空白が分割されている場合、先頭と末尾の空白は無視されます。 それ以外の場合、先頭と末尾のスプリッターは通常、空のアイテムが含まれることになります。
- to_info_dict() Dict[str, Any]
ユーザー向けのドキュメントを生成するツールに役立つ可能性のある情報を収集します。
click.Context.to_info_dict()を使用して、CLI構造全体をトラバースします。
バージョン8.0の新機能。
例外
- exception click.ClickException(message: str)
- Clickが処理してユーザーに表示できる例外。
- exception click.Abort
- クリックして中止するように通知する内部シグナリング例外。
- exception click.UsageError(message: str, ctx: Optional[Context] = None)
- 使用エラーを通知する内部例外。 これは通常、それ以上の処理を中止します。
- パラメーター
- ;;* message –表示するエラーメッセージ。
- ctx –オプションでこのエラーの原因となったコンテキスト。 クリックすると、状況によっては自動的にコンテキストが入力されます。
- exception click.BadParameter(message: str, ctx: Optional[Context] = None, param: Optional[Parameter] = None, param_hint: Optional[str] = None)
不正なパラメータの標準化されたエラーメッセージをフォーマットする例外。 これは、Clickがコンテキスト情報(たとえば、どのパラメーターであるか)を添付するため、コールバックまたはタイプからスローされる場合に役立ちます。
バージョン2.0の新機能。
- パラメーター
param –このエラーの原因となったパラメータオブジェクト。 これは省略できます。可能であれば、Clickはこの情報自体を添付します。
param_hint –パラメーター名として表示される文字列。 これは、カスタム検証が発生する必要がある場合に、 param の代わりに使用できます。 文字列の場合はそのまま使用され、リストの場合は各項目が引用符で囲まれて区切られます。
- exception click.FileError(filename: str, hint: Optional[str] = None)
- ファイルを開くことができない場合に発生します。
- exception click.NoSuchOption(option_name: str, message: Optional[str] = None, possibilities: Optional[Sequence[str]] = None, ctx: Optional[Context] = None)
クリックが存在しないオプションを処理しようとした場合に発生します。
バージョン4.0の新機能。
- exception click.BadOptionUsage(option_name: str, message: str, ctx: Optional[Context] = None)
オプションが一般的に提供されているが、オプションの使用が正しくなかった場合に発生します。 これは、たとえば、オプションの引数の数が正しくない場合に発生します。
バージョン4.0の新機能。
- パラメーター
option_name –誤って使用されているオプションの名前。
- exception click.BadArgumentUsage(message: str, ctx: Optional[Context] = None)
引数が一般的に提供されているが、引数の使用が正しくなかった場合に発生します。 これは、たとえば、引数の値の数が正しくない場合に発生します。
バージョン6.0の新機能。
フォーマット
- class click.HelpFormatter(indent_increment: int = 2, width: Optional[int] = None, max_width: Optional[int] = None)
このクラスは、テキストベースのヘルプページのフォーマットに役立ちます。 これは通常、非常に特殊な内部ケースに必要なだけですが、開発者が独自の派手な出力を作成できるように公開されています。
現在、常にメモリに書き込みます。
- パラメーター
indent_increment –各レベルの追加の増分。
width –テキストの幅。 これはデフォルトで最大78にクランプされた端子幅になります。
- dedent() None
インデントを減らします。
- getvalue() str
バッファの内容を返します。
- indent() None
インデントを増やします。
- indentation() Iterator[None]
インデントを増やすコンテキストマネージャー。
- section(name: str) Iterator[None]
段落、見出し、インデントを作成する便利なコンテキストマネージャー。
- パラメーター
name –見出しとして記述されるセクション名。
- write(string: str) None
Unicode文字列を内部バッファに書き込みます。
- write_dl(rows: Sequence[Tuple[str, str]], col_max: int = 30, col_spacing: int = 2) None
定義リストをバッファに書き込みます。 これは、オプションとコマンドが通常フォーマットされる方法です。
- パラメーター
rows –用語と値の2つのアイテムタプルのリスト。
col_max –最初の列の最大幅。
col_spacing –最初の列と2番目の列の間のスペースの数。
- write_heading(heading: str) None
見出しをバッファに書き込みます。
- write_paragraph() None
段落をバッファに書き込みます。
- write_text(text: str) None
再インデントされたテキストをバッファに書き込みます。 これにより、段落が再ラップされて保持されます。
- write_usage(prog: str, args: str = , prefix: Optional[str] = None) None
使用ラインをバッファに書き込みます。
- パラメーター
prog –プログラム名。
args –空白で区切られた引数のリスト。
prefix –最初の行のプレフィックス。 デフォルトは
"Usage: "
です。
- click.wrap_text(text: str, width: int = 78, initial_indent: str = , subsequent_indent: str = , preserve_paragraphs: bool = False) str
テキストをインテリジェントに折り返すヘルパー関数。 デフォルトでは、テキストの1つの段落で動作することを前提としていますが、 prepare_paragraphs パラメーターが指定されている場合、段落(2つの空の行で定義)をインテリジェントに処理します。
段落が処理される場合、段落の前に
\b
文字(\x08
)を含む空の行を付けて、そのブロックで再折り返しが発生しないことを示すことができます。- パラメーター
text –再折り返しする必要のあるテキスト。
width –テキストの最大幅。
initial_indent –文字列として最初の行に配置する必要がある最初のインデント。
subsequent_indent –連続する各行に配置する必要のあるインデント文字列。
prepare_paragraphs –このフラグが設定されている場合、ラッピングは段落をインテリジェントに処理します。
構文解析
- class click.OptionParser(ctx: Optional[Context] = None)
オプションパーサーは、オプションと引数を解析するために最終的に使用される内部クラスです。 optparseをモデルにしており、同様ですが大幅に簡素化されたAPIを提供します。 高レベルのClickクラスがそれをラップするため、通常は直接使用しないでください。
上位レベルで実装されている機能(タイプやデフォルトなど)を実装していないため、optparseやargparseほど拡張性はありません。
- パラメーター
ctx –オプションでこのパーサーを配置する Context 。
- add_argument(obj: CoreArgument, dest: Optional[str], nargs: int = 1) None
dest という名前の位置引数をパーサーに追加します。
obj を使用して、パーサーから返されるオーダーリスト内のオプションを識別できます。
- add_option(obj: CoreOption, opts: Sequence[str], dest: Optional[str], action: Optional[str] = None, nargs: int = 1, const: Optional[Any] = None) None
dest という名前の新しいオプションをパーサーに追加します。 宛先は(optparseとは異なり)推測されないため、明示的に指定する必要があります。 アクションは、
store
、store_const
、append
、appnd_const
、またはcount
のいずれかになります。obj を使用して、パーサーから返されるオーダーリスト内のオプションを識別できます。
- allow_interspersed_args
これは、パーサーが散在する引数を処理する方法を制御します。 これが False に設定されている場合、パーサーは最初の非オプションで停止します。 Clickはこれを使用して、ネストされたサブコマンドを安全に実装します。
- ctx
このパーサーのコンテキスト。 一部の高度なユースケースでは、これは None の場合があります。
- ignore_unknown_options
これは、パーサーに不明なオプションの処理方法を指示します。 デフォルトではエラーが発生しますが(これは賢明です)、それを無視して、すべての不明なオプションを結果の引数にシフトした後、処理を続行する2番目のモードがあります。
- parse_args(args: List[str]) Tuple[Dict[str, Any], List[str], List[CoreParameter]]
位置引数を解析し、解析されたオプションと引数、および残りの引数がある場合は
(values, args, order)
を返します。 順序は、コマンドラインに表示されるオブジェクトのリストです。 引数が複数回出現する場合、それらも複数回記憶されます。
テスト
- class click.testing.CliRunner(charset: str = 'utf-8', env: Optional[Mapping[str, Optional[str]]] = None, echo_stdin: bool = False, mix_stderr: bool = True)
CLIランナーは、分離された環境で単体テストを行うためにClickコマンドラインスクリプトを呼び出す機能を提供します。 これは、グローバルインタープリターの状態を変更するため、並行性のないシングルスレッドシステムでのみ機能します。
- パラメーター
charset –入力および出力データの文字セット。
env –オーバーライドするための環境変数を含む辞書。
echo_stdin –これが True に設定されている場合、stdinからの読み取りはstdoutに書き込みます。 これは、状況によっては例を示すのに役立ちます。 通常のプロンプトは自動的に入力をエコーすることに注意してください。
mix_stderr –これが False に設定されている場合、stdoutとstderrは独立したストリームとして保持されます。 これは、予測可能なstdoutとノイズの多いstderrがあり、それぞれを個別に測定できるUnix哲学アプリに役立ちます。
- get_default_prog_name(cli: BaseCommand) str
コマンドオブジェクトを指定すると、デフォルトのプログラム名が返されます。 デフォルトは name 属性、または設定されていない場合は
"root"
です。
- invoke(cli: BaseCommand, args: Optional[Union[str, Sequence[str]]] = None, input: Optional[Union[str, bytes, IO]] = None, env: Optional[Mapping[str, Optional[str]]] = None, catch_exceptions: bool = True, color: bool = False, **extra: Any) click.testing.Result
隔離された環境でコマンドを呼び出します。 引数はコマンドラインスクリプトに直接転送され、 extra キーワード引数はコマンドの
main()
関数に渡されます。これにより、 Result オブジェクトが返されます。
- パラメーター
cli –呼び出すコマンド
args –呼び出す引数。 iterableまたはstringとして指定できます。 文字列として指定すると、Unixシェルコマンドとして解釈されます。 詳細については、
shlex.split()
をご覧ください。input – sys.stdin の入力データ。
env –環境がオーバーライドされます。
catch_exceptions –
SystemExit
以外の例外をキャッチするかどうか。extra –
main()
に渡すキーワード引数。color –出力にカラーコードを含めるかどうか。 アプリケーションは、これを明示的にオーバーライドできます。
バージョン8.0で変更:結果オブジェクトには、呼び出されたコマンドから返された値を持つ
return_value
属性があります。バージョン4.0で変更:
color
パラメーターが追加されました。バージョン3.0で変更:
catch_exceptions
パラメーターが追加されました。バージョン3.0で変更:結果オブジェクトには
exc_info
属性があり、使用可能な場合はトレースバックがあります。
- isolated_filesystem(temp_dir: Optional[Union[str, os.PathLike]] = None) Iterator[str]
一時ディレクトリを作成し、現在の作業ディレクトリをそれに変更するコンテキストマネージャ。 これにより、CWDの内容に影響を与えるテストが分離され、相互に干渉するのを防ぎます。
- パラメーター
temp_dir –このディレクトリの下に一時ディレクトリを作成します。 指定した場合、作成されたディレクトリは終了時に削除されません。
バージョン8.0で変更:
temp_dir
パラメーターが追加されました。
- isolation(input: Optional[Union[str, bytes, IO]] = None, env: Optional[Mapping[str, Optional[str]]] = None, color: bool = False) Iterator[Tuple[_io.BytesIO, Optional[_io.BytesIO]]]
コマンドラインツールを呼び出すための分離を設定するコンテキストマネージャー。 これにより、指定された入力データを使用してstdinが設定され、指定されたディクショナリからのオーバーライドを使用して os.environ が設定されます。 これにより、クリックしてモックされる内部の一部も再バインドされます(プロンプト機能など)。
これは、 invoke()メソッドで自動的に実行されます。
- パラメーター
input –sys.stdinに入力する入力ストリーム。
env –環境は辞書としてオーバーライドされます。
color –出力にカラーコードを含めるかどうか。 アプリケーションは、これを明示的にオーバーライドできます。
バージョン8.0で変更:
stderr
は、デフォルトの"strict"
ではなくerrors="backslashreplace"
で開かれます。バージョン4.0で変更:
color
パラメーターが追加されました。
- make_env(overrides: Optional[Mapping[str, Optional[str]]] = None) Mapping[str, Optional[str]]
スクリプトを呼び出すための環境オーバーライドを返します。
- class click.testing.Result(runner: click.testing.CliRunner, stdout_bytes: bytes, stderr_bytes: Optional[bytes], return_value: Any, exit_code: int, exception: Optional[BaseException], exc_info: Optional[Tuple[Type[BaseException], BaseException, types.TracebackType]] = None)
呼び出されたCLIスクリプトのキャプチャされた結果を保持します。
- exc_info
トレースバック
- exception
発生した場合に発生した例外。
- exit_code
整数としての終了コード。
- property output: str
ユニコード文字列としての(標準)出力。
- return_value
呼び出されたコマンドから返される値。
バージョン8.0の新機能。
- runner
結果を生み出したランナー
- property stderr: str
Unicode文字列としての標準エラー。
- stderr_bytes
バイト単位の標準エラー、または使用できない場合はなし
- property stdout: str
Unicode文字列としての標準出力。
- stdout_bytes
バイトとしての標準出力。