進(jìn)階fPython 命令行 深入 click 之選項(xiàng)

給選項(xiàng)命名
click.option 中的命令規(guī)則可參考參數(shù)名稱[2]。它接受的前兩個(gè)參數(shù)為長(zhǎng)、短選項(xiàng)（順序隨意），其中：

長(zhǎng)選項(xiàng)以 “--” 開(kāi)頭，比如 “--string-to-echo”
短選項(xiàng)以 “-” 開(kāi)頭，比如 “-s”
第三個(gè)參數(shù)為選項(xiàng)參數(shù)的名稱，如果不指定，將會(huì)使用長(zhǎng)選項(xiàng)的下劃線形式名稱：

@click.command()
@click.option('-s', '--string-to-echo')
def echo(string_to_echo):
    click.echo(string_to_echo)

顯示指定為 string

@click.command()
@click.option('-s', '--string-to-echo', 'string')
def echo(string):
    click.echo(string)

基本值選項(xiàng)
值選項(xiàng)是非常常用的選項(xiàng)，它接受一個(gè)值。如果在命令行中提供了值選項(xiàng)，則需要提供對(duì)應(yīng)的值；反之則使用默認(rèn)值。若沒(méi)在 click.option 中指定默認(rèn)值，則默認(rèn)值為 None，且該選項(xiàng)的類型為 STRING[3]；反之，則選項(xiàng)類型為默認(rèn)值的類型。

比如，提供默認(rèn)值為 1，則選項(xiàng)類型為 INT[4]：

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

如果要求選項(xiàng)為必填，則可指定 click.option 的 required=True：

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

如果選項(xiàng)名稱和 Python 中的關(guān)鍵字沖突，則可以顯式的指定選項(xiàng)名稱。比如將 --from 的名稱設(shè)置為 from_：

@click.command()
@click.option('--from', '-f', 'from_')
@click.option('--to', '-t')
def reserved_param_name(from_, to):
    click.echo(f'from {from_} to {to}')

如果要在幫助中顯式默認(rèn)值，則可指定 click.option 的 show_default=True：

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

在命令行中調(diào)用則有：

$ dots --help
Usage: dots [OPTIONS]

Options:
  --n INTEGER  [default: 1]
  --help       Show this message a
```nd exit.
 **多值選項(xiàng)**
有時(shí)，我們會(huì)希望命令行中一個(gè)選項(xiàng)能接收多個(gè)值，通過(guò)指定 click.option 中的 nargs 參數(shù)（必須是大于等于 0）。這樣，接收的多值選項(xiàng)就會(huì)變成一個(gè)元組。

比如，在下面的示例中，當(dāng)通過(guò) --pos 指定多個(gè)值時(shí)，pos 變量就是一個(gè)元組，里面的每個(gè)元素是一個(gè) float：

@click.command()
@click.option('--pos', nargs=2, type=float)
def findme(pos):
click.echo(pos)

在命令行中調(diào)用則有：

$ findme --pos 2.0 3.0
(1.0, 2.0)

有時(shí)，通過(guò)同一選項(xiàng)指定的多個(gè)值得類型可能不同，這個(gè)時(shí)候可以指定 click.option 中的 type=(類型1, 類型2, ...) 來(lái)實(shí)現(xiàn)。而由于元組的長(zhǎng)度同時(shí)表示了值的數(shù)量，所以就無(wú)須指定 nargs 參數(shù)。

@click.command()
@click.option('--item', type=(str, int))
def putitem(item):
click.echo('name=%s id=%d' % item)

在命令行中調(diào)用則有：

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

**多選項(xiàng)**
不同于多值選項(xiàng)是通過(guò)一個(gè)選項(xiàng)指定多個(gè)值，多選項(xiàng)則是使用多個(gè)相同選項(xiàng)分別指定值，通過(guò) click.option 中的 multiple=True 來(lái)實(shí)現(xiàn)。

當(dāng)我們定義如下多選項(xiàng)：

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

便可以指定任意數(shù)量個(gè)選項(xiàng)來(lái)指定值，獲取到的 message 是一個(gè)元組：

$ commit -m foo -m bar --message baz
foo
bar
baz

**計(jì)值選項(xiàng)**
有時(shí)我們可能需要獲得選項(xiàng)的數(shù)量，那么可以指定 click.option 中的 count=True 來(lái)實(shí)現(xiàn)。

最常見(jiàn)的使用場(chǎng)景就是指定多個(gè) --verbose 或 -v 選項(xiàng)來(lái)表示輸出內(nèi)容的詳細(xì)程度。

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

在命令行中調(diào)用則有：

$ log -vvv
Verbosity: 3

通過(guò)上面的例子，verbose 就是數(shù)字，表示 -v 選項(xiàng)的數(shù)量，由此可以進(jìn)一步使用該值來(lái)控制日志的詳細(xì)程度。

** 布爾選項(xiàng)**
布爾選項(xiàng)用來(lái)表示真或假，它有多種實(shí)現(xiàn)方式：

通過(guò) click.option 的 is_flag=True 參數(shù)來(lái)實(shí)現(xiàn)：
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)

** 特性切換選項(xiàng)**
所謂特性切換就是切換同一個(gè)操作對(duì)象的不同特性，比如指定 --upper 就讓輸出大寫，指定 --lower 就讓輸出小寫。這么來(lái)看，布爾值其實(shí)是特性切換的一個(gè)特例。

要實(shí)現(xiàn)特性切換選項(xiàng)，需要讓多個(gè)選項(xiàng)都有相同的參數(shù)名稱，并且定義它們的標(biāo)記值 flag_value：

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)())

在命令行中調(diào)用則有：

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

在上面的示例中，--upper 和 --lower 都有相同的參數(shù)值 transformation：

當(dāng)指定 --upper 時(shí)，transformation 就是 --upper 選項(xiàng)的標(biāo)記值 upper
當(dāng)指定 --lower 時(shí)，transformation 就是 --lower 選項(xiàng)的標(biāo)記值 lower
進(jìn)而就可以做進(jìn)一步的業(yè)務(wù)邏輯處理。

**選擇項(xiàng)選項(xiàng)**
選擇項(xiàng)選項(xiàng) 和 上篇文章中介紹的 選擇項(xiàng)參數(shù) 類似，只不過(guò)是限定選項(xiàng)內(nèi)容，依舊是通過(guò) type=click.Choice 實(shí)現(xiàn)。此外，case_sensitive=False 還可以忽略選項(xiàng)內(nèi)容的大小寫。

@click.command()@click.option('--hash-type',
br/>@click.option('--hash-type',
def digest(hash_type):
click.echo(hash_type)
在命令行中調(diào)用則有：

$ 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": invalid choice: foo. (choose from MD5, SHA1)

$ digest --help
Usage: digest [OPTIONS]

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

**提示選項(xiàng)**
顧名思義，當(dāng)提供了選項(xiàng)卻沒(méi)有提供對(duì)應(yīng)的值時(shí)，會(huì)提示用戶輸入值。這種交互式的方式會(huì)讓命令行變得更加友好。通過(guò)指定 click.option 中的 prompt 可以實(shí)現(xiàn)。

當(dāng) prompt=True 時(shí)，提示內(nèi)容為選項(xiàng)的參數(shù)名稱

@click.command()
@click.option('--name', prompt=True)
def hello(name):
click.echo(f'Hello {name}!')
在命令行調(diào)用則有：

$ hello --name=John
Hello John!
$ hello
Name: John
Hello John!
當(dāng) prompt='Your name please' 時(shí)，提示內(nèi)容為指定內(nèi)容@click.command()
br/>@click.command()
def hello(name):
click.echo(f'Hello {name}!')

在命令行中調(diào)用則有：

```$ hello
Your name please: John
Hello John!

基于提示選項(xiàng)，我們還可以指定 hide_input=True 來(lái)隱藏輸入，confirmation_prompt=True 來(lái)讓用戶進(jìn)行二次輸入，這非常適合輸入密碼的場(chǎng)景。

@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")}')

當(dāng)然，也可以直接使用 click.password_option：

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

我們還可以給提示選項(xiàng)設(shè)置默認(rèn)值，通過(guò) default 參數(shù)進(jìn)行設(shè)置，如果被設(shè)置為函數(shù)，則可以實(shí)現(xiàn)動(dòng)態(tài)默認(rèn)值。

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

范圍選項(xiàng)
如果希望選項(xiàng)的值在某個(gè)范圍內(nèi)，就可以使用范圍選項(xiàng)，通過(guò)指定 type=click.IntRange 來(lái)實(shí)現(xiàn)。它有兩種模式：

默認(rèn)模式（非強(qiáng)制模式），如果值不在區(qū)間范圍內(nèi)將會(huì)引發(fā)一個(gè)錯(cuò)誤。如 type=click.IntRange(0, 10) 表示范圍是 [0, 10]，超過(guò)該范圍報(bào)錯(cuò)
強(qiáng)制模式，如果值不在區(qū)間范圍內(nèi)，將會(huì)強(qiáng)制選取一個(gè)區(qū)間臨近值。如 click.IntRange(0, None, clamp=True) 表示范圍是 [0, +∞)，小于 0 則取 0，大于 20 則取 20。其中 None 表示沒(méi)有限制```@click.command()
br/>```@click.command()
@click.option('--digit', type=click.IntRange(0, 10))
def repeat(count, digit):
click.echo(str(digit) * count)

if name == 'main':
repeat()

在命令行中調(diào)用則有：

$ repeat --count=1000 --digit=5
55555555555555555555
$ repeat --count=1000 --digit=12
Usage: repeat [OPTIONS]

Error: Invalid value for "--digit": 12 is not in the valid range of 0 to 10.

**回調(diào)和優(yōu)先**
回調(diào)通過(guò) click.option 中的 callback 可以指定選項(xiàng)的回調(diào)，它會(huì)在該選項(xiàng)被解析后調(diào)用?；卣{(diào)函數(shù)的簽名如下：

def callback(ctx, param, value):
pass

其中：

ctx 是命令的上下文 click.Context[6]
param 為選項(xiàng)變量 click.Option[7]
value 為選項(xiàng)的值
使用回調(diào)函數(shù)可以完成額外的參數(shù)校驗(yàn)邏輯。比如，通過(guò) --rolls 的選項(xiàng)來(lái)指定搖骰子的方式，內(nèi)容為“{N}d{M}”，表示 M 面的骰子搖 N 次，N 和 M 都是數(shù)字。在真正的處理 rolls 前，我們需要通過(guò)回調(diào)函數(shù)來(lái)校驗(yàn)它的格式：

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):
click.echo('Rolling a %d-sided dice %d time(s)' % rolls)

這樣，當(dāng)我們輸入錯(cuò)誤格式時(shí)，變會(huì)校驗(yàn)不通過(guò)：

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

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

輸入正確格式時(shí)，則正常輸出信息：

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

優(yōu)先通過(guò) click.option 中的 is_eager 可以讓該選項(xiàng)成為優(yōu)先選項(xiàng)，這意味著它會(huì)先于所有選項(xiàng)處理。

利用回調(diào)和優(yōu)先選項(xiàng)，我們就可以很好地實(shí)現(xiàn) --version 選項(xiàng)。不論命令行中寫了多少選項(xiàng)和參數(shù)，只要包含了 --version，我們就希望它打印版本就退出，而不執(zhí)行其他選項(xiàng)的邏輯，那么就需要讓它成為優(yōu)先選項(xiàng)，并且在回調(diào)函數(shù)中打印版本。

此外，在 click 中每個(gè)選項(xiàng)都對(duì)應(yīng)到命令處理函數(shù)的同名參數(shù)，如果不想把該選項(xiàng)傳遞到處理函數(shù)中，則需要指定 expose_value=True，于是有：

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!')

當(dāng)然 click 提供了便捷的 click.version_option 來(lái)實(shí)現(xiàn) --version：

@click.command()@click.version_option(version='0.1.0')
br/>@click.version_option(version='0.1.0')
pass

**Yes 選項(xiàng)**
基于前面的學(xué)習(xí)，我們可以實(shí)現(xiàn) Yes 選項(xiàng)，也就是對(duì)于某些操作，不提供 --yes 則進(jìn)行二次確認(rèn)，提供了則直接操作：

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!')

當(dāng)然 click 提供了便捷的 click.confirmation_option 來(lái)實(shí)現(xiàn) Yes 選項(xiàng)：

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

在命令行中調(diào)用則有：

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

項(xiàng)前綴，還可使用 + 或 /，當(dāng)然在一般情況下并不建議這么做。詳情參閱官方文檔的 Other Prefix Characters[10]

**總結(jié)**
可以看出，click 對(duì)命令行選項(xiàng)的支持非常豐富和強(qiáng)大，除了支持 argarse 所支持的所有選項(xiàng)類型外，還提供了諸如 計(jì)值選項(xiàng)、特性切換選項(xiàng)、提示選項(xiàng) 等更豐富的選項(xiàng)類型。此外，還提供了從環(huán)境中讀變量等方便易用的增強(qiáng)功能。簡(jiǎn)直就是開(kāi)發(fā)命令行程序的利器。