`argparse` — 命令列選項、引數和子命令的解析器¶

3.2 版本新增。

註解

雖然 argparse 是實現基本命令列應用程式的預設推薦標準庫模組，但對於其命令列應用程式的行為有更嚴格要求的作者可能會發現它沒有提供必要的控制級別。當 argparse 不支援應用程式所需的行為時（例如完全停用對穿插選項和位置引數的支援，或接受以 - 開頭的選項引數值，即使它們對應於另一個定義的選項），請參閱選擇引數解析庫以考慮替代方案。

argparse 模組使編寫使用者友好的命令列介面變得容易。程式定義它需要哪些引數，argparse 將計算出如何從 sys.argv 中解析出這些引數。argparse 模組還會自動生成幫助和用法訊息。當用戶向程式提供無效引數時，該模組還會發出錯誤。

argparse 模組對命令列介面的支援是圍繞 argparse.ArgumentParser 的例項構建的。它是引數規範的容器，並具有適用於整個解析器的選項

parser = argparse.ArgumentParser(
                    prog='ProgramName',
                    description='What the program does',
                    epilog='Text at the bottom of help')

ArgumentParser.add_argument() 方法將各個引數規範附加到解析器。它支援位置引數、接受值的選項以及開/關標誌

parser.add_argument('filename')           # positional argument
parser.add_argument('-c', '--count')      # option that takes a value
parser.add_argument('-v', '--verbose',
                    action='store_true')  # on/off flag

ArgumentParser.parse_args() 方法執行解析器，並將提取的資料放入 argparse.Namespace 物件中

args = parser.parse_args()
print(args.filename, args.count, args.verbose)

註解

如果您正在尋找有關如何將 optparse 程式碼升級到 argparse 的指南，請參閱升級 Optparse 程式碼。

ArgumentParser 物件¶

class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)¶

建立一個新的 ArgumentParser 物件。所有引數都應作為關鍵字引數傳遞。每個引數在下面都有其自己的更詳細的描述，但簡而言之，它們是

prog - 程式的名稱（預設值：os.path.basename(sys.argv[0])）
usage - 描述程式用法的字串（預設值：從新增到解析器的引數生成）
description - 顯示在引數幫助之前的文字（預設情況下，沒有文字）
epilog - 顯示在引數幫助之後的文字（預設情況下，沒有文字）
parents - ArgumentParser 物件的列表，這些物件的引數也應包括在內
formatter_class - 用於自定義幫助輸出的類
prefix_chars - 字首可選引數的字元集（預設值：‘-‘）
fromfile_prefix_chars - 字首檔案的字元集，應從中讀取其他引數（預設值：None）
argument_default - 引數的全域性預設值（預設值：None）
conflict_handler - 用於解決衝突選項的策略（通常不必要）
add_help - 向解析器新增 -h/--help 選項（預設值：True）
allow_abbrev - 如果縮寫是明確的，則允許縮寫長選項。（預設值：True）
exit_on_error - 確定當發生錯誤時，ArgumentParser 是否退出並顯示錯誤資訊。（預設值：True）

在 3.5 版本中更改: 添加了 allow_abbrev 引數。

在 3.8 版本中更改: 在以前的版本中，allow_abbrev 還停用短標誌的分組，例如 -vv 表示 -v -v。

在 3.9 版本中更改: 添加了 exit_on_error 引數。

以下部分描述瞭如何使用這些引數中的每一個。

prog¶

預設情況下，ArgumentParser 根據 Python 直譯器的執行方式計算要在幫助訊息中顯示的程式名稱

如果將檔案作為引數傳遞，則為 sys.argv[0] 的 base name。
如果將目錄或 zipfile 作為引數傳遞，則為 Python 直譯器名稱後跟 sys.argv[0]。
如果使用了 -m 選項，則為 Python 直譯器名稱後跟 -m 後跟模組或包名稱。

此預設值幾乎總是理想的，因為它會使幫助訊息與在命令列上呼叫程式時使用的字串匹配。但是，要更改此預設行為，可以使用 prog= 引數為 ArgumentParser 提供另一個值。

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]

options:
 -h, --help  show this help message and exit

請注意，程式名稱，無論是從 sys.argv[0] 確定還是從 prog= 引數確定，都可以使用 %(prog)s 格式說明符在幫助訊息中使用。

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo of the myprogram program

用法¶

預設情況下，ArgumentParser 從其包含的引數計算用法訊息。可以使用 usage= 關鍵字引數覆蓋預設訊息。

>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]

positional arguments:
 bar          bar help

options:
 -h, --help   show this help message and exit
 --foo [FOO]  foo help

%(prog)s 格式說明符可用於在用法訊息中填充程式名稱。

描述¶

大多數對 ArgumentParser 建構函式的呼叫都將使用 description= 關鍵字引數。此引數簡要描述程式的作用以及它的工作原理。在幫助訊息中，描述顯示在命令列用法字串和各種引數的幫助訊息之間。

預設情況下，描述將自動換行，使其適合給定的空間。要更改此行為，請參閱 formatter_class 引數。

後記¶

某些程式喜歡在引數描述之後顯示程式的其他描述。可以使用 epilog= 引數為 ArgumentParser 指定此類文字。

>>> parser = argparse.ArgumentParser(
...     description='A foo that bars',
...     epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

options:
 -h, --help  show this help message and exit

And that's how you'd foo a bar

與 description 引數一樣，預設情況下，epilog= 文字也會自動換行，但是可以透過 formatter_class 引數為 ArgumentParser 調整此行為。

父解析器¶

有時，多個解析器共享一組常見的引數。與其重複定義這些引數，不如使用包含所有共享引數的單個解析器，並將其傳遞給 ArgumentParser 的 parents= 引數。 parents= 引數接受一個 ArgumentParser 物件列表，從它們中收集所有位置和可選操作，並將這些操作新增到正在構造的 ArgumentParser 物件中。

>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)

>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)

>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)

請注意，大多數父解析器將指定 add_help=False。否則，ArgumentParser 將看到兩個 -h/--help 選項（一個在父解析器中，一個在子解析器中），並引發錯誤。

註解

您必須先完全初始化解析器，然後才能透過 parents= 傳遞它們。如果在子解析器之後更改父解析器，則這些更改不會反映在子解析器中。

格式化類¶

ArgumentParser 物件允許透過指定備用格式化類來自定義幫助格式。目前，有四個這樣的類：

class argparse.RawDescriptionHelpFormatter¶
class argparse.RawTextHelpFormatter¶
class argparse.ArgumentDefaultsHelpFormatter¶
class argparse.MetavarTypeHelpFormatter¶

RawDescriptionHelpFormatter 和 RawTextHelpFormatter 可以更好地控制文字描述的顯示方式。預設情況下，ArgumentParser 物件會在命令列幫助訊息中自動換行 description 和 epilog 文字。

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     description='''this description
...         was indented weird
...             but that is okay''',
...     epilog='''
...             likewise for this epilog whose whitespace will
...         be cleaned up and whose words will be wrapped
...         across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]

this description was indented weird but that is okay

options:
 -h, --help  show this help message and exit

likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines

將 RawDescriptionHelpFormatter 作為 formatter_class= 傳遞表示 description 和 epilog 已經正確格式化，不應自動換行。

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description=textwrap.dedent('''\
...         Please do not mess up this text!
...         --------------------------------
...             I have indented it
...             exactly the way
...             I want it
...         '''))
>>> parser.print_help()
usage: PROG [-h]

Please do not mess up this text!
--------------------------------
   I have indented it
   exactly the way
   I want it

options:
 -h, --help  show this help message and exit

RawTextHelpFormatter 保留所有幫助文字的空白符，包括引數描述。但是，多個換行符會被替換為一個。如果您希望保留多個空行，請在換行符之間新增空格。

ArgumentDefaultsHelpFormatter 會自動將有關預設值的資訊新增到每個引數的幫助訊息中。

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar ...]

positional arguments:
 bar         BAR! (default: [1, 2, 3])

options:
 -h, --help  show this help message and exit
 --foo FOO   FOO! (default: 42)

MetavarTypeHelpFormatter 使用每個引數的 type 引數的名稱作為其值的顯示名稱（而不是像常規格式化程式那樣使用 dest）。

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.MetavarTypeHelpFormatter)
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', type=float)
>>> parser.print_help()
usage: PROG [-h] [--foo int] float

positional arguments:
  float

options:
  -h, --help  show this help message and exit
  --foo int

字首字元¶

大多數命令列選項將使用 - 作為字首，例如 -f/--foo。需要支援不同或額外的字元字首（例如，+f 或 /foo 等選項）的解析器可以使用 ArgumentParser 建構函式的 prefix_chars= 引數來指定它們。

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')

prefix_chars= 引數的預設值為 '-'。提供一個不包含 - 的字元集會導致不允許使用 -f/--foo 選項。

來自檔案的字首字元¶

有時，在處理特別長的引數列表時，將引數列表儲存在檔案中而不是在命令列中鍵入出來可能更有意義。如果將 fromfile_prefix_chars= 引數傳遞給 ArgumentParser 建構函式，則以任何指定字元開頭的引數將被視為檔案，並將被它們包含的引數替換。例如：

>>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:
...     fp.write('-f\nbar')
...
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')

預設情況下，從檔案中讀取的引數必須每行一個（但另請參閱 convert_arg_line_to_args()），並且被視為與命令列上原始檔案引用引數位於相同的位置。因此，在上面的示例中，表示式 ['-f', 'foo', '@args.txt'] 被認為等效於表示式 ['-f', 'foo', '-f', 'bar']。

ArgumentParser 使用檔案系統編碼和錯誤處理程式讀取包含引數的檔案。

fromfile_prefix_chars= 引數的預設值為 None，這意味著引數永遠不會被視為檔案引用。

在 3.12 版本中更改：ArgumentParser 更改了編碼和錯誤，以從預設值（例如，locale.getpreferredencoding(False) 和 "strict"）讀取引數檔案到檔案系統編碼和錯誤處理程式。引數檔案在 Windows 上應使用 UTF-8 編碼，而不是 ANSI 內碼表。

argument_default¶

通常，引數預設值可以透過將預設值傳遞給 add_argument() 或透過呼叫 set_defaults() 方法並使用特定名稱-值對來指定。然而，有時為引數指定單個解析器範圍的預設值可能很有用。這可以透過將 argument_default= 關鍵字引數傳遞給 ArgumentParser 來實現。例如，要在 parse_args() 呼叫中全域性禁止屬性建立，我們可以提供 argument_default=SUPPRESS

>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()

allow_abbrev¶

通常，當你將引數列表傳遞給 parse_args() 方法時，它會識別長選項的縮寫。

可以透過將 allow_abbrev 設定為 False 來停用此功能

>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
>>> parser.add_argument('--foobar', action='store_true')
>>> parser.add_argument('--foonley', action='store_false')
>>> parser.parse_args(['--foon'])
usage: PROG [-h] [--foobar] [--foonley]
PROG: error: unrecognized arguments: --foon

在 3.5 版本中新增。

conflict_handler¶

ArgumentParser 物件不允許兩個動作具有相同的選項字串。預設情況下，如果嘗試使用已在使用的選項字串建立引數，ArgumentParser 物件會引發異常

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
 ..
ArgumentError: argument --foo: conflicting option string(s): --foo

有時（例如，在使用父類時），簡單地使用相同的選項字串覆蓋任何較舊的引數可能很有用。為了獲得此行為，可以將值 'resolve' 提供給 ArgumentParser 的 conflict_handler= 引數

>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]

options:
 -h, --help  show this help message and exit
 -f FOO      old foo help
 --foo FOO   new foo help

請注意，只有當 ArgumentParser 物件的所有選項字串都被覆蓋時，它才會刪除一個動作。因此，在上面的示例中，舊的 -f/--foo 動作被保留為 -f 動作，因為只有 --foo 選項字串被覆蓋。

add_help¶

預設情況下，ArgumentParser 物件會新增一個選項，該選項僅顯示解析器的幫助訊息。如果在命令列中提供 -h 或 --help，則會列印 ArgumentParser 幫助。

有時，停用此幫助選項的新增可能很有用。可以透過將 False 作為 ArgumentParser 的 add_help= 引數傳遞來實現。

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]

options:
 --foo FOO  foo help

幫助選項通常為 -h/--help。如果指定了 prefix_chars= 並且不包含 -，則 -h 和 --help 不是有效的選項。在這種情況下，prefix_chars 中的第一個字元用於為幫助選項新增字首

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]

options:
  +h, ++help  show this help message and exit

exit_on_error¶

通常，當你將無效的引數列表傳遞給 parse_args() 方法時，它會將訊息列印到 sys.stderr 並以狀態碼 2 退出。

如果使用者希望手動捕獲錯誤，則可以透過將 exit_on_error 設定為 False 來啟用此功能

>>> parser = argparse.ArgumentParser(exit_on_error=False)
>>> parser.add_argument('--integers', type=int)
_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
>>> try:
...     parser.parse_args('--integers a'.split())
... except argparse.ArgumentError:
...     print('Catching an argumentError')
...
Catching an argumentError

在 3.9 版本中新增。

add_argument() 方法¶

ArgumentParser.add_argument(name or flags..., *[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest][, deprecated])¶

定義如何解析單個命令列引數。每個引數都有其自己的更詳細的描述，但簡而言之，它們是

名稱或標誌 - 名稱或選項字串列表，例如 'foo' 或 '-f', '--foo'。
action - 當在命令列中遇到此引數時要執行的基本操作型別。
nargs - 應該使用的命令列引數的數量。
const - 某些 action 和 nargs 選擇所需的常量值。
default - 如果命令列中沒有該引數，並且如果名稱空間物件中沒有該引數，則生成的值。
type - 應該將命令列引數轉換為的型別。
choices - 引數的允許值序列。
required - 是否可以省略命令列選項（僅限可選）。
help - 對引數作用的簡要描述。
metavar - 用法訊息中引數的名稱。
dest - 要新增到由 parse_args() 返回的物件中的屬性的名稱。
deprecated - 是否不建議使用該引數。

以下部分描述瞭如何使用這些引數中的每一個。

名稱或標誌¶

add_argument() 方法必須知道期望的是可選引數（如 -f 或 --foo），還是位置引數（如檔名列表）。因此，傳遞給 add_argument() 的第一個引數必須是一系列標誌或一個簡單的引數名稱。

例如，可以建立如下的可選引數

>>> parser.add_argument('-f', '--foo')

而位置引數可以像這樣建立

>>> parser.add_argument('bar')

當呼叫 parse_args() 時，可選引數將由 - 字首標識，其餘引數將被假定為位置引數

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar

action¶

ArgumentParser 物件將命令列引數與動作關聯。這些動作幾乎可以對與之關聯的命令列引數執行任何操作，儘管大多數動作只是將屬性新增到 parse_args() 返回的物件。 action 關鍵字引數指定應如何處理命令列引數。提供的動作有

'store' - 這只是儲存引數的值。這是預設操作。
'store_const' - 這會儲存由 const 關鍵字引數指定的值；請注意，const 關鍵字引數預設為 None。 'store_const' 動作最常用於指定某種標誌的可選引數。例如
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)
```

'store_true' 和 'store_false' - 它們是 'store_const' 的特殊情況，分別用於儲存值 True 和 False。此外，它們還分別建立預設值 False 和 True。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
>>> parser.add_argument('--baz', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
Namespace(foo=True, bar=False, baz=True)

'append' - 此操作儲存一個列表，並將每個引數值附加到列表中。它對於允許多次指定一個選項非常有用。如果預設值非空，則預設元素將出現在選項的解析值中，命令列中的任何值都將附加在這些預設值之後。用法示例
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append')
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['1', '2'])
```

'append_const' - 此操作儲存一個列表，並將 const 關鍵字引數指定的值附加到列表中；請注意，const 關鍵字引數的預設值為 None。'append_const' 操作通常在需要將多個引數的常量儲存到同一列表時很有用。例如

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--str', dest='types', action='append_const', const=str)
>>> parser.add_argument('--int', dest='types', action='append_const', const=int)
>>> parser.parse_args('--str --int'.split())
Namespace(types=[<class 'str'>, <class 'int'>])

'extend' - 此操作儲存一個列表，並將多值引數列表中的每個項附加到該列表。 'extend' 操作通常與 nargs 關鍵字引數值 '+' 或 '*' 一起使用。請注意，當 nargs 為 None（預設值）或 '?' 時，引數字串的每個字元都將附加到列表中。用法示例
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
>>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
Namespace(foo=['f1', 'f2', 'f3', 'f4'])
```
在 3.8 版本中新增。
'count' - 此操作計算關鍵字引數出現的次數。例如，這對於增加詳細程度級別很有用。
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count', default=0)
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
```
請注意，除非明確設定為 0，否則預設值將為 None。
'help' - 此操作列印當前解析器中所有選項的完整幫助訊息，然後退出。預設情況下，幫助操作會自動新增到解析器中。有關如何建立輸出的詳細資訊，請參閱 ArgumentParser。

'version' - 此操作期望在 add_argument() 呼叫中使用 version= 關鍵字引數，並在呼叫時列印版本資訊並退出。

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
>>> parser.parse_args(['--version'])
PROG 2.0

只有使用命令列引數的操作（例如 'store'、'append' 或 'extend'）才能與位置引數一起使用。

class argparse.BooleanOptionalAction¶

您還可以透過傳遞一個 Action 子類或其他實現相同介面的物件來指定任意操作。BooleanOptionalAction 在 argparse 中可用，並添加了對布林操作（如 --foo 和 --no-foo）的支援。

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)

在 3.9 版本中新增。

建立自定義操作的推薦方法是擴充套件 Action，覆蓋 __call__() 方法，並可以選擇覆蓋 __init__() 和 format_usage() 方法。您還可以使用 register() 方法註冊自定義操作，並透過其註冊名稱引用它們。

自定義操作的示例

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super().__init__(option_strings, dest, **kwargs)
...     def __call__(self, parser, namespace, values, option_string=None):
...         print('%r %r %r' % (namespace, values, option_string))
...         setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')

有關更多詳細資訊，請參閱 Action。

nargs¶

ArgumentParser 物件通常將單個命令列引數與要執行的單個操作相關聯。nargs 關鍵字引數將不同數量的命令列引數與單個操作相關聯。另請參閱指定不明確的引數。支援的值為

N（整數）。命令列中的 N 個引數將收集到一個列表中。例如

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2)
>>> parser.add_argument('bar', nargs=1)
>>> parser.parse_args('c --foo a b'.split())
Namespace(bar=['c'], foo=['a', 'b'])

請注意，nargs=1 會生成一個包含一個項的列表。這與預設值不同，預設值是項本身產生。

'?'。如果可能，將從命令列消耗一個引數，並將其作為單個項生成。如果沒有命令列引數，則將生成 default 中的值。請注意，對於可選引數，還有一種特殊情況 - 選項字串存在，但後面沒有跟命令列引數。在這種情況下，將生成 const 中的值。以下是一些示例來說明這一點

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> parser.add_argument('bar', nargs='?', default='d')
>>> parser.parse_args(['XX', '--foo', 'YY'])
Namespace(bar='XX', foo='YY')
>>> parser.parse_args(['XX', '--foo'])
Namespace(bar='XX', foo='c')
>>> parser.parse_args([])
Namespace(bar='d', foo='d')

nargs='?' 的更常見用法之一是允許可選的輸入和輸出檔案

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
...                     default=sys.stdin)
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
...                     default=sys.stdout)
>>> parser.parse_args(['input.txt', 'output.txt'])
Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
>>> parser.parse_args([])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)

'*'。所有出現的命令列引數都收集到一個列表中。請注意，通常對於具有 nargs='*' 的位置引數來說，擁有多個是沒有意義的，但是擁有多個具有 nargs='*' 的可選引數是可能的。例如

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='*')
>>> parser.add_argument('--bar', nargs='*')
>>> parser.add_argument('baz', nargs='*')
>>> parser.parse_args('a b --foo x y --bar 1 2'.split())
Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

'+'。與 '*' 一樣，所有出現的命令列引數都收集到一個列表中。此外，如果沒有至少一個命令列引數，則會生成錯誤訊息。例如

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
>>> parser.parse_args(['a', 'b'])
Namespace(foo=['a', 'b'])
>>> parser.parse_args([])
usage: PROG [-h] foo [foo ...]
PROG: error: the following arguments are required: foo

如果未提供 nargs 關鍵字引數，則消耗的引數數量由 action 確定。通常，這意味著將消耗單個命令列引數，並生成單個項（而不是列表）。不使用命令列引數的操作（例如 'store_const'）設定 nargs=0。

const¶

add_argument() 的 const 引數用於儲存未從命令列讀取但在各種 ArgumentParser 操作中所需的常量值。它最常見的兩個用途是

當使用 action='store_const' 或 action='append_const' 呼叫 add_argument() 時。這些操作將 const 值新增到由 parse_args() 返回的物件的屬性之一。有關示例，請參閱 action 說明。如果未向 add_argument() 提供 const，則它將接收 None 的預設值。
當使用選項字串（如 -f 或 --foo）呼叫 add_argument() 並且 nargs='?' 時，將建立一個可選引數，該引數可以後跟零個或一個命令列引數。在解析命令列時，如果遇到選項字串但後面沒有跟隨命令列引數，則將假定 const 的值為 None。有關示例，請參閱 nargs 的描述。

在 3.11 版本中更改: 預設情況下 const=None，包括當 action='append_const' 或 action='store_const' 時。

default¶

所有可選引數和某些位置引數都可以在命令列中省略。add_argument() 的 default 關鍵字引數（其值預設為 None）指定如果命令列引數不存在時應使用的值。對於可選引數，當命令列中不存在選項字串時，將使用 default 值。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)

如果目標名稱空間已設定了屬性，則 action *default* 不會覆蓋它。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)

如果 default 值是一個字串，則解析器會像解析命令列引數一樣解析該值。特別是，解析器會在設定 Namespace 返回值上的屬性之前，應用任何 type 轉換引數（如果已提供）。否則，解析器將按原樣使用該值。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)

對於 nargs 等於 ? 或 * 的位置引數，當不存在命令列引數時，將使用 default 值。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)

對於 required 引數，將忽略 default 值。例如，這適用於 nargs 值不是 ? 或 * 的位置引數，或標記為 required=True 的可選引數。

提供 default=argparse.SUPPRESS 會導致在命令列引數不存在時，不新增任何屬性。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')

type¶

預設情況下，解析器將命令列引數讀取為簡單的字串。但是，命令列字串通常應解釋為另一種型別，例如 float 或 int。add_argument() 的 type 關鍵字允許執行任何必要的型別檢查和型別轉換。

如果 type 關鍵字與 default 關鍵字一起使用，則僅當 default 是字串時才應用型別轉換器。

type 的引數可以是接受單個字串的可呼叫物件，也可以是已註冊型別的名稱（請參閱 register()）。如果函式引發 ArgumentTypeError、TypeError 或 ValueError，則會捕獲異常並顯示格式良好的錯誤訊息。不處理其他異常型別。

常見的內建型別和函式可以用作型別轉換器。

import argparse
import pathlib

parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)

使用者定義的函式也可以使用。

>>> def hyphenated(string):
...     return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')

不建議將 bool() 函式用作型別轉換器。它所做的只是將空字串轉換為 False，將非空字串轉換為 True。這通常不是想要的。

通常，type 關鍵字是一種便利功能，僅應用於簡單的轉換，這些轉換隻能引發三個支援的異常之一。任何具有更有趣的錯誤處理或資源管理的功能都應在解析引數後在下游進行。

例如，JSON 或 YAML 轉換具有複雜的錯誤情況，需要比 type 關鍵字提供的更好的報告。JSONDecodeError 的格式將不佳，並且根本不會處理 FileNotFoundError 異常。

即使 FileType 在與 type 關鍵字一起使用時也有其侷限性。如果一個引數使用 FileType，然後後續引數失敗，則會報告錯誤，但不會自動關閉該檔案。在這種情況下，最好等到解析器執行後，然後使用 with 語句來管理檔案。

對於僅針對固定值集進行檢查的型別檢查器，請考慮改用 choices 關鍵字。

choices¶

某些命令列引數應從一組受限的值中選擇。可以透過將序列物件作為 add_argument() 的 *choices* 關鍵字引數傳遞來處理這些引數。解析命令列時，將檢查引數值，如果引數不是可接受的值之一，則會顯示錯誤訊息。

>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
>>> parser.parse_args(['rock'])
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')

請注意，在執行任何 type 轉換之後，會檢查是否包含在 *choices* 序列中，因此 *choices* 序列中的物件的型別應與指定的 type 匹配。

任何序列都可以作為 *choices* 值傳遞，因此支援 list 物件、tuple 物件和自定義序列。

不建議使用 enum.Enum，因為它很難控制其在用法、幫助和錯誤訊息中的外觀。

格式化的 choices 會覆蓋通常從 *dest* 派生的預設 *metavar*。這通常是你想要的，因為使用者永遠不會看到 *dest* 引數。如果此顯示不理想（可能因為有很多選擇），只需指定一個顯式的 metavar。

required¶

通常，argparse 模組假定諸如 -f 和 --bar 之類的標誌表示 *可選* 引數，這些引數始終可以在命令列中省略。要使選項為 *必需* 的，可以為 add_argument() 的 required= 關鍵字引數指定 True。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: [-h] --foo FOO
: error: the following arguments are required: --foo

如示例所示，如果選項標記為 required，則如果命令列中不存在該選項，parse_args() 將報告錯誤。

註解

必需選項通常被認為是不好的形式，因為使用者希望*選項*是*可選的*，因此應儘可能避免使用。

help¶

help 值是一個字串，其中包含引數的簡短描述。當用戶請求幫助時（通常透過在命令列中使用 -h 或 --help），這些 help 描述將與每個引數一起顯示。

help 字串可以包含各種格式說明符，以避免重複諸如程式名稱或引數 default 之類的內容。可用的說明符包括程式名稱 %(prog)s 和 add_argument() 的大多數關鍵字引數，例如 %(default)s、%(type)s 等。

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
...                     help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]

positional arguments:
 bar     the bar to frobble (default: 42)

options:
 -h, --help  show this help message and exit

由於幫助字串支援 % 格式，如果你希望在幫助字串中出現文字 %，則必須將其轉義為 %%。

argparse 支援透過將 help 值設定為 argparse.SUPPRESS 來靜默某些選項的幫助條目。

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]

options:
  -h, --help  show this help message and exit

metavar¶

當 ArgumentParser 生成幫助訊息時，它需要某種方式來引用每個預期的引數。預設情況下，ArgumentParser 物件使用 dest 值作為每個物件的“名稱”。預設情況下，對於位置引數操作，直接使用 dest 值；對於可選引數操作，將 dest 值轉換為大寫。因此，dest='bar' 的單個位置引數將被稱為 bar。一個後跟單個命令列引數的單個可選引數 --foo 將被稱為 FOO。一個例子：

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo FOO] bar

positional arguments:
 bar

options:
 -h, --help  show this help message and exit
 --foo FOO

可以使用 metavar 指定一個備用名稱。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo YYY] XXX

positional arguments:
 XXX

options:
 -h, --help  show this help message and exit
 --foo YYY

請注意，metavar 僅更改顯示的名稱 - parse_args() 物件上屬性的名稱仍然由 dest 值確定。

nargs 的不同值可能會導致多次使用 metavar。向 metavar 提供一個元組，可以為每個引數指定不同的顯示。

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2)
>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]

options:
 -h, --help     show this help message and exit
 -x X X
 --foo bar baz

dest¶

大多數 ArgumentParser 操作都會將某個值新增為 parse_args() 返回的物件的屬性。此屬性的名稱由 add_argument() 的 dest 關鍵字引數確定。對於位置引數操作，dest 通常作為第一個引數提供給 add_argument()。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')

對於可選引數操作，dest 的值通常從選項字串推斷得出。ArgumentParser 透過獲取第一個長選項字串並刪除初始的 -- 字串來生成 dest 的值。如果未提供長選項字串，則 dest 將從第一個短選項字串中派生，方法是刪除初始的 - 字元。任何內部的 - 字元都將轉換為 _ 字元，以確保該字串是有效的屬性名稱。下面的示例說明了這種行為：

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -x 2'.split())
Namespace(foo_bar='1', x='2')
>>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2')

dest 允許提供自定義屬性名稱。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')

deprecated¶

在專案的生命週期中，可能需要從命令列刪除某些引數。在刪除它們之前，您應該通知使用者這些引數已棄用，並且將被刪除。預設值為 False 的 add_argument() 的 deprecated 關鍵字引數指定該引數是否已棄用，並將在未來刪除。對於引數，如果 deprecated 為 True，則當使用該引數時，將向 sys.stderr 列印警告。

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='snake.py')
>>> parser.add_argument('--legs', default=0, type=int, deprecated=True)
>>> parser.parse_args([])
Namespace(legs=0)
>>> parser.parse_args(['--legs', '4'])  
snake.py: warning: option '--legs' is deprecated
Namespace(legs=4)

在 3.13 版本中新增。

Action 類¶

Action 類實現 Action API，一個可呼叫物件，它返回一個可呼叫物件，該物件處理來自命令列的引數。任何遵循此 API 的物件都可以作為 action 引數傳遞給 add_argument()。

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)¶

Action 物件由 ArgumentParser 使用，以表示從命令列解析一個或多個字串的單個引數所需的資訊。Action 類必須接受兩個位置引數，以及傳遞給 ArgumentParser.add_argument() 的任何關鍵字引數，除了 action 本身。

Action 的例項（或傳遞給 action 引數的任何可呼叫物件的返回值）應具有已定義的屬性 dest、option_strings、default、type、required、help 等。確保定義這些屬性的最簡單方法是呼叫 Action.__init__()。

__call__(parser, namespace, values, option_string=None)¶

Action 例項應該是可呼叫的，因此子類必須重寫 __call__() 方法，該方法應接受四個引數。

parser - 包含此操作的 ArgumentParser 物件。
namespace - 將由 parse_args() 返回的 Namespace 物件。大多數操作使用 setattr() 將屬性新增到此物件。
values - 關聯的命令列引數，並應用了任何型別轉換。型別轉換使用 type 關鍵字引數指定給 add_argument()。
option_string - 用於呼叫此操作的選項字串。option_string 引數是可選的，如果該操作與位置引數關聯，則該引數將不存在。

__call__() 方法可以執行任意操作，但通常會根據 dest 和 values 設定 namespace 上的屬性。

format_usage()¶: Action 子類可以定義一個 format_usage() 方法，該方法不接受任何引數並返回一個字串，該字串將在列印程式用法時使用。如果未提供此類方法，則將使用合理的預設值。

parse_args() 方法¶

ArgumentParser.parse_args(args=None, namespace=None)¶

將引數字串轉換為物件並將其作為名稱空間的屬性分配。返回填充的名稱空間。

先前對 add_argument() 的呼叫確定了建立哪些物件以及如何分配它們。有關詳細資訊，請參閱 add_argument() 的文件。

args - 要解析的字串列表。預設值取自 sys.argv。
namespace - 用於獲取屬性的物件。預設值是一個新的空 Namespace 物件。

選項值語法¶

parse_args() 方法支援幾種指定選項值的方法（如果它接受一個值）。在最簡單的情況下，選項及其值作為兩個單獨的引數傳遞

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)

對於長選項（名稱長度超過一個字元的選項），選項和值也可以作為單個命令列引數傳遞，使用 = 分隔它們

>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)

對於短選項（僅一個字元長的選項），選項及其值可以連線在一起

>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')

可以將多個短選項連線在一起，僅使用單個 - 字首，只要最後一個選項（或沒有選項）需要值

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')

無效引數¶

在解析命令列時，parse_args() 會檢查各種錯誤，包括歧義選項、無效型別、無效選項、錯誤的位置引數數量等。當遇到此類錯誤時，它會退出並列印錯誤以及用法訊息

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')

>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger

包含 `-` 的引數¶

parse_args() 方法會在使用者明顯犯錯時嘗試給出錯誤，但某些情況本質上是模稜兩可的。例如，命令列引數 -1 可能是嘗試指定選項或嘗試提供位置引數。parse_args() 方法在此處很謹慎：位置引數只有在看起來像負數並且解析器中沒有看起來像負數的選項時才能以 - 開頭

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')

>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # no negative number options, so -1 and -5 are positional arguments
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-1', dest='one')
>>> parser.add_argument('foo', nargs='?')

>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

>>> # negative number options present, so both -1s are options
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument

如果你的位置引數必須以 - 開頭，並且看起來不像負數，你可以插入偽引數 '--'，這會告訴 parse_args()，在此之後的所有內容都是位置引數

>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)

有關更多詳細資訊，另請參閱關於歧義引數的 argparse 指南。

引數縮寫（字首匹配）¶

parse_args() 方法預設情況下允許將長選項縮寫為字首，如果該縮寫是明確的（字首與唯一選項匹配）

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon

對於可能產生多個選項的引數，會產生錯誤。可以透過將 allow_abbrev 設定為 False 來停用此功能。

超出 `sys.argv`¶

有時，可能需要讓 ArgumentParser 解析除 sys.argv 之外的引數。這可以透過將字串列表傳遞給 parse_args() 來完成。這對於在互動式提示符下進行測試很有用

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
...     'integers', metavar='int', type=int, choices=range(10),
...     nargs='+', help='an integer in the range 0..9')
>>> parser.add_argument(
...     '--sum', dest='accumulate', action='store_const', const=sum,
...     default=max, help='sum the integers (default: find the max)')
>>> parser.parse_args(['1', '2', '3', '4'])
Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])

名稱空間物件¶

class argparse.Namespace¶

parse_args() 預設使用的簡單類，用於建立一個儲存屬性並返回它的物件。

此類刻意簡單，只是一個帶有可讀字串表示形式的 object 子類。如果你希望具有屬性的類似字典的檢視，可以使用標準 Python 慣用法 vars()

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}

將屬性分配給已存在的物件，而不是新的 Namespace 物件也可能很有用。可以透過指定 namespace= 關鍵字引數來實現。

>>> class C:
...     pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'

其他實用程式¶

子命令¶

ArgumentParser.add_subparsers(*[, title][, description][, prog][, parser_class][, action][, dest][, required][, help][, metavar])¶

許多程式將其功能劃分為多個子命令，例如，svn 程式可以呼叫諸如 svn checkout、svn update 和 svn commit 之類的子命令。當程式執行需要不同型別的命令列引數的多個不同功能時，以這種方式劃分功能可能是一個特別好的主意。ArgumentParser 支援使用 add_subparsers() 方法建立此類子命令。add_subparsers() 方法通常在沒有引數的情況下呼叫，並返回一個特殊的操作物件。此物件具有一個單獨的方法 add_parser()，該方法接受命令名稱和任何 ArgumentParser 建構函式引數，並返回一個可以照常修改的 ArgumentParser 物件。

引數描述

title - 幫助輸出中子解析器組的標題；如果提供了描述，則預設值為 “subcommands”，否則使用位置引數的標題
description - 幫助輸出中子解析器組的描述，預設值為 None
prog - 將與子命令幫助一起顯示的用法資訊，預設值為程式名稱和子解析器引數之前的任何位置引數
parser_class - 將用於建立子解析器例項的類，預設值為當前解析器的類（例如，ArgumentParser）
action - 當在命令列遇到此引數時要採取的基本操作型別
dest - 用於儲存子命令名稱的屬性名稱；預設值為 None，不儲存任何值
required - 是否必須提供子命令，預設值為 False （在 3.7 版本中新增）
help - 在幫助輸出中顯示的子解析器組的幫助資訊，預設值為 None
metavar - 在幫助資訊中呈現可用子命令的字串；預設值為 None，並以 {cmd1, cmd2, ..} 的形式呈現子命令

一些使用示例

>>> # create the top-level parser
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='subcommand help')
>>>
>>> # create the parser for the "a" command
>>> parser_a = subparsers.add_parser('a', help='a help')
>>> parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # create the parser for the "b" command
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz help')
>>>
>>> # parse some argument lists
>>> parser.parse_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
Namespace(baz='Z', foo=True)

請注意，parse_args() 返回的物件將只包含主解析器和命令列選定的子解析器的屬性（而不包含任何其他子解析器）。因此，在上面的示例中，當指定 a 命令時，僅存在 foo 和 bar 屬性，而當指定 b 命令時，僅存在 foo 和 baz 屬性。

類似地，當從子解析器請求幫助訊息時，只會列印該特定解析器的幫助資訊。幫助訊息不包括父解析器或同級解析器的訊息。（但是，可以透過為 add_parser() 提供 help= 引數來為每個子解析器命令提供幫助訊息，如上所述。）

>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] {a,b} ...

positional arguments:
  {a,b}   subcommand help
    a     a help
    b     b help

options:
  -h, --help  show this help message and exit
  --foo   foo help

>>> parser.parse_args(['a', '--help'])
usage: PROG a [-h] bar

positional arguments:
  bar     bar help

options:
  -h, --help  show this help message and exit

>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]

options:
  -h, --help     show this help message and exit
  --baz {X,Y,Z}  baz help

add_subparsers() 方法還支援 title 和 description 關鍵字引數。當其中任何一個存在時，子解析器的命令將以它們自己的組出現在幫助輸出中。例如：

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands',
...                                    description='valid subcommands',
...                                    help='additional help')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> parser.parse_args(['-h'])
usage:  [-h] {foo,bar} ...

options:
  -h, --help  show this help message and exit

subcommands:
  valid subcommands

  {foo,bar}   additional help

此外，add_parser() 支援一個額外的 *aliases* 引數，該引數允許使用多個字串來引用同一個子解析器。此示例（如 svn）將 co 作為 checkout 的簡寫。

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>> checkout = subparsers.add_parser('checkout', aliases=['co'])
>>> checkout.add_argument('foo')
>>> parser.parse_args(['co', 'bar'])
Namespace(foo='bar')

add_parser() 還支援一個額外的 *deprecated* 引數，該引數允許棄用子解析器。

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='chicken.py')
>>> subparsers = parser.add_subparsers()
>>> run = subparsers.add_parser('run')
>>> fly = subparsers.add_parser('fly', deprecated=True)
>>> parser.parse_args(['fly'])  
chicken.py: warning: command 'fly' is deprecated
Namespace()

在 3.13 版本中新增。

處理子命令的一種特別有效的方法是將 add_subparsers() 方法的使用與對 set_defaults() 的呼叫結合起來，以便每個子解析器都知道它應該執行哪個 Python 函式。例如：

>>> # subcommand functions
>>> def foo(args):
...     print(args.x * args.y)
...
>>> def bar(args):
...     print('((%s))' % args.z)
...
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(required=True)
>>>
>>> # create the parser for the "foo" command
>>> parser_foo = subparsers.add_parser('foo')
>>> parser_foo.add_argument('-x', type=int, default=1)
>>> parser_foo.add_argument('y', type=float)
>>> parser_foo.set_defaults(func=foo)
>>>
>>> # create the parser for the "bar" command
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))

這樣，您可以讓 parse_args() 在引數解析完成後呼叫適當的函式。將函式與這樣的操作關聯起來通常是處理每個子解析器的不同操作的最簡單方法。但是，如果需要檢查呼叫的子解析器的名稱，則可以為 add_subparsers() 呼叫使用 dest 關鍵字引數。

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(dest='subparser_name')
>>> subparser1 = subparsers.add_parser('1')
>>> subparser1.add_argument('-x')
>>> subparser2 = subparsers.add_parser('2')
>>> subparser2.add_argument('y')
>>> parser.parse_args(['2', 'frobble'])
Namespace(subparser_name='2', y='frobble')

在 3.7 版本中更改: 新增了 *required* 關鍵字引數。

FileType 物件¶

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)¶

FileType 工廠建立可以傳遞給 ArgumentParser.add_argument() 的 type 引數的物件。將 FileType 物件作為其型別的引數將以請求的模式、緩衝區大小、編碼和錯誤處理方式開啟命令列引數作為檔案（有關更多詳細資訊，請參閱 open() 函式）。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
>>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
>>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

FileType 物件理解偽引數 '-'，並自動將其轉換為可讀 FileType 物件的 sys.stdin 和可寫 FileType 物件的 sys.stdout。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

在 3.4 版本中更改: 添加了 *encodings* 和 *errors* 引數。

引數組¶

ArgumentParser.add_argument_group(title=None, description=None, *[, argument_default][, conflict_handler])¶

預設情況下，ArgumentParser 在顯示幫助訊息時將命令列引數分組為“位置引數”和“選項”。當存在比此預設分組更好的引數概念分組時，可以使用 add_argument_group() 方法建立適當的組。

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group = parser.add_argument_group('group')
>>> group.add_argument('--foo', help='foo help')
>>> group.add_argument('bar', help='bar help')
>>> parser.print_help()
usage: PROG [--foo FOO] bar

group:
  bar    bar help
  --foo FOO  foo help

add_argument_group() 方法返回一個引數組物件，該物件具有與常規 ArgumentParser 相同的 add_argument() 方法。當將引數新增到組中時，解析器會像處理普通引數一樣對待它，但在幫助訊息中將引數顯示在單獨的組中。add_argument_group() 方法接受 *title* 和 *description* 引數，這些引數可用於自定義此顯示。

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group1 = parser.add_argument_group('group1', 'group1 description')
>>> group1.add_argument('foo', help='foo help')
>>> group2 = parser.add_argument_group('group2', 'group2 description')
>>> group2.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [--bar BAR] foo

group1:
  group1 description

  foo    foo help

group2:
  group2 description

  --bar BAR  bar help

可選的，僅限關鍵字的引數 argument_default 和 conflict_handler 允許對引數組的行為進行更細粒度的控制。這些引數的含義與 ArgumentParser 建構函式中的含義相同，但專門應用於引數組而不是整個解析器。

請注意，任何不在使用者定義的組中的引數最終都會回到通常的“位置引數”和“可選引數”部分。

在 3.11 版本中更改: 在引數組上呼叫 add_argument_group() 已被棄用。此功能從未得到支援，並且並非始終正常工作。該功能透過繼承意外地存在於 API 上，將來將被刪除。

互斥¶

ArgumentParser.add_mutually_exclusive_group(required=False)¶

建立一個互斥組。argparse 將確保在命令列中只出現互斥組中的一個引數。

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group()
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args(['--foo'])
Namespace(bar=True, foo=True)
>>> parser.parse_args(['--bar'])
Namespace(bar=False, foo=False)
>>> parser.parse_args(['--foo', '--bar'])
usage: PROG [-h] [--foo | --bar]
PROG: error: argument --bar: not allowed with argument --foo

add_mutually_exclusive_group() 方法還接受一個 *required* 引數，用於指示至少需要一個互斥引數。

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group(required=True)
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args([])
usage: PROG [-h] (--foo | --bar)
PROG: error: one of the arguments --foo --bar is required

請注意，目前互斥引數組不支援 add_argument_group() 的 *title* 和 *description* 引數。但是，可以將互斥組新增到具有標題和描述的引數組中。例如：

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_argument_group('Group title', 'Group description')
>>> exclusive_group = group.add_mutually_exclusive_group(required=True)
>>> exclusive_group.add_argument('--foo', help='foo help')
>>> exclusive_group.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [-h] (--foo FOO | --bar BAR)

options:
  -h, --help  show this help message and exit

Group title:
  Group description

  --foo FOO   foo help
  --bar BAR   bar help

3.11 版本已更改: 在互斥組上呼叫 add_argument_group() 或 add_mutually_exclusive_group() 已被棄用。這些功能從未被支援，並且並不總是能正常工作。這些函式是透過繼承意外地存在於 API 中，將來會被移除。

解析器預設值¶

ArgumentParser.set_defaults(**kwargs)¶

大多數情況下，parse_args() 返回的物件的屬性將完全由檢查命令列引數和引數動作來確定。set_defaults() 允許新增一些無需檢查命令列即可確定的其他屬性。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.set_defaults(bar=42, baz='badger')
>>> parser.parse_args(['736'])
Namespace(bar=42, baz='badger', foo=736)

請注意，解析器級別的預設值總是會覆蓋引數級別的預設值。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')

當使用多個解析器時，解析器級別的預設值特別有用。有關此型別的示例，請參閱 add_subparsers() 方法。

ArgumentParser.get_default(dest)¶

獲取由 add_argument() 或 set_defaults() 設定的名稱空間屬性的預設值。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'

列印幫助資訊¶

在大多數典型應用程式中，parse_args() 將負責格式化和列印任何用法或錯誤訊息。但是，有幾種可用的格式化方法。

ArgumentParser.print_usage(file=None)¶: 列印如何在命令列上呼叫 ArgumentParser 的簡短描述。如果 file 為 None，則假定為 sys.stdout。

ArgumentParser.print_help(file=None)¶: 列印幫助訊息，包括程式用法和使用 ArgumentParser 註冊的引數資訊。如果 file 為 None，則假定為 sys.stdout。

這些方法也有一些變體，它們只是返回一個字串而不是列印它。

ArgumentParser.format_usage()¶: 返回一個字串，其中包含如何在命令列上呼叫 ArgumentParser 的簡短描述。

ArgumentParser.format_help()¶: 返回一個字串，其中包含幫助訊息，包括程式用法和使用 ArgumentParser 註冊的引數資訊。

部分解析¶

ArgumentParser.parse_known_args(args=None, namespace=None)¶

有時，指令碼可能只解析少量的命令列引數，將剩餘的引數傳遞給另一個指令碼或程式。在這些情況下，parse_known_args() 方法會很有用。它的工作方式與 parse_args() 非常相似，但當存在額外的引數時，它不會產生錯誤。相反，它會返回一個包含已填充的名稱空間和剩餘引數字串列表的兩項元組。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

警告

字首匹配規則適用於 parse_known_args()。解析器可能會使用一個選項，即使它只是其已知選項之一的字首，而不是將其保留在剩餘的引數列表中。

自定義檔案解析¶

ArgumentParser.convert_arg_line_to_args(arg_line)¶

從檔案中讀取的引數（請參閱 ArgumentParser 建構函式的 fromfile_prefix_chars 關鍵字引數）每行讀取一個引數。convert_arg_line_to_args() 可以被覆蓋以進行更復雜的讀取。

此方法接受一個引數 arg_line，它是從引數檔案中讀取的字串。它返回從此字串解析的引數列表。該方法會按順序從引數檔案中讀取的每一行呼叫一次。

此方法的一個有用的重寫是，將每個以空格分隔的單詞視為一個引數。以下示例演示瞭如何執行此操作：

class MyArgumentParser(argparse.ArgumentParser):
    def convert_arg_line_to_args(self, arg_line):
        return arg_line.split()

退出方法¶

ArgumentParser.exit(status=0, message=None)¶

此方法會終止程式，並以指定的 status 退出，如果給定，它會在之前將 message 列印到 sys.stderr。使用者可以重寫此方法以不同方式處理這些步驟。

class ErrorCatchingArgumentParser(argparse.ArgumentParser):
    def exit(self, status=0, message=None):
        if status:
            raise Exception(f'Exiting because of an error: {message}')
        exit(status)

ArgumentParser.error(message)¶: 此方法會向 sys.stderr 列印用法訊息，包括 message，並以狀態碼 2 終止程式。

混合解析¶

ArgumentParser.parse_intermixed_args(args=None, namespace=None)¶

ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)¶

許多 Unix 命令允許使用者將可選引數與位置引數混合使用。parse_intermixed_args() 和 parse_known_intermixed_args() 方法支援這種解析風格。

這些解析器不支援所有的 argparse 功能，如果使用不支援的功能，將會引發異常。特別是，不支援子解析器以及包含可選引數和位置引數的互斥組。

下面的示例顯示了 parse_known_args() 和 parse_intermixed_args() 之間的區別：前者將 ['2', '3'] 作為未解析的引數返回，而後者將所有位置引數收集到 rest 中。

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('cmd')
>>> parser.add_argument('rest', nargs='*', type=int)
>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

parse_known_intermixed_args() 返回一個包含已填充名稱空間和剩餘引數字串列表的兩項元組。如果有任何剩餘的未解析引數字串，parse_intermixed_args() 會引發錯誤。

3.7 版本新增。

註冊自定義型別或操作¶

ArgumentParser.register(registry_name, value, object)¶

有時，在錯誤訊息中使用自定義字串以提供更友好的使用者輸出是可取的。在這些情況下，可以使用 register() 向解析器註冊自定義操作或型別，並允許您透過其註冊名稱而不是其可呼叫名稱來引用該型別。

register() 方法接受三個引數 - registry_name，指定將儲存物件的內部登錄檔（例如，action, type），value，它是註冊物件的鍵，以及 object，即要註冊的可呼叫物件。

以下示例顯示瞭如何向解析器註冊自定義型別

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))
>>> parser.add_argument('--foo', type='hexadecimal integer')
_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default=None, type='hexadecimal integer', choices=None, required=False, help=None, metavar=None, deprecated=False)
>>> parser.parse_args(['--foo', '0xFA'])
Namespace(foo=250)
>>> parser.parse_args(['--foo', '1.2'])
usage: PROG [-h] [--foo FOO]
PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'

異常¶

exception argparse.ArgumentError¶

建立或使用引數（可選或位置引數）時發生的錯誤。

此異常的字串值是訊息，並補充了導致該錯誤的引數的資訊。

exception argparse.ArgumentTypeError¶: 當將命令列字串轉換為型別時出現問題時引發。

指南和教程

argparse — 命令列選項、引數和子命令的解析器¶