Python 命令列之旅：深入 click 之選項篇
作者：HelloGitHub-Prodesire
HelloGitHub 的《講解開源專案》系列，專案地址：https://github.com/HelloGitHub-Team/Article
一、前言
在上一篇文章中，我們介紹了 click 中的“引數”，本文將繼續深入瞭解 click，著重講解它的“選項”。
本系列文章預設使用 Python 3 作為直譯器進行講解。
若你仍在使用 Python 2，請注意兩者之間語法和庫的使用差異哦~二、選項
通過 click.option 可以給命令增加選項，並通過配置函式的引數來配置不同功能的選項。
2.1 給選項命名
click.option
- 長選項以 “--” 開頭，比如 “--string-to-echo”
- 短選項以 “-” 開頭，比如 “-s”
第三個引數為選項引數的名稱，如果不指定，將會使用長選項的下劃線形式名稱：
@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)
2.2 基本值選項
值選項是非常常用的選項，它接受一個值。如果在命令列中提供了值選項，則需要提供對應的值；反之則使用預設值。若沒在 click.option 中指定預設值，則預設值為 None，且該選項的型別為 STRING；反之，則選項型別為預設值的型別。
比如，提供預設值為 1，則選項型別為 INT：
@click.command()
@click.option('--n', default=1)
def dots(n):
click.echo('.' * n)如果要求選項為必填，則可指定 click.option 的 required=True：
@click.command() @click.option('--n', required=True, type=int) def dots(n): click.echo('.' * n)
如果選項名稱和 Python 中的關鍵字衝突，則可以顯式的指定選項名稱。比如將 --from 的名稱設定為 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}')如果要在幫助中顯式預設值，則可指定 click.option 的 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.2.3 多值選項
有時，我們會希望命令列中一個選項能接收多個值，通過指定 click.option 中的 nargs 引數（必須是大於等於 0）。這樣，接收的多值選項就會變成一個元組。
比如，在下面的示例中，當通過 --pos 指定多個值時，pos 變數就是一個元組，裡面的每個元素是一個 float：
@click.command()
@click.option('--pos', nargs=2, type=float)
def findme(pos):
click.echo(pos)在命令列中呼叫則有：
$ findme --pos 2.0 3.0
(1.0, 2.0)有時，通過同一選項指定的多個值得型別可能不同，這個時候可以指定 click.option 中的 type=(型別1, 型別2, ...) 來實現。而由於元組的長度同時表示了值的數量，所以就無須指定 nargs 引數。
@click.command()
@click.option('--item', type=(str, int))
def putitem(item):
click.echo('name=%s id=%d' % item)在命令列中呼叫則有：
$ putitem --item peter 1338
name=peter id=13382.4 多選項
不同於多值選項是通過一個選項指定多個值，多選項則是使用多個相同選項分別指定值，通過 click.option 中的 multiple=True 來實現。
當我們定義如下多選項：
@click.command()
@click.option('--message', '-m', multiple=True)
def commit(message):
click.echo('\n'.join(message))便可以指定任意數量個選項來指定值，獲取到的 message 是一個元組：
$ commit -m foo -m bar --message baz
foo
bar
baz2.5 計值選項
有時我們可能需要獲得選項的數量，那麼可以指定 click.option 中的 count=True 來實現。
最常見的使用場景就是指定多個 --verbose 或 -v 選項來表示輸出內容的詳細程度。
@click.command()
@click.option('-v', '--verbose', count=True)
def log(verbose):
click.echo(f'Verbosity: {verbose}')在命令列中呼叫則有：
$ log -vvv
Verbosity: 3通過上面的例子，verbose 就是數字，表示 -v 選項的數量，由此可以進一步使用該值來控制日誌的詳細程度。
2.6 布林選項
布林選項用來表示真或假，它有多種實現方式：
- 通過
click.option的is_flag=True引數來實現：
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- 通過在
click.option的選項定義中使用/分隔表示真假兩個選項來實現：
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在 Windows 中，一個選項可以以 / 開頭，這樣就會真假選項的分隔符衝突了，這個時候可以使用 ; 進行分隔：
@click.command()
@click.option('/debug;/no-debug')
def log(debug):
click.echo(f'debug={debug}')
if __name__ == '__main__':
log()在 cmd 中呼叫則有：
> log /debug
debug=True2.7 特性切換選項
所謂特性切換就是切換同一個操作物件的不同特性，比如指定 --upper 就讓輸出大寫，指定 --lower 就讓輸出小寫。這麼來看，布林值其實是特性切換的一個特例。
要實現特性切換選項，需要讓多個選項都有相同的引數名稱，並且定義它們的標記值 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)())在命令列中呼叫則有：
$ info --upper
LINUX
$ info --lower
linux
$ info
LINUX在上面的示例中，--upper 和 --lower 都有相同的引數值 transformation：
- 當指定
--upper時，transformation就是--upper選項的標記值upper - 當指定
--lower時，transformation就是--lower選項的標記值lower
進而就可以做進一步的業務邏輯處理。
2.8 選擇項選項
選擇項選項 和 上篇文章中介紹的 選擇項引數 類似，只不過是限定選項內容，依舊是通過 type=click.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": invalid choice: foo. (choose from MD5, SHA1)
$ digest --help
Usage: digest [OPTIONS]
Options:
--hash-type [MD5|SHA1]
--help Show this message and exit.2.9 提示選項
顧名思義，當提供了選項卻沒有提供對應的值時，會提示使用者輸入值。這種互動式的方式會讓命令列變得更加友好。通過指定 click.option 中的 prompt 可以實現。
- 當
prompt=True時，提示內容為選項的引數名稱
@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!- 當
prompt='Your name please'時，提示內容為指定內容
@click.command()
@click.option('--name', prompt='Your name please')
def hello(name):
click.echo(f'Hello {name}!')在命令列中呼叫則有：
$ hello
Your name please: John
Hello John!基於提示選項，我們還可以指定 hide_input=True 來隱藏輸入，confirmation_prompt=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")}')當然，也可以直接使用 click.password_option：
@click.command()
@click.password_option()
def encrypt(password):
click.echo(f'Encrypting password to {password.encode("rot13")}')我們還可以給提示選項設定預設值，通過 default 引數進行設定，如果被設定為函式，則可以實現動態預設值。
@click.command()
@click.option('--username', prompt=True,
default=lambda: os.environ.get('USER', ''))
def hello(username):
print("Hello,", username)詳情請閱讀 Dynamic Defaults for Prompts。
2.10 範圍選項
如果希望選項的值在某個範圍內，就可以使用範圍選項，通過指定 type=click.IntRange 來實現。它有兩種模式：
- 預設模式（非強制模式），如果值不在區間範圍內將會引發一個錯誤。如
type=click.IntRange(0, 10)表示範圍是 [0, 10]，超過該範圍報錯 - 強制模式，如果值不在區間範圍內，將會強制選取一個區間臨近值。如
click.IntRange(0, None, clamp=True)表示範圍是 [0, +∞)，小於 0 則取 0，大於 20 則取 20。其中None表示沒有限制
@click.command()
@click.option('--count', type=click.IntRange(0, None, clamp=True))
@click.option('--digit', type=click.IntRange(0, 10))
def repeat(count, digit):
click.echo(str(digit) * count)
if __name__ == '__main__':
repeat()在命令列中呼叫則有：
$ 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.2.11 回撥和優先
回撥
通過 click.option 中的 callback 可以指定選項的回撥，它會在該選項被解析後呼叫。回撥函式的簽名如下：
def callback(ctx, param, value):
pass其中：
- ctx 是命令的上下文 click.Context
- param 為選項變數 click.Option
- value 為選項的值
使用回撥函式可以完成額外的引數校驗邏輯。比如，通過 --rolls 的選項來指定搖骰子的方式，內容為“{N}d{M}”，表示 M 面的骰子搖 N 次，N 和 M 都是數字。在真正的處理 rolls 前，我們需要通過回撥函式來校驗它的格式：
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)這樣，當我們輸入錯誤格式時，變會校驗不通過：
$ 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)優先
通過 click.option 中的 is_eager 可以讓該選項成為優先選項，這意味著它會先於所有選項處理。
利用回撥和優先選項，我們就可以很好地實現 --version 選項。不論命令列中寫了多少選項和引數，只要包含了 --version，我們就希望它列印版本就退出，而不執行其他選項的邏輯，那麼就需要讓它成為優先選項，並且在回撥函式中列印版本。
此外，在 click 中每個選項都對應到命令處理函式的同名引數，如果不想把該選項傳遞到處理函式中，則需要指定 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!')當然 click 提供了便捷的 click.version_option 來實現 --version：
@click.command()
@click.version_option(version='0.1.0')
def hello():
pass2.12 Yes 選項
基於前面的學習，我們可以實現 Yes 選項，也就是對於某些操作，不提供 --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!')當然 click 提供了便捷的 click.confirmation_option 來實現 Yes 選項：
@click.command()
@click.confirmation_option(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!2.11 其他增強功能
click 支援從環境中讀取選項的值，這是 argparse 所不支援的，可參閱官方文件的 Values from Environment Variables 和 Multiple Values from Environment Values。
click 支援指定選項字首，你可以不使用 - 作為選項字首，還可使用 + 或 /，當然在一般情況下並不建議這麼做。詳情參閱官方文件的 Other Prefix Characters
三、總結
可以看出，click 對命令列選項的支援非常豐富和強大，除了支援 argarse 所支援的所有選項型別外，還提供了諸如 計值選項、特性切換選項、提示選項 等更豐富的選項型別。此外，還提供了從環境中讀變數等方便易用的增強功能。簡直就是開發命令列程式的利器。
在下篇文章中，我們著重介紹下 click 的命令和組，這可是實現它的重要特性（任意巢狀命令）的方式。
『講解開源專案系列』——讓對開源專案感興趣的人不再畏懼、讓開源專案的發起者不再孤單。跟著我們的文章，你會發現程式設計的樂趣、使用和發現參與開源專案如此簡單。歡迎留言聯絡我們、加入我們，讓更多人愛上開源、貢獻開源