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,且該選項的類型為 ;反之,則選項類型為默認值的類型。

比如,提供默認值為 1,則選項類型為 :

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

如果要求選項為必填,則可指定 click.optionrequired=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.optionshow_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=1338

2.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
baz

2.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.optionis_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=True

2.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)

詳情請閱讀 。

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 是命令的上下文
  • param 為選項變量
  • 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():
    pass

2.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 所不支持的,可參閱官方文檔的 和 。

click 支持指定選項前綴,你可以不使用 - 作為選項前綴,還可使用 +/,當然在一般情況下並不建議這麼做。詳情參閱官方文檔的

三、總結

可以看出,click 對命令行選項的支持非常豐富和強大,除了支持 argarse 所支持的所有選項類型外,還提供了諸如 計值選項特性切換選項提示選項 等更豐富的選項類型。此外,還提供了從環境中讀變量等方便易用的增強功能。簡直就是開發命令行程序的利器。

在下篇文章中,我們着重介紹下 click 的命令和組,這可是實現它的重要特性(任意嵌套命令)的方式。

『講解開源項目系列』——讓對開源項目感興趣的人不再畏懼、讓開源項目的發起者不再孤單。跟着我們的文章,你會發現編程的樂趣、使用和發現參与開源項目如此簡單。歡迎留言聯繫我們、加入我們,讓更多人愛上開源、貢獻開源~

本站聲明:網站內容來源於博客園,如有侵權,請聯繫我們,我們將及時處理
【其他文章推薦】

※想知道網站建置網站改版該如何進行嗎?將由專業工程師為您規劃客製化網頁設計後台網頁設計

※不管是台北網頁設計公司台中網頁設計公司,全省皆有專員為您服務

※Google地圖已可更新顯示潭子電動車充電站設置地點!!

※帶您來看台北網站建置台北網頁設計,各種案例分享

小三通物流營運型態?

※快速運回,大陸空運推薦?

您可能也會喜歡…