オプション

コマンドへのオプションの追加は通過できます option() 装飾師です。オプションは様々なバージョンを持つことができるので、それらの動作を構成するための大量のパラメータがあります。オプションをクリックすると positional arguments それがそうです。

オプションを名前付けします

オプションの名前は、修飾関数を呼び出す際にPythonパラメータ名として使用されます。これはオプション名から推定することもでき，明示的に与えることもできる.名前は位置パラメータとして装飾子に提供される.

名前は以下の順にお選びください

1. 名前にプレフィックスがない場合は、コマンドライン上のオプション名ではなく、Pythonパラメータ名として使用されます。

2. 少なくとも1つの名前が2つの破折番号をプレフィックスとする場合、所与の第1の名前が名前として使用される。

3. 名前プレフィックスは、破れた番号であり、そうでなければ、その名前が使用される。

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", the name is foo_bar

• "-x", the name is x

• "-f", "--filename", "dest", the name is dest

• "--CamelCase", the name is camelcase

• "-f", "-fb", the name is f

• "--f", "--foo-bar", the name is f

• "---f", the name is _f

基本価値オプション

最も基本的なオプションは値オプションである.これらのオプションは、1つのパラメータ、すなわち1つの値を受け取る。タイプが提供されていない場合は、デフォルト値のタイプが使用されます。デフォルト値が提供されていない場合、タイプは STRING それがそうです。名前が明示的に指定されていない限り、パラメータの名前は定義された最初の長いオプションであり、そうでなければ、第1の短いオプションが使用される。デフォルトの場合，オプションは必要ではないが，オプションを必要とするためには，入力するだけでよい. required=True 装飾師に対する論争として。

@click.command()
@click.option('--n', default=1)
def dots(n):
    click.echo('.' * n)

# How to make an option required
@click.command()
@click.option('--n', required=True, type=int)
def dots(n):
    click.echo('.' * n)

# How to use a Python reserved word such as `from` as a parameter
@click.command()
@click.option('--from', '-f', 'from_')
@click.option('--to', '-t')
def reserved_param_name(from_, to):
    click.echo(f"from {from_} to {to}")

コマンドライン上で以下の動作を実行する。

$ dots --n=2
..

本例では、オプションのタイプは INT デフォルト値は整数ですから。

コマンドヘルプを表示する際にデフォルト値を表示する場合は、ご利用ください show_default=True

@click.command()
@click.option('--n', default=1, show_default=True)
def dots(n):
    click.echo('.' * n)

$ dots --help
Usage: dots [OPTIONS]

Options:
  --n INTEGER  [default: 1]
  --help       Show this message and exit.

多値オプション

場合によっては、複数のパラメータを受け入れることを選択することができます。オプションについては，固定数のパラメータのみをサポートする.これは nargs パラメータそして，これらの値をタプルとして格納する.

@click.command()
@click.option('--pos', nargs=2, type=float)
def findme(pos):
    a, b = pos
    click.echo(f"{a} / {b}")

コマンドライン上で以下の動作を実行する。

$ findme --pos 2.0 3.0
2.0 / 3.0

多値オプションとしてのタプル

Changelog

バージョン 4.0 で追加.

ご覧のように、ご利用ください nargs 結果タプル内の各項目を特定の数字に設定した場合、そのタイプは同じである。これはあなたが欲しいものではないかもしれません。一般に、タプル内の異なるインデックスに対して異なるタイプを使用することを望むことができる。このため、タプルをタイプとして直接指定することができます。

@click.command()
@click.option('--item', type=(str, int))
def putitem(item):
    name, id = item
    click.echo(f"name={name} id={id}")

コマンドライン上で以下の動作を実行する。

$ putitem --item peter 1338
name=peter id=1338

タプルテキストをタイプとして使うことで nargs タプルの長さに自動的に設定された click.Tuple タイプは自動的に使用されます。したがって、上記の例は、以下と同等である。

@click.command()
@click.option('--item', nargs=2, type=click.Tuple([str, int]))
def putitem(item):
    name, id = item
    click.echo(f"name={name} id={id}")

複数の選択肢

似たような nargs また、1つのパラメータを複数回提供し、最後の値だけではなく、すべての値を記録することをサポートしたい場合もある。例えば、 git commit -m foo -m bar メッセージを提出するために2行記録されます。 foo そして bar それがそうです。これは使用することで multiple 旗：

例：

@click.command()
@click.option('--message', '-m', multiple=True)
def commit(message):
    click.echo('\n'.join(message))

コマンドライン上で以下の動作を実行する。

$ commit -m foo -m bar
foo
bar

1つを通ると default 使用 multiple=True デフォルト値はリストまたはタプルでなければならず、そうでなければ単文字リストとして解釈されます。

@click.option("--format", multiple=True, default=["json"])

数をかぞえる

いくつかの非常にまれな場合、整数をカウントアップするために反復オプションを使用することは興味深い。これは、例えば、詳細なフラグのために使用することができる。

@click.command()
@click.option('-v', '--verbose', count=True)
def log(verbose):
    click.echo(f"Verbosity: {verbose}")

コマンドライン上で以下の動作を実行する。

$ log -vvv
Verbosity: 3

ブル旗.

ブール·マークは有効または無効になるオプションです。これはスラッシュで区切られた2つのフラグを一度に定義することで実現できる (/ )を有効または無効にするために使用されます。(オプション文字列にスラッシュがある場合、Clickは自動的にブールフラグであることを知り、渡す is_flag=True 暗黙的に。)Alwaysをクリックすると、デフォルト値を変更できるように、有効化と無効化フラグを提供したいです。

例：

import sys

@click.command()
@click.option('--shout/--no-shout', default=False)
def info(shout):
    rv = sys.platform
    if shout:
        rv = rv.upper() + '!!!!111'
    click.echo(rv)

コマンドライン上で以下の動作を実行する。

$ info --shout
LINUX!!!!111
$ info --no-shout
linux
$ info
linux

もしあなたが本当にスイッチを切りたくないなら、あなたはただ1つを定義して、Clickに何かが標識であることを手動で通知することができます。

import sys

@click.command()
@click.option('--shout', is_flag=True)
def info(shout):
    rv = sys.platform
    if shout:
        rv = rv.upper() + '!!!!111'
    click.echo(rv)

コマンドライン上で以下の動作を実行する。

$ info --shout
LINUX!!!!111
$ info
linux

オプションにスラッシュが含まれている場合(例えば、以下の位置でWindowsスタイルのパラメータを使用する場合)に注意してください / 接頭辞文字)で、パラメータを分割することもできます ; その代わりに

@click.command()
@click.option('/debug;/no-debug')
def log(debug):
    click.echo(f"debug={debug}")

if __name__ == '__main__':
    log()

Changelog

バージョン 6.0 で変更.

2番目のオプションのみにエイリアスを定義したい場合には、プリアンブルスペースを用いてフォーマット文字列の曖昧性を解消する必要がある：

例：

import sys

@click.command()
@click.option('--shout/--no-shout', ' /-S', default=False)
def info(shout):
    rv = sys.platform
    if shout:
        rv = rv.upper() + '!!!!111'
    click.echo(rv)

$ info --help
Usage: info [OPTIONS]

Options:
  --shout / -S, --no-shout
  --help                    Show this message and exit.

機能スイッチ

ブールマークのほかに機能スイッチもあります。これらは，複数のオプションを同一のパラメータ名に設定し，フラグ値を定義することで実現される.ご注意ください提供することで flag_value パラメータは、クリックして暗黙的設定を設定します。 is_flag=True それがそうです。

デフォルトフラグを設定するには、値を指定してください True デフォルト値に設定されているフラグ。

import sys

@click.command()
@click.option('--upper', 'transformation', flag_value='upper',
              default=True)
@click.option('--lower', 'transformation', flag_value='lower')
def info(transformation):
    click.echo(getattr(sys.platform, transformation)())

コマンドライン上で以下の動作を実行する。

$ info --upper
LINUX
$ info --lower
linux
$ info
LINUX

オプションを選択する

時々、あなたが望むパラメータは値リストの中の1つのオプションです。この場合、ご利用いただけます Choice タイプです。これは，実効値リストでインスタンス化することができる.コマンドライン上で渡された文字列ではなく、最初に渡されたオプションが返されます。トークン正規化関数と case_sensitive=False 二つの違いを招くかもしれないが、まだ一致している。

例：

@click.command()
@click.option('--hash-type',
              type=click.Choice(['MD5', 'SHA1'], case_sensitive=False))
def digest(hash_type):
    click.echo(hash_type)

どのように見えますか？

$ digest --hash-type=MD5
MD5

$ digest --hash-type=md5
MD5

$ digest --hash-type=foo
Usage: digest [OPTIONS]
Try 'digest --help' for help.

Error: Invalid value for '--hash-type': 'foo' is not one of 'MD5', 'SHA1'.

$ digest --help
Usage: digest [OPTIONS]

Options:
  --hash-type [MD5|SHA1]
  --help                  Show this message and exit.

オプションは、リストまたはタプルの形態でのみ転送されます。生成器のような他の反復は、意外な結果をもたらす可能性がある。

オプションは以下の条件を持つオプションに適用される multiple=True それがそうです。もし1つが default 価値がある. multiple=True これは、効率的に選択されたリストまたはタプルでなければならない。

以下のような要因の影響を考慮したうえで，選択が唯一であるはずである case_sensitive また，任意の指定されたトークン正規化関数である.

Changelog

バージョン 7.1 で変更: 選択肢の結果値は常に最初に伝達された選択肢の1つであり，いずれにしても case_sensitive それがそうです。

ヒント.

場合によっては、コマンドラインから提供されることができるパラメータが必要ですが、提供されていない場合には、ユーザの入力が要求されます。これは，提示文字列を定義してClickを用いることで実現できる.

例：

@click.command()
@click.option('--name', prompt=True)
def hello(name):
    click.echo(f"Hello {name}!")

どのように見えるのでしょうか

$ hello --name=John
Hello John!
$ hello
Name: John
Hello John!

デフォルトのプロンプト文字列に満足していない場合は、異なるプロンプト文字列を要求することができます：

@click.command()
@click.option('--name', prompt='Your name please')
def hello(name):
    click.echo(f"Hello {name}!")

どのように見えますか？

$ hello
Your name please: John
Hello John!

Trueに設定された多重フラグと一緒に提示を使用しないことを提案する.逆に，この関数を交互に提示すべきである.

デフォルトの場合，コマンドラインを介して入力が伝達されていなければ，ユーザに入力を促す.この行為を閉じるためには、参照されたい オプションの値. それがそうです。

パスワード提示

クリックすると、隠れたヒントと要求確認もサポートされます。これはパスワード入力に有用です

@click.command()
@click.option('--password', prompt=True, hide_input=True,
              confirmation_prompt=True)
def encrypt(password):
    click.echo(f"Encrypting password to {password.encode('rot13')}")

どのように見えますか？

$ encrypt
Password: 
Repeat for confirmation: 

このようなパラメータの組合せは非常に一般的であるため，これを置き換えることも可能である. password_option() 装飾師：

@click.command()
@click.password_option()
def encrypt(password):
    click.echo(f"Encrypting password to {password.encode('rot13')}")

提示された動的デフォルト値

♪the auto_envvar_prefix そして default_map コンテキストオプションは、プログラムが環境またはプロファイルからオプション値を読み出すことを可能にします。しかし，これは提示機構をカバーするため，ユーザは交互に値を変更することを選択することはできない.

ユーザにデフォルト値を構成させたい場合、コマンドラインでオプションが指定されていない場合、システムは、デフォルト値としてCallableを提供することで、これを実現することができます。例えば、環境からデフォルト値を取得するには、以下の操作を実行してください。

@click.command()
@click.option('--username', prompt=True,
              default=lambda: os.environ.get('USER', ''))
def hello(username):
    print("Hello,", username)

デフォルト値が何かを記述するには、設定してください show_default それがそうです。

@click.command()
@click.option('--username', prompt=True,
              default=lambda: os.environ.get('USER', ''),
              show_default='current user')
def hello(username):
    print("Hello,", username)

$ hello --help
Usage: hello [OPTIONS]

Options:
  --username TEXT  [default: (current user)]
  --help           Show this message and exit.

コールバックと切迫した選択肢

時々、あなたは実行プロセスを完全に変更するためのパラメータが必要だ。例えばあなたが持っていたいのは --version パラメータは、バージョンを印刷し、その後、アプリケーションを終了する。

注意： --version 再使用可能なパラメータはクリックで利用可能 click.version_option() それがそうです。ここでのコードは、そのようなフラグをどのように実現するかの例に過ぎない。

この場合、あなたは二つの概念が必要だ：緊急パラメータとコールバック。緊急パラメータは他のパラメータの前に処理されるパラメータであり，コールバックはそのパラメータを処理した後に実行されるパラメータである.このような切迫性が必要であり，このような早い必要なパラメータはエラーメッセージを発生させない.例えばもし --version 急いでいるのではなくパラメータです --foo 必要であり，その前に定義されており，それを指定する必要がある. --version 仕事に行きます。詳細についてはご参照ください 評価順序をコールバックする それがそうです。

コールバックは、2つのパラメータを使用して呼び出される関数である：現在 Context その価値がありますコンテキストは、アプリケーションを終了し、他の処理されたパラメータへのアクセスを可能にするなどの有用な機能を提供する。

次は一例です --version 旗：

def print_version(ctx, param, value):
    if not value or ctx.resilient_parsing:
        return
    click.echo('Version 1.0')
    ctx.exit()

@click.command()
@click.option('--version', is_flag=True, callback=print_version,
              expose_value=False, is_eager=True)
def hello():
    click.echo('Hello World!')

♪the expose_value パラメータはかなり無意味なことを防ぐことができます version パラメータはコールバックに渡される.指定されていなければブール値を渡す hello 脚本です。♪the resilient_parsing Clickが実行フローを変更する破壊的な行動が発生せずにコマンド行を解析したい場合には，フラグをコンテキストに適用する.この例では、私たちは手続きを脱退するので、私たちは何もしない。

どのように見えますか？

$ hello
Hello World!
$ hello --version
Version 1.0

コールバック署名変更

Click 2.0では，コールバック署名が変更された.これらの変更の詳細については、ご参照ください 2.0にアップグレードする それがそうです。

パラメータです。

危険な操作に対しては，ユーザに確認を要求できることは非常に有用である.これはブール値を加えることで実現できる --yes ユーザがフラグを提供していない場合、確認が要求され、コールバックに失敗する：

def abort_if_false(ctx, param, value):
    if not value:
        ctx.abort()

@click.command()
@click.option('--yes', is_flag=True, callback=abort_if_false,
              expose_value=False,
              prompt='Are you sure you want to drop the db?')
def dropdb():
    click.echo('Dropped all tables!')

命令ライン上の外観もあります

$ dropdb
Are you sure you want to drop the db? [y/N]: n
Aborted!
$ dropdb --yes
Dropped all tables!

このようなパラメータの組合せは非常に一般的であるため，これを置き換えることも可能である. confirmation_option() 装飾師：

@click.command()
@click.confirmation_option(prompt='Are you sure you want to drop the db?')
def dropdb():
    click.echo('Dropped all tables!')

コールバック署名変更

Click 2.0では，コールバック署名が変更された.これらの変更の詳細については、ご参照ください 2.0にアップグレードする それがそうです。

環境変数からの値

Clickの非常に有用な機能の1つは，通常のパラメータに加えて，環境変数からのパラメータを受け取ることができることである.これにより，ツールの自動化が容易になる.例えば、プロファイルと --config パラメータですが導出もサポートしています TOOL_CONFIG=hello.cfg キー-値ペアは、より良い開発体験を提供します。

Clickは2つの方法でこれを支持する。1つは，オプションのみでサポートされる環境変数を自動構築することである.この機能を有効にするには、ご利用ください auto_envvar_prefix 引数は呼び出されたスクリプトに渡す必要がある.そして，命令とパラメータごとに大文字下線ブロック変数として追加する.もしあなたが名前を持っていたら run 名前を一つ選ぶ reload 接頭辞は WEB 変数は WEB_RUN_RELOAD それがそうです。

例示的な用法：

@click.command()
@click.option('--username')
def greet(username):
    click.echo(f'Hello {username}!')

if __name__ == '__main__':
    greet(auto_envvar_prefix='GREETER')

コマンドラインから以下の動作を実行する。

$ export GREETER_USERNAME=john
$ greet
Hello john!

使用時 auto_envvar_prefix 命令群では，命令名は環境変数に含まれ，プレフィックスとパラメータ名の間に位置する必要がある. i.e. PREFIX_COMMAND_VARIABLE それがそうです。もしあなたが名前を持っていたら run-server 名前を一つ選ぶ host 接頭辞は WEB 変数は WEB_RUN_SERVER_HOST それがそうです。

例：

@click.group()
@click.option('--debug/--no-debug')
def cli(debug):
    click.echo(f"Debug mode is {'on' if debug else 'off'}")

@cli.command()
@click.option('--username')
def greet(username):
    click.echo(f"Hello {username}!")

if __name__ == '__main__':
    cli(auto_envvar_prefix='GREETER')

$ export GREETER_DEBUG=false
$ export GREETER_GREET_USERNAME=John
$ cli greet
Debug mode is off
Hello John!

2つ目のオプションは，オプション上に環境変数の名前を定義することで，特定の環境変数から値を手動で引き込むことである.

例示的な用法：

@click.command()
@click.option('--username', envvar='USERNAME')
def greet(username):
   click.echo(f"Hello {username}!")

if __name__ == '__main__':
    greet()

コマンドラインから以下の動作を実行する。

$ export USERNAME=john
$ greet
Hello john!

この場合、第1の環境変数を選択する異なる環境変数のリストであってもよい。

環境値からの複数の値

オプションは複数の値を受け取ることができるため，環境変数(文字列)からこのような値を引き込むのはやや複雑である.Clickがこの問題を解決する方法は，この行為をタイプにカスタマイズさせることである.どちらにも適用される multiple そして nargs 値が違う 1 Clickが呼び出します ParamType.split_envvar_value() メソッドは分割を実行する.

すべてのタイプのデフォルト実装は、スペース上で分割されます。このルールの例外は File そして Path いずれもオペレーティングシステムの経路分割規則によって分割されたタイプである.LinuxやOS XなどのUnixシステムでは，コロン上のファイルごとに分割される. (: )は、Windowsについては、各サブ番号に (; ）。

例示的な用法：

@click.command()
@click.option('paths', '--path', envvar='PATHS', multiple=True,
              type=click.Path())
def perform(paths):
    for path in paths:
        click.echo(path)

if __name__ == '__main__':
    perform()

コマンドラインから以下の動作を実行する。

$ export PATHS=./foo/bar:./test
$ perform
./foo/bar
./test

他の接頭辞文字

クリックすると、それ以外の接頭辞文字を処理することができます - 選択肢です。例えば，スラッシュをパラメータとして扱うためには，この機能は非常に有用である. / 似たようなものですClickは開発者がPOSIXセマンティクスに続くことを望んでいるので、通常はそうすることを強く奨励しないことに注意されたい。しかし場合によってはこれは有用かもしれません

@click.command()
@click.option('+w/-w')
def chmod(w):
    click.echo(f"writable={w}")

if __name__ == '__main__':
    chmod()

コマンドラインから以下の動作を実行する。

$ chmod +w
writable=True
$ chmod -w
writable=False

ご注意ください、もしあなたが使っているのは / 接頭辞文字として、ブールマークをご利用になりたい場合は、ご利用ください ; ではなく / ：

@click.command()
@click.option('/debug;/no-debug')
def log(debug):
    click.echo(f"debug={debug}")

if __name__ == '__main__':
    log()

範囲オプション

♪the IntRange タイプが広がった INT 値が所与の範囲に含まれることを確実にするためにキーが入力される。♪the FloatRange TYPEは以下のオブジェクトに対して同様の動作を行う. FLOAT それがそうです。

もし min あるいは…。 max 省略されています 無界の それがそうです。この方向のどんな値でも受け入れられる。デフォルトの場合、この2つの境界はいずれも 閉鎖されました これは、境界値が許容可能な範囲内に含まれることを意味する。 min_open そして max_open この境界を範囲から除外するために使用されてもよい。

If clamp mode is enabled, a value that is outside the range is set to the boundary instead of failing. For example, the range 0, 5 would return 5 for the value 10, or 0 for the value -1. When using FloatRange, clamp can only be enabled if both bounds are closed (the default).

@click.command()
@click.option("--count", type=click.IntRange(0, 20, clamp=True))
@click.option("--digit", type=click.IntRange(0, 9))
def repeat(count, digit):
    click.echo(str(digit) * count)

$ repeat --count=100 --digit=5
55555555555555555555
$ repeat --count=6 --digit=12
Usage: repeat [OPTIONS]
Try 'repeat --help' for help.

Error: Invalid value for '--digit': 12 is not in the range 0<=x<=9.

検証のためのコールバック

Changelog

バージョン 2.0 で変更.

カスタム検証ロジックを適用するには，この操作をパラメータコールバックで実行することができる.検証が機能しなければ，これらのコールバックは値を修正することもできるし，誤りを引き起こすこともできる.

Click 1.0では UsageError しかしClick 2.0から始めて BadParameter Error、これには、パラメータ名も含むようにエラーメッセージを自動的にフォーマットする追加の利点がある。

例：

def validate_rolls(ctx, param, value):
    try:
        rolls, dice = map(int, value.split('d', 2))
        return (dice, rolls)
    except ValueError:
        raise click.BadParameter('rolls need to be in format NdM')

@click.command()
@click.option('--rolls', callback=validate_rolls, default='1d6')
def roll(rolls):
    sides, times = rolls
    click.echo(f"Rolling a {sides}-sided dice {times} time(s)")

if __name__ == '__main__':
    roll()

どのように見えるのでしょうか

$ roll --rolls=42
Usage: roll [OPTIONS]

Error: Invalid value for '--rolls': rolls need to be in format NdM

$ roll --rolls=2d12
Rolling a 12-sided dice 2 time(s)

オプションの値.

オプションに値を提供することはオプションであってもよく、この場合、値を提供することなく、オプションのフラグのみが提示されるか、またはそれを使用する。 flag_value それがそうです。

設ける is_flag=False, flag_value=value Clickにはまだオプションに値を渡すことができると伝えていますが、フラグだけで指定されていれば flag_value 全部使っています。

@click.command()
@click.option("--name", is_flag=False, flag_value="Flag", default="Default")
def hello(name):
    click.echo(f"Hello, {name}!")

$ hello
Hello, Default!
$ hello --name Value
Hello, Value!
$ hello --name
Hello, Flag!

もしこのオプションが prompt 有効にして、設定します prompt_required=False そのオプションをまったく提供していない場合に提示を表示するのではなく，オプションのフラグが与えられたときにのみ提示を表示するようにClickに伝える.

@click.command()
@click.option('--name', prompt=True, prompt_required=False, default="Default")
def hello(name):
    click.echo(f"Hello {name}!")

$ hello
Hello Default!
$ hello --name Value
Hello Value!
$ hello --name
Name [Default]: Prompt
Hello Prompt!

もし required=True ただし，選択肢が与えられていなければ提示されるが，フラグのみが与えられていれば提示される.