Argparse 教程?

作者: Tshepang Lekhonkhobe

這篇教程旨在作為 argparse 的入門介紹，此模塊是 Python 標(biāo)準(zhǔn)庫中推薦的命令行解析模塊。

備注

還有另外兩個模塊可以完成同樣的任務(wù)，稱為 getopt (對應(yīng)于 C 語言中的 getopt() 函數(shù)) 和被棄用的 optparse。還要注意 argparse 是基于 optparse 的，因此用法與其非常相似。

概念?

讓我們利用 ls 命令來展示我們將要在這篇入門教程中探索的功能：

$ 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.
...

我們可以從這四個命令中學(xué)到幾個概念：

ls 是一個即使在運(yùn)行的時候沒有提供任何選項，也非常有用的命令。在默認(rèn)情況下他會輸出當(dāng)前文件夾包含的文件和文件夾。
如果我們想要使用比它默認(rèn)提供的更多功能，我們需要告訴該命令更多信息。在這個例子里，我們想要查看一個不同的目錄，pypy。我們所做的是指定所謂的位置參數(shù)。之所以這樣命名，是因為程序應(yīng)該如何處理該參數(shù)值，完全取決于它在命令行出現(xiàn)的位置。更能體現(xiàn)這個概念的命令如 cp，它最基本的用法是 cp SRC DEST。第一個位置參數(shù)指的是*你想要復(fù)制的*，第二個位置參數(shù)指的是*你想要復(fù)制到的位置*。
現(xiàn)在假設(shè)我們想要改變這個程序的行為。在我們的例子中，我們不僅僅只是輸出每個文件的文件名，還輸出了更多信息。在這個例子中，-l 被稱為可選參數(shù)。
這是一段幫助文檔的文字。它是非常有用的，因為當(dāng)你遇到一個你從未使用過的程序時，你可以通過閱讀它的幫助文檔來弄清楚它是如何運(yùn)行的。

基礎(chǔ)?

讓我們從一個簡單到（幾乎）什么也做不了的例子開始：

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)行情況如下：

在沒有任何選項的情況下運(yùn)行腳本不會在標(biāo)準(zhǔn)輸出顯示任何內(nèi)容。這沒有什么用處。
第二行代碼開始展現(xiàn)出 argparse 模塊的作用。我們幾乎什么也沒有做，但已經(jīng)得到一條很好的幫助信息。
--help 選項，也可縮寫為 -h，是唯一一個可以直接使用的選項（即不需要指定該選項的內(nèi)容）。指定任何內(nèi)容都會導(dǎo)致錯誤。即便如此，我們也能直接得到一條有用的用法信息。

位置參數(shù)介紹?

舉個例子：

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)行情況如下：

我們增加了 add_argument() 方法，該方法用于指定程序能夠接受哪些命令行選項。在這個例子中，我將選項命名為 echo，與其功能一致。
現(xiàn)在調(diào)用我們的程序必須要指定一個選項。
The parse_args() method actually returns some data from the options specified, in this case, echo.
這一變量是 argparse 免費(fèi)施放的某種 “魔法”（即是說，不需要指定哪個變量是存儲哪個值的）。你也可以注意到，這一名稱與傳遞給方法的字符串參數(shù)一致，都是 echo。

然而請注意，盡管顯示的幫助看起來清楚完整，但它可以比現(xiàn)在更有幫助。比如我們可以知道 echo 是一個位置參數(shù)，但我們除了靠猜或者看源代碼，沒法知道它是用來干什么的。所以，我們可以把它改造得更有用：

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)在，來做一些更有用的事情：

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)展不太順利。那是因為 argparse 會把我們傳遞給它的選項視作為字符串，除非我們告訴它別這樣。所以，讓我們來告訴 argparse 來把這一輸入視為整數(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'

做得不錯。當(dāng)這個程序在收到錯誤的無效的輸入時，它甚至能在執(zhí)行計算之前先退出，還能顯示很有幫助的錯誤信息。

可選參數(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è)計為當(dāng)指定 --verbosity 選項時顯示某些東西，否則不顯示。
不添加這一選項時程序沒有提示任何錯誤而退出，表明這一選項確實是可選的。注意，如果一個可選參數(shù)沒有被使用時，相關(guān)變量被賦值為 None，在此例中是 args.verbosity，這也就是為什么它在 if 語句中被當(dāng)作邏輯假。
幫助信息有點(diǎn)不同。
使用 --verbosity 選項時，必須指定一個值，但可以是任何值。

上述例子接受任何整數(shù)值作為 --verbosity 的參數(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)在，這一選項更多地是一個標(biāo)志，而非需要接受一個值的什么東西。我們甚至改變了選項的名字來符合這一思路。注意我們現(xiàn)在指定了一個新的關(guān)鍵詞 action，并賦值為 "store_true"。這意味著，當(dāng)這一選項存在時，為 args.verbose 賦值為 True。沒有指定時則隱含地賦值為 False。
當(dāng)你為其指定一個值時，它會報錯，符合作為標(biāo)志的真正的精神。
留意不同的幫助文字。

短選項?

如果你熟悉命令行的用法，你會發(fā)現(xià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ù)?

我們的程序變得越來越復(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

我們帶回了一個位置參數(shù)，結(jié)果發(fā)生了報錯。
注意順序無關(guān)緊要。

給我們的程序加上接受多個冗長度的值，然后實際來用用：

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

除了最后一個，看上去都不錯。最后一個暴露了我們的程序中有一個 bug。我們可以通過限制 --verbosity 選項可以接受的值來修復(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

注意這一改變同時反應(yīng)在錯誤信息和幫助信息里。

現(xiàn)在，讓我們使用另一種的方式來改變?nèi)唛L度。這種方式更常見，也和 CPython 的可執(zhí)行文件處理它自己的冗長度參數(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)

我們引入了另一種動作 "count"，來統(tǒ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)在比前一版本更像是一個標(biāo)志（和 action="store_true" 相似）。這能解釋它為什么報錯。
它也表現(xiàn)得與 “store_true” 的行為相似。
這給出了一個關(guān)于 count 動作的效果的演示。你之前很可能應(yīng)該已經(jīng)看過這種用法。
如果你不添加 -v 標(biāo)志，這一標(biāo)志的值會是 None。
如期望的那樣，添加該標(biāo)志的長形態(tài)能夠獲得相同的輸出。
可惜的是，對于我們的腳本獲得的新能力，我們的幫助輸出并沒有提供很多信息，但我們總是可以通過改善文檔來修復(fù)這一問題（比如通過 help 關(guān)鍵字參數(shù)）。
最后一個輸出暴露了我們程序中的一個 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ù)那個 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)

我們剛剛引入了又一個新的關(guān)鍵字 default。我們把它設(shè)置為 0 來讓它可以與其他整數(shù)值相互比較。記住，默認(rèn)情況下如果一個可選參數(shù)沒有被指定，它的值會是 None，并且它不能和整數(shù)值相比較（所以產(chǎn)生了 TypeError 異常）。

然后：

$ python3 prog.py 4
16

憑借我們目前已學(xué)的東西你就可以做到許多事情，而我們還僅僅學(xué)了一些皮毛而已。 argparse 模塊是非常強(qiáng)大的，在結(jié)束篇教程之前我們將再探索更多一些內(nèi)容。

進(jìn)行一些小小的改進(jìn)?

如果我們想擴(kuò)展我們的簡短程序來執(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

請注意到目前為止我們一直在使用詳細(xì)級別來更改所顯示的文本。以下示例則使用詳細(xì)級別來顯示 更多的 文本:

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'])

矛盾的選項?

到目前為止，我們一直在使用 argparse.ArgumentParser 實例的兩個方法。讓我們再介紹第三個方法 add_mutually_exclusive_group()。它允許我們指定彼此相互沖突的選項。讓我們再更改程序的其余部分以便使用新功能更有意義：我們將引入 --quiet 選項，它將與 --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)在變得更簡潔了，我們出于演示需要略去了一些功能。無論如何，輸出是這樣的:

$ 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á)到的靈活性，即混合使用長和短兩種形式的選項。

在我們收尾之前，你也許希望告訴你的用戶這個程序的主要目標(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))

請注意用法文本中有細(xì)微的差異。注意 [-v | -q]，它的意思是說我們可以使用 -v 或 -q，但不能同時使用兩者：

$ 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ì)和完整，包含大量示例。完成這個教程之后，你應(yīng)該能毫不困難地閱讀該文檔。

Argparse 教程?

概念?

基礎(chǔ)?

位置參數(shù)介紹?

可選參數(shù)介紹?

短選項?

結(jié)合位置參數(shù)和可選參數(shù)?

進(jìn)行一些小小的改進(jìn)?

Specifying ambiguous arguments?

矛盾的選項?

后記?

目錄

上一個主題

下一個主題

當(dāng)前頁面