Argparse 教程?
- 作者
Tshepang Lekhonkhobe
這篇教程旨在作為 argparse
的入門介紹,此模塊是 Python 標(biāo)準(zhǔn)庫(kù)中推薦的命令行解析模塊。
備注
還有另外兩個(gè)模塊可以完成同樣的任務(wù),稱為 getopt
(對(duì)應(yīng)于 C 語(yǔ)言中的 getopt()
函數(shù)) 和被棄用的 optparse
。還要注意 argparse
是基于 optparse
的,因此用法與其非常相似。
概念?
讓我們利用 ls 命令來(lái)展示我們將要在這篇入門教程中探索的功能:
$ ls
cpython devguide prog.py pypy rm-unused-function.patch
$ ls pypy
ctypes_configure demo dotviewer include lib_pypy lib-python ...
$ ls -l
total 20
drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython
drwxr-xr-x 4 wena wena 4096 Feb 8 12:04 devguide
-rwxr-xr-x 1 wena wena 535 Feb 19 00:05 prog.py
drwxr-xr-x 14 wena wena 4096 Feb 7 00:59 pypy
-rw-r--r-- 1 wena wena 741 Feb 18 01:01 rm-unused-function.patch
$ ls --help
Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.
...
我們可以從這四個(gè)命令中學(xué)到幾個(gè)概念:
ls 是一個(gè)即使在運(yùn)行的時(shí)候沒有提供任何選項(xiàng),也非常有用的命令。在默認(rèn)情況下他會(huì)輸出當(dāng)前文件夾包含的文件和文件夾。
如果我們想要使用比它默認(rèn)提供的更多功能,我們需要告訴該命令更多信息。在這個(gè)例子里,我們想要查看一個(gè)不同的目錄,
pypy
。我們所做的是指定所謂的位置參數(shù)。之所以這樣命名,是因?yàn)槌绦驊?yīng)該如何處理該參數(shù)值,完全取決于它在命令行出現(xiàn)的位置。更能體現(xiàn)這個(gè)概念的命令如 cp,它最基本的用法是cp SRC DEST
。第一個(gè)位置參數(shù)指的是*你想要復(fù)制的*,第二個(gè)位置參數(shù)指的是*你想要復(fù)制到的位置*。現(xiàn)在假設(shè)我們想要改變這個(gè)程序的行為。在我們的例子中,我們不僅僅只是輸出每個(gè)文件的文件名,還輸出了更多信息。在這個(gè)例子中,
-l
被稱為可選參數(shù)。這是一段幫助文檔的文字。它是非常有用的,因?yàn)楫?dāng)你遇到一個(gè)你從未使用過的程序時(shí),你可以通過閱讀它的幫助文檔來(lái)弄清楚它是如何運(yùn)行的。
基礎(chǔ)?
讓我們從一個(gè)簡(jiǎn)單到(幾乎)什么也做不了的例子開始:
import argparse
parser = argparse.ArgumentParser()
parser.parse_args()
以下是該代碼的運(yùn)行結(jié)果:
$ python3 prog.py
$ python3 prog.py --help
usage: prog.py [-h]
options:
-h, --help show this help message and exit
$ python3 prog.py --verbose
usage: prog.py [-h]
prog.py: error: unrecognized arguments: --verbose
$ python3 prog.py foo
usage: prog.py [-h]
prog.py: error: unrecognized arguments: foo
程序運(yùn)行情況如下:
在沒有任何選項(xiàng)的情況下運(yùn)行腳本不會(huì)在標(biāo)準(zhǔn)輸出顯示任何內(nèi)容。這沒有什么用處。
第二行代碼開始展現(xiàn)出
argparse
模塊的作用。我們幾乎什么也沒有做,但已經(jīng)得到一條很好的幫助信息。--help
選項(xiàng),也可縮寫為-h
,是唯一一個(gè)可以直接使用的選項(xiàng)(即不需要指定該選項(xiàng)的內(nèi)容)。指定任何內(nèi)容都會(huì)導(dǎo)致錯(cuò)誤。即便如此,我們也能直接得到一條有用的用法信息。
位置參數(shù)介紹?
舉個(gè)例子:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo")
args = parser.parse_args()
print(args.echo)
運(yùn)行此程序:
$ python3 prog.py
usage: prog.py [-h] echo
prog.py: error: the following arguments are required: echo
$ python3 prog.py --help
usage: prog.py [-h] echo
positional arguments:
echo
options:
-h, --help show this help message and exit
$ python3 prog.py foo
foo
程序運(yùn)行情況如下:
我們?cè)黾恿?
add_argument()
方法,該方法用于指定程序能夠接受哪些命令行選項(xiàng)。在這個(gè)例子中,我將選項(xiàng)命名為echo
,與其功能一致。現(xiàn)在調(diào)用我們的程序必須要指定一個(gè)選項(xiàng)。
The
parse_args()
method actually returns some data from the options specified, in this case,echo
.這一變量是
argparse
免費(fèi)施放的某種 “魔法”(即是說,不需要指定哪個(gè)變量是存儲(chǔ)哪個(gè)值的)。你也可以注意到,這一名稱與傳遞給方法的字符串參數(shù)一致,都是echo
。
然而請(qǐng)注意,盡管顯示的幫助看起來(lái)清楚完整,但它可以比現(xiàn)在更有幫助。比如我們可以知道 echo
是一個(gè)位置參數(shù),但我們除了靠猜或者看源代碼,沒法知道它是用來(lái)干什么的。所以,我們可以把它改造得更有用:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo", help="echo the string you use here")
args = parser.parse_args()
print(args.echo)
然后我們得到:
$ python3 prog.py -h
usage: prog.py [-h] echo
positional arguments:
echo echo the string you use here
options:
-h, --help show this help message and exit
現(xiàn)在,來(lái)做一些更有用的事情:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number")
args = parser.parse_args()
print(args.square**2)
以下是該代碼的運(yùn)行結(jié)果:
$ python3 prog.py 4
Traceback (most recent call last):
File "prog.py", line 5, in <module>
print(args.square**2)
TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'
進(jìn)展不太順利。那是因?yàn)?argparse
會(huì)把我們傳遞給它的選項(xiàng)視作為字符串,除非我們告訴它別這樣。所以,讓我們來(lái)告訴 argparse
來(lái)把這一輸入視為整數(shù):
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number",
type=int)
args = parser.parse_args()
print(args.square**2)
以下是該代碼的運(yùn)行結(jié)果:
$ python3 prog.py 4
16
$ python3 prog.py four
usage: prog.py [-h] square
prog.py: error: argument square: invalid int value: 'four'
做得不錯(cuò)。當(dāng)這個(gè)程序在收到錯(cuò)誤的無(wú)效的輸入時(shí),它甚至能在執(zhí)行計(jì)算之前先退出,還能顯示很有幫助的錯(cuò)誤信息。
可選參數(shù)介紹?
到目前為止,我們一直在研究位置參數(shù)。讓我們看看如何添加可選的:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--verbosity", help="increase output verbosity")
args = parser.parse_args()
if args.verbosity:
print("verbosity turned on")
和輸出:
$ python3 prog.py --verbosity 1
verbosity turned on
$ python3 prog.py
$ python3 prog.py --help
usage: prog.py [-h] [--verbosity VERBOSITY]
options:
-h, --help show this help message and exit
--verbosity VERBOSITY
increase output verbosity
$ python3 prog.py --verbosity
usage: prog.py [-h] [--verbosity VERBOSITY]
prog.py: error: argument --verbosity: expected one argument
程序運(yùn)行情況如下:
這一程序被設(shè)計(jì)為當(dāng)指定
--verbosity
選項(xiàng)時(shí)顯示某些東西,否則不顯示。不添加這一選項(xiàng)時(shí)程序沒有提示任何錯(cuò)誤而退出,表明這一選項(xiàng)確實(shí)是可選的。注意,如果一個(gè)可選參數(shù)沒有被使用時(shí),相關(guān)變量被賦值為
None
,在此例中是args.verbosity
,這也就是為什么它在if
語(yǔ)句中被當(dāng)作邏輯假。幫助信息有點(diǎn)不同。
使用
--verbosity
選項(xiàng)時(shí),必須指定一個(gè)值,但可以是任何值。
上述例子接受任何整數(shù)值作為 --verbosity
的參數(shù),但對(duì)于我們的簡(jiǎn)單程序而言,只有兩個(gè)值有實(shí)際意義:True
或者 False
。讓我們據(jù)此修改代碼:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--verbose", help="increase output verbosity",
action="store_true")
args = parser.parse_args()
if args.verbose:
print("verbosity turned on")
和輸出:
$ python3 prog.py --verbose
verbosity turned on
$ python3 prog.py --verbose 1
usage: prog.py [-h] [--verbose]
prog.py: error: unrecognized arguments: 1
$ python3 prog.py --help
usage: prog.py [-h] [--verbose]
options:
-h, --help show this help message and exit
--verbose increase output verbosity
程序運(yùn)行情況如下:
現(xiàn)在,這一選項(xiàng)更多地是一個(gè)標(biāo)志,而非需要接受一個(gè)值的什么東西。我們甚至改變了選項(xiàng)的名字來(lái)符合這一思路。注意我們現(xiàn)在指定了一個(gè)新的關(guān)鍵詞
action
,并賦值為"store_true"
。這意味著,當(dāng)這一選項(xiàng)存在時(shí),為args.verbose
賦值為True
。沒有指定時(shí)則隱含地賦值為False
。當(dāng)你為其指定一個(gè)值時(shí),它會(huì)報(bào)錯(cuò),符合作為標(biāo)志的真正的精神。
留意不同的幫助文字。
短選項(xiàng)?
如果你熟悉命令行的用法,你會(huì)發(fā)現(xiàn)我還沒講到這一選項(xiàng)的短版本。這也很簡(jiǎn)單:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("-v", "--verbose", help="increase output verbosity",
action="store_true")
args = parser.parse_args()
if args.verbose:
print("verbosity turned on")
效果就像這樣:
$ python3 prog.py -v
verbosity turned on
$ python3 prog.py --help
usage: prog.py [-h] [-v]
options:
-h, --help show this help message and exit
-v, --verbose increase output verbosity
可以注意到,這一新的能力也反映在幫助文本里。
結(jié)合位置參數(shù)和可選參數(shù)?
我們的程序變得越來(lái)越復(fù)雜了:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbose", action="store_true",
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbose:
print(f"the square of {args.square} equals {answer}")
else:
print(answer)
接著是輸出:
$ python3 prog.py
usage: prog.py [-h] [-v] square
prog.py: error: the following arguments are required: square
$ python3 prog.py 4
16
$ python3 prog.py 4 --verbose
the square of 4 equals 16
$ python3 prog.py --verbose 4
the square of 4 equals 16
我們帶回了一個(gè)位置參數(shù),結(jié)果發(fā)生了報(bào)錯(cuò)。
注意順序無(wú)關(guān)緊要。
給我們的程序加上接受多個(gè)冗長(zhǎng)度的值,然后實(shí)際來(lái)用用:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", type=int,
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print(f"the square of {args.square} equals {answer}")
elif args.verbosity == 1:
print(f"{args.square}^2 == {answer}")
else:
print(answer)
和輸出:
$ python3 prog.py 4
16
$ python3 prog.py 4 -v
usage: prog.py [-h] [-v VERBOSITY] square
prog.py: error: argument -v/--verbosity: expected one argument
$ python3 prog.py 4 -v 1
4^2 == 16
$ python3 prog.py 4 -v 2
the square of 4 equals 16
$ python3 prog.py 4 -v 3
16
除了最后一個(gè),看上去都不錯(cuò)。最后一個(gè)暴露了我們的程序中有一個(gè) bug。我們可以通過限制 --verbosity
選項(xiàng)可以接受的值來(lái)修復(fù)它:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", type=int, choices=[0, 1, 2],
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print(f"the square of {args.square} equals {answer}")
elif args.verbosity == 1:
print(f"{args.square}^2 == {answer}")
else:
print(answer)
和輸出:
$ python3 prog.py 4 -v 3
usage: prog.py [-h] [-v {0,1,2}] square
prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, 1, 2)
$ python3 prog.py 4 -h
usage: prog.py [-h] [-v {0,1,2}] square
positional arguments:
square display a square of a given number
options:
-h, --help show this help message and exit
-v {0,1,2}, --verbosity {0,1,2}
increase output verbosity
注意這一改變同時(shí)反應(yīng)在錯(cuò)誤信息和幫助信息里。
現(xiàn)在,讓我們使用另一種的方式來(lái)改變?nèi)唛L(zhǎng)度。這種方式更常見,也和 CPython 的可執(zhí)行文件處理它自己的冗長(zhǎng)度參數(shù)的方式一致(參考 python --help
的輸出):
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display the square of a given number")
parser.add_argument("-v", "--verbosity", action="count",
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print(f"the square of {args.square} equals {answer}")
elif args.verbosity == 1:
print(f"{args.square}^2 == {answer}")
else:
print(answer)
我們引入了另一種動(dòng)作 "count",來(lái)統(tǒng)計(jì)特定選項(xiàng)出現(xiàn)的次數(shù)。
$ python3 prog.py 4
16
$ python3 prog.py 4 -v
4^2 == 16
$ python3 prog.py 4 -vv
the square of 4 equals 16
$ python3 prog.py 4 --verbosity --verbosity
the square of 4 equals 16
$ python3 prog.py 4 -v 1
usage: prog.py [-h] [-v] square
prog.py: error: unrecognized arguments: 1
$ python3 prog.py 4 -h
usage: prog.py [-h] [-v] square
positional arguments:
square display a square of a given number
options:
-h, --help show this help message and exit
-v, --verbosity increase output verbosity
$ python3 prog.py 4 -vvv
16
是的,它現(xiàn)在比前一版本更像是一個(gè)標(biāo)志(和
action="store_true"
相似)。這能解釋它為什么報(bào)錯(cuò)。它也表現(xiàn)得與 “store_true” 的行為相似。
這給出了一個(gè)關(guān)于
count
動(dòng)作的效果的演示。你之前很可能應(yīng)該已經(jīng)看過這種用法。如果你不添加
-v
標(biāo)志,這一標(biāo)志的值會(huì)是None
。如期望的那樣,添加該標(biāo)志的長(zhǎng)形態(tài)能夠獲得相同的輸出。
可惜的是,對(duì)于我們的腳本獲得的新能力,我們的幫助輸出并沒有提供很多信息,但我們總是可以通過改善文檔來(lái)修復(fù)這一問題(比如通過
help
關(guān)鍵字參數(shù))。最后一個(gè)輸出暴露了我們程序中的一個(gè) bug。
讓我們修復(fù)一下:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", action="count",
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
# bugfix: replace == with >=
if args.verbosity >= 2:
print(f"the square of {args.square} equals {answer}")
elif args.verbosity >= 1:
print(f"{args.square}^2 == {answer}")
else:
print(answer)
這是它給我們的輸出:
$ python3 prog.py 4 -vvv
the square of 4 equals 16
$ python3 prog.py 4 -vvvv
the square of 4 equals 16
$ python3 prog.py 4
Traceback (most recent call last):
File "prog.py", line 11, in <module>
if args.verbosity >= 2:
TypeError: '>=' not supported between instances of 'NoneType' and 'int'
第一組輸出很好,修復(fù)了之前的 bug。也就是說,我們希望任何 >= 2 的值盡可能詳盡。
第三組輸出并不理想。
讓我們修復(fù)那個(gè) bug:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", action="count", default=0,
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity >= 2:
print(f"the square of {args.square} equals {answer}")
elif args.verbosity >= 1:
print(f"{args.square}^2 == {answer}")
else:
print(answer)
我們剛剛引入了又一個(gè)新的關(guān)鍵字 default
。我們把它設(shè)置為 0
來(lái)讓它可以與其他整數(shù)值相互比較。記住,默認(rèn)情況下如果一個(gè)可選參數(shù)沒有被指定,它的值會(huì)是 None
,并且它不能和整數(shù)值相比較(所以產(chǎn)生了 TypeError
異常)。
然后:
$ python3 prog.py 4
16
憑借我們目前已學(xué)的東西你就可以做到許多事情,而我們還僅僅學(xué)了一些皮毛而已。 argparse
模塊是非常強(qiáng)大的,在結(jié)束篇教程之前我們將再探索更多一些內(nèi)容。
進(jìn)行一些小小的改進(jìn)?
如果我們想擴(kuò)展我們的簡(jiǎn)短程序來(lái)執(zhí)行其他冪次的運(yùn)算,而不僅是乘方:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
parser.add_argument("-v", "--verbosity", action="count", default=0)
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
print(f"{args.x} to the power {args.y} equals {answer}")
elif args.verbosity >= 1:
print(f"{args.x}^{args.y} == {answer}")
else:
print(answer)
輸出:
$ python3 prog.py
usage: prog.py [-h] [-v] x y
prog.py: error: the following arguments are required: x, y
$ python3 prog.py -h
usage: prog.py [-h] [-v] x y
positional arguments:
x the base
y the exponent
options:
-h, --help show this help message and exit
-v, --verbosity
$ python3 prog.py 4 2 -v
4^2 == 16
請(qǐng)注意到目前為止我們一直在使用詳細(xì)級(jí)別來(lái) 更改 所顯示的文本。 以下示例則使用詳細(xì)級(jí)別來(lái)顯示 更多的 文本:
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
parser.add_argument("-v", "--verbosity", action="count", default=0)
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
print(f"Running '{__file__}'")
if args.verbosity >= 1:
print(f"{args.x}^{args.y} == ", end="")
print(answer)
輸出:
$ python3 prog.py 4 2
16
$ python3 prog.py 4 2 -v
4^2 == 16
$ python3 prog.py 4 2 -vv
Running 'prog.py'
4^2 == 16
Specifying ambiguous arguments?
When there is ambiguity in deciding whether an argument is positional or for an
argument, --
can be used to tell parse_args()
that
everything after that is a positional argument:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-n', nargs='+')
>>> parser.add_argument('args', nargs='*')
>>> # ambiguous, so parse_args assumes it's an option
>>> parser.parse_args(['-f'])
usage: PROG [-h] [-n N [N ...]] [args ...]
PROG: error: unrecognized arguments: -f
>>> parser.parse_args(['--', '-f'])
Namespace(args=['-f'], n=None)
>>> # ambiguous, so the -n option greedily accepts arguments
>>> parser.parse_args(['-n', '1', '2', '3'])
Namespace(args=[], n=['1', '2', '3'])
>>> parser.parse_args(['-n', '1', '--', '2', '3'])
Namespace(args=['2', '3'], n=['1'])
矛盾的選項(xiàng)?
到目前為止,我們一直在使用 argparse.ArgumentParser
實(shí)例的兩個(gè)方法。 讓我們?cè)俳榻B第三個(gè)方法 add_mutually_exclusive_group()
。 它允許我們指定彼此相互沖突的選項(xiàng)。 讓我們?cè)俑某绦虻钠溆嗖糠忠员闶褂眯鹿δ芨幸饬x:我們將引入 --quiet
選項(xiàng),它將與 --verbose
正好相反:
import argparse
parser = argparse.ArgumentParser()
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true")
group.add_argument("-q", "--quiet", action="store_true")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x**args.y
if args.quiet:
print(answer)
elif args.verbose:
print(f"{args.x} to the power {args.y} equals {answer}")
else:
print(f"{args.x}^{args.y} == {answer}")
我們的程序現(xiàn)在變得更簡(jiǎn)潔了,我們出于演示需要略去了一些功能。 無(wú)論如何,輸出是這樣的:
$ python3 prog.py 4 2
4^2 == 16
$ python3 prog.py 4 2 -q
16
$ python3 prog.py 4 2 -v
4 to the power 2 equals 16
$ python3 prog.py 4 2 -vq
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
$ python3 prog.py 4 2 -v --quiet
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
這應(yīng)該很容易理解。 我添加了末尾的輸出這樣你就可以看到其所達(dá)到的靈活性,即混合使用長(zhǎng)和短兩種形式的選項(xiàng)。
在我們收尾之前,你也許希望告訴你的用戶這個(gè)程序的主要目標(biāo),以免他們還不清楚:
import argparse
parser = argparse.ArgumentParser(description="calculate X to the power of Y")
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true")
group.add_argument("-q", "--quiet", action="store_true")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x**args.y
if args.quiet:
print(answer)
elif args.verbose:
print("{} to the power {} equals {}".format(args.x, args.y, answer))
else:
print("{}^{} == {}".format(args.x, args.y, answer))
請(qǐng)注意用法文本中有細(xì)微的差異。 注意 [-v | -q]
,它的意思是說我們可以使用 -v
或 -q
,但不能同時(shí)使用兩者:
$ python3 prog.py --help
usage: prog.py [-h] [-v | -q] x y
calculate X to the power of Y
positional arguments:
x the base
y the exponent
options:
-h, --help show this help message and exit
-v, --verbose
-q, --quiet
后記?
除了這里顯示的內(nèi)容,argparse
模塊還提供了更多功能。 它的文檔相當(dāng)詳細(xì)和完整,包含大量示例。 完成這個(gè)教程之后,你應(yīng)該能毫不困難地閱讀該文檔。