天天看點
傳回

Python 指令行之旅：深入 click（二）Python 指令行之旅：深入 click（二）

Python 指令行之旅：深入 click（二）

原文發表于

Prodesire 部落格

。

一、前言

在上一篇文章中，我們介紹了

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

詳情請閱讀

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

其中：

使用回調函數可以完成額外的參數校驗邏輯。比如，通過 --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

所不支援的，可參閱官方文檔的

Values from Environment Variables Multiple Values from Environment Values

click

支援指定選項字首，你可以不使用

-

作為選項字首，還可使用

+

/

，當然在一般情況下并不建議這麼做。詳情參閱官方文檔的

Other Prefix Characters

三、總結

可以看出，

click

對指令行選項的支援非常豐富和強大，除了支援

argarse

所支援的所有選項類型外，還提供了諸如

計值選項

、

特性切換選項

提示選項

等更豐富的選項類型。此外，還提供了從環境中讀變量等友善易用的增強功能。簡直就是開發指令行程式的利器。

在下篇文章中，我們着重介紹下

click

的指令群組，這可是實作它的重要特性（任意嵌套指令）的方式。

機器學習/深度學習 Linux 資料安全/隐私保護 Python Windows click python指令行 python指令non cli python指令行 python dict排序 click指令行
上一篇: Python 指令行之旅：深入 click（一）Python 指令行之旅：深入 click（一）
下一篇: 【譯】Apache Spark 資料模組化之時間次元（一）

繼續閱讀