命令行開發神器 Click 簡明指南

知識 04-01

點擊上方

「

Python開發

」，選擇「置頂公眾號」

關鍵時刻，第一時間送達！

Click 是用 Python 寫的一個第三方模塊，用於快速創建命令行。我們知道，Python 內置了一個 Argparse 的標準庫用於創建命令行，但使用起來有些繁瑣，Click 相比於 Argparse，就好比 requests 相比於 urllib。

快速使用

Click 的使用大致有兩個步驟：

使用 @click.command() 裝飾一個函數，使之成為命令行介面；使用 @click.option() 等裝飾函數，為其添加命令行選項等。它的一種典型使用形式如下：

import
click
@click
.
command
()
@click
.
option
(
"--param"
,
default
=
default_value
,
help = "description" )
def
func
(
param
):
pass

下面，讓我們看一下官方文檔的入門例子：

import
click
@click
.
command ()
@click
.
option
(
"--count"
,
default
= 1 , help = "Number of greetings." )
@click
.
option ( "--name" , prompt = "Your name" , help = "The person to greet." )
def
hello
(
count
,
name
):
"""Simple program that greets NAME for a total of COUNT times."""
for
x
in
range
(
count
):
click
.
echo
(
"Hello %s!"

%
name
)
if
__name__
==

"__main__"
:
hello
()

在上面的例子中，函數 hello 有兩個參數：count 和 name，它們的值從命令行中獲取。

@click.command() 使函數 hello 成為命令行介面；

@click.option 的第一個參數指定了命令行選項的名稱，可以看到，count 的默認值是 1；

使用 click.echo 進行輸出是為了獲得更好的兼容性，因為 print 在 Python2 和 Python3 的用法有些差別。

看看執行情況：

$ python hello
.
py
Your
name
:

Ethan

# 這裡會顯示 "Your name: "(對應代碼中的 prompt)，接受用戶輸入
Hello

Ethan
!
$ python hello
.
py
--
help
# click 幫我們自動生成了 `--help` 用法
Usage
:
hello
.
py
[
OPTIONS
]
Simple
program that greets NAME
for
a total of COUNT times
.
Options
:
--
count INTEGER
Number
of greetings
.
--
name TEXT
The
person to greet
.
--
help
Show

this
message
and

exit
.
$ python hello
.
py
--
count
3

--
name
Ethan

# 指定 count 和 name 的值
Hello

Ethan
!
Hello

Ethan
!
Hello

Ethan
!
$ python hello
.
py
--
count
=
3

--
name
=
Ethan

# 也可以使用 `=`，和上面等價
Hello

Ethan
!
Hello

Ethan
!
Hello

Ethan
!
$ python hello
.
py
--
name
=
Ethan

# 沒有指定 count，默認值是 1
Hello

Ethan
!

click.option

option 最基本的用法就是通過指定命令行選項的名稱，從命令行讀取參數值，再將其傳遞給函數。在上面的例子，我們看到，除了設置命令行選項的名稱，我們還會指定默認值，help 說明等，option 常用的設置參數如下：

default: 設置命令行參數的默認值

help: 參數說明

type: 參數類型，可以是 string, int, float 等

prompt: 當在命令行中沒有輸入相應的參數時，會根據 prompt 提示用戶輸入

nargs: 指定命令行參數接收的值的個數

下面，我們再看看相關的例子。

指定 type

我們可以使用 type 來指定參數類型：

import
click
@click
.
command
()
@click
.
option
(
"--rate"
,
type
=
float
,
help
=
"rate"
)

# 指定 rate 是 float 類型
def
show
(
rate
):
click
.
echo
(
"rate: %s"

%
rate
)
if
__name__
==

"__main__"
:
show
()

執行情況：

$ python click_type
.
py
--
rate
1
rate
:

1.0
$ python click_type
.
py
--
rate
0.66
rate
:

0.66

可選值

在某些情況下，一個參數的值只能是某些可選的值，如果用戶輸入了其他值，我們應該提示用戶輸入正確的值。在這種情況下，我們可以通過 click.Choice() 來限定：

import
click
@click
.
command
()
@click
.
option
(
"--gender"
,
type
=
click
.
Choice
([
"man"
,

"woman"
]))

# 限定值
def
choose
(
gender
):
click
.
echo
(
"gender: %s"

%
gender
)
if
__name__
==

"__main__"
:
choose
()

執行情況：

$ python click_choice
.
py
--
gender boy
Usage
:
click_choice
.
py
[
OPTIONS
]
Error
:

Invalid
value
for

"--gender"
:
invalid choice
:
boy
.

(
choose
from
man
,
woman
)
$ python click_choice
.
py
--
gender man
gender
:
man

多值參數

有時，一個參數需要接收多個值。option 支持設置固定長度的參數值，通過 nargs 指定。

看看例子就明白了：

import
click
@click
.
command
()
@click
.
option
(
"--center"
,
nargs
=
2
,
type
=
float
,
help
=
"center of the circle"
)
@click
.
option
(
"--radius"
,
type
=
float
,
help
=
"radius of the circle"
)
def
circle
(
center
,
radius
):
click
.
echo
(
"center: %s, radius: %s"

%

(
center
,
radius
))
if
__name__
==

"__main__"
:
circle
()

在上面的例子中，option 指定了兩個參數：center 和 radius，其中，center 表示二維平面上一個圓的圓心坐標，接收兩個值，以元組的形式將值傳遞給函數，而 radius 表示圓的半徑。

執行情況：

$ python click_multi_values
.
py
--
center
3

4

--
radius
10
center
:

(
3.0
,

4.0
),
radius
:

10.0
$ python click_multi_values
.
py
--
center
3

4

5

--
radius
10
Usage
:
click_multi_values
.
py
[
OPTIONS
]
Error
:

Got
unexpected extra argument
(
5
)

輸入密碼

有時，在輸入密碼的時候，我們希望能隱藏顯示。option 提供了兩個參數來設置密碼的輸入：hideinput 和 confirmationpromt，其中，hideinput 用於隱藏輸入，confirmationpromt 用於重複輸入。

看看例子：

import
click
@click
.
command
()
@click
.
option
(
"--password"
,
prompt
=
True
,
hide_input
=
True
,
confirmation_prompt
=
True
)
def
input_password
(
password
):
click
.
echo
(
"password: %s"

%
password
)
if
__name__
==

"__main__"
:
input_password
()

執行情況：

$ python click_password
.
py
Password
:

# 不會顯示密碼
Repeat

for
confirmation
:

# 重複一遍
password
:

666666

由於上面的寫法有點繁瑣，click 也提供了一種快捷的方式，通過使用 @click.password_option()，上面的代碼可以簡寫成：

import
click
@click
.
command
()
@click
.
password_option
()
def
input_password
(
password
):
click
.
echo
(
"password: %s"

%
password
)
if
__name__
==

"__main__"
:
input_password
()

改變命令行程序的執行

有些參數會改變命令行程序的執行，比如在終端輸入 python 是進入 python 控制台，而輸入 python --version 是列印 python 版本。Click 提供 eager 標識對參數名進行標識，如果輸入該參數，則會攔截既定的命令行執行流程，跳轉去執行一個回調函數。

讓我們看看例子：

import
click
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
)
@click
.
option
(
"--name"
,
default
=
"Ethan"
,
help
=
"name"
)
def
hello
(
name
):
click
.
echo
(
"Hello %s!"

%
name
)
if
__name__
==

"__main__"
:
hello
()

其中：

is_eager=True 表明該命令行選項優先順序高於其他選項；

expose_value=False 表示如果沒有輸入該命令行選項，會執行既定的命令行流程；

callback 指定了輸入該命令行選項時，要跳轉執行的函數；

執行情況：

$ python click_eager
.
py
Hello

Ethan
!
$ python click_eager
.
py
--
version
# 攔截既定的命令行執行流程
Version

1.0
$ python click_eager
.
py
--
name
Michael
Hello

Michael
!
$ python click_eager
.
py
--
version
--
name
Ethan

# 忽略 name 選項
Version

1.0

click.argument

我們除了使用 @click.option 來添加可選參數，還會經常使用 @click.argument 來添加固定參數。它的使用和 option 類似，但支持的功能比 option 少。

入門使用

下面是一個簡單的例子：

import
click
@click
.
command
()
@click
.
argument
(
"coordinates"
)
def
show
(
coordinates
):
click
.
echo
(
"coordinates: %s"

%
coordinates
)
if
__name__
==

"__main__"
:
show
()

看看執行情況：

$ python click_argument
.
py
# 錯誤，缺少參數 coordinates
Usage
:
click_argument
.
py
[
OPTIONS
]
COORDINATES
Error
:

Missing
argument
"coordinates"
.
$ python click_argument
.
py
--
help
# argument 指定的參數在 help 中沒有顯示
Usage
:
click_argument
.
py
[
OPTIONS
]
COORDINATES
Options
:
--
help
Show

this
message
and

exit
.
$ python click_argument
.
py
--
coordinates
10

# 錯誤用法，這是 option 參數的用法
Error
:

no
such option
:

--
coordinates
$ python click_argument
.
py
10

# 正確，直接輸入值即可
coordinates
:

10

多個 argument

我們再來看看多個 argument 的例子：

import
click
@click
.
command
()
@click
.
argument
(
"x"
)
@click
.
argument
(
"y"
)
@click
.
argument
(
"z"
)
def
show
(
x
,
y
,
z
):
click
.
echo
(
"x: %s, y: %s, z:%s"

%

(
x
,
y
,
z
))
if
__name__
==

"__main__"
:
show
()

執行情況：

$ python click_argument
.
py
10

20

30
x
:

10
,
y
:

20
,
z
:
30
$ python click_argument
.
py
10
Usage
:
click_argument
.
py
[
OPTIONS
]
X Y Z
Error
:

Missing
argument
"y"
.
$ python click_argument
.
py
10

20
Usage
:
click_argument
.
py
[
OPTIONS
]
X Y Z
Error
:

Missing
argument
"z"
.
$ python click_argument
.
py
10

20

30

40
Usage
:
click_argument
.
py
[
OPTIONS
]
X Y Z
Error
:

Got
unexpected extra argument
(
40
)

不定參數

argument 還有另外一種常見的用法，就是接收不定量的參數，讓我們看看例子：

import
click
@click
.
command
()
@click
.
argument
(
"src"
,
nargs
=-
1
)
@click
.
argument
(
"dst"
,
nargs
=
1
)
def
move
(
src
,
dst
):
click
.
echo
(
"move %s to %s"

%

(
src
,
dst
))
if
__name__
==

"__main__"
:
move
()

其中，nargs=-1 表明參數 src 接收不定量的參數值，參數值會以 tuple 的形式傳入函數。如果 nargs 大於等於 1，表示接收 nargs 個參數值，上面的例子中，dst 接收一個參數值。

讓我們看看執行情況：

$ python click_argument
.
py file1 trash
# src=("file1",) dst="trash"
move
(
u
"file1"
,)
to trash
$ python click_argument
.
py file1 file2 file3 trash
# src=("file1", "file2", "file3") dst="trash"
move
(
u
"file1"
,
u
"file2"
,
u
"file3"
)
to trash

彩色輸出

在前面的例子中，我們使用 click.echo 進行輸出，如果配合 colorama 這個模塊，我們可以使用 click.secho 進行彩色輸出，在使用之前，使用 pip 安裝 colorama：

$ pip install colorama

看看例子：

import
click
@click
.
command
()
@click
.
option
(
"--name"
,
help
=
"The person to greet."
)
def
hello
(
name
):
click
.
secho
(
"Hello %s!"

%
name
,
fg
=
"red"
,
underline
=
True
)
click
.
secho
(
"Hello %s!"

%
name
,
fg
=
"yellow"
,
bg
=
"black"
)
if
__name__
==

"__main__"
:
hello
()