argparse-用於命令行選項、參數和子命令的解析器

import argparse    parser = argparse.ArgumentParser(description='Process some integers.')  parser.add_argument('integers', metavar='N', type=int, nargs='+',                      help='an integer for the accumulator')  parser.add_argument('--sum', dest='accumulate', action='store_const',                      const=sum, default=max,                      help='sum the integers (default: find the max)')    args = parser.parse_args()  print(args.accumulate(args.integers))

假設上面的Python程式碼保存到一個名為prog的文件中。，它可以在命令行運行，並提供有用的幫助資訊:

$ python prog.py -h  usage: prog.py [-h] [--sum] N [N ...]    Process some integers.    positional arguments:   N           an integer for the accumulator    optional arguments:   -h, --help  show this help message and exit   --sum       sum the integers (default: find the max)

當使用適當的參數運行時，它輸出命令行整數的和或最大值:

$ python prog.py 1 2 3 4  4    $ python prog.py 1 2 3 4 --sum  10

如果傳入無效參數，則會發出錯誤:

$ python prog.py a b c  usage: prog.py [-h] [--sum] N [N ...]  prog.py: error: argument N: invalid int value: 'a'

下面的部分將帶您了解這個示例。

創建一個解析器

使用argparse的第一步是創建一個ArgumentParser對象：

>>> parser = argparse.ArgumentParser(description='Process some integers.')

ArgumentParser對象將保存將命令行解析為Python數據類型所需的所有資訊。

添加參數

通過調用add_argument()方法，可以用關於程式參數的資訊填充ArgumentParser。通常，這些調用告訴ArgumentParser如何獲取命令行上的字元串並將它們轉換成對象。當調用parse_args()時，將存儲並使用此資訊。例如:

>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',  ...                     help='an integer for the accumulator')  >>> parser.add_argument('--sum', dest='accumulate', action='store_const',  ...                     const=sum, default=max,  ...                     help='sum the integers (default: find the max)')

稍後，調用parse_args()將返回一個具有整數和累加兩個屬性的對象。integers屬性將是一個或多個int的列表，而累加屬性將是sum()函數(如果——sum在命令行中指定)，或者max()函數(如果沒有)。

解析參數

ArgumentParser通過parse_args()方法解析參數。這將檢查命令行，將每個參數轉換為適當的類型，然後調用適當的操作。在大多數情況下，這意味著一個簡單的命名空間對象將建立從命令行解析的屬性:

>>> parser.parse_args(['--sum', '7', '-1', '42'])  Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

在腳本中，parse_args()通常沒有參數，ArgumentParser將自動確定sys.argv中的命令行參數。

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)

創建一個新的ArgumentParser對象。所有參數都應該作為關鍵字參數傳遞。每一個參數都有其更詳細的描述如下，但簡而言之，它們是:

prog – 程式名稱(默認:sys.argv[0])
usage – 描述程式使用情況的字元串(默認值:由添加到解析器的參數生成)
description – 要在參數help之前顯示的文本(默認值:none)
epilog – 參數help(默認:none)之後顯示的文本
parents – ArgumentParser對象的列表，其中也應該包含參數
formatter_class – 用於自定義幫助輸出的類
prefix_chars – 前綴可選參數的字符集(默認值:' – ')
fromfile_prefix_chars – 應該從前綴文件中讀取附加參數的一組字元(默認值:None)
argument_default – 參數的全局默認值(默認值:None)
conflict_handler – 解決衝突選項的策略(通常是不必要的)
add_help – 向解析器添加-h/——help選項(默認值:True)
allow_abbrev – 允許長選項被縮寫，如果縮寫是明確的。(默認值是真實的)

修改版本3.5:添加allow_abbrev參數。下面的部分將描述如何使用這些方法。

prog

默認情況下，ArgumentParser對象使用sys。以確定如何在幫助消息中顯示程式的名稱。這個預設值幾乎總是可取的，因為它將使幫助消息與在命令行上調用程式的方式匹配。例如，考慮一個名為myprogram.py的文件，其程式碼如下:

import argparse  parser = argparse.ArgumentParser()  parser.add_argument('--foo', help='foo help')  args = parser.parse_args()

該程式的幫助將顯示myprogram.py作為程式名(無論程式是從哪裡調用的):

$ python myprogram.py --help  usage: myprogram.py [-h] [--foo FOO]    optional arguments:   -h, --help  show this help message and exit   --foo FOO   foo help  $ cd ..  $ python subdir/myprogram.py --help  usage: myprogram.py [-h] [--foo FOO]    optional arguments:   -h, --help  show this help message and exit   --foo FOO   foo help

要更改此默認行為，可以使用prog= argument向ArgumentParser提供另一個值:

>>> parser = argparse.ArgumentParser(prog='myprogram')  >>> parser.print_help()  usage: myprogram [-h]    optional arguments:   -h, --help  show this help message and exit

注意，程式名是否由sys決定。可以使用%(prog)格式說明符幫助消息。

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

usage

默認情況下，ArgumentParser從它包含的參數中計算使用消息:

>>> parser = argparse.ArgumentParser(prog='PROG')  >>> parser.add_argument('--foo', nargs='?', help='foo help')  >>> parser.add_argument('bar', nargs='+', help='bar help')  >>> parser.print_help()  usage: PROG [-h] [--foo [FOO]] bar [bar ...]    positional arguments:   bar          bar help    optional arguments:   -h, --help   show this help message and exit   --foo [FOO]  foo help

可以使用usage= keyword參數重寫默認消息:

>>> 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    optional arguments:   -h, --help   show this help message and exit   --foo [FOO]  foo help

可以使用%(prog)s格式說明符在您的使用消息中填充程式名稱。

描述

對ArgumentParser構造函數的大多數調用將使用description= keyword參數。這個參數簡要描述了程式的功能及其工作原理。在幫助消息中，描述顯示在命令行用法字元串和各種參數的幫助消息之間:

>>> parser = argparse.ArgumentParser(description='A foo that bars')  >>> parser.print_help()  usage: argparse.py [-h]    A foo that bars    optional arguments:   -h, --help  show this help message and exit

默認情況下，描述將行包裝，以便適合給定的空間。要更改此行為，請參閱formatter_class參數。

epilog

有些程式喜歡在參數描述之後顯示程式的附加描述。這樣的文本可以使用epilog= argument指定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    optional arguments:   -h, --help  show this help message and exit    And that's how you'd foo a bar

與description參數一樣，默認情況下epilog= text是行包裝的，但是可以使用formatter_class參數到ArgumentParser調整此行為。

parents

有時，幾個解析器共享一組公共參數。與其重複這些參數的定義，不如使用一個包含所有共享參數並傳遞給parent = argument到ArgumentParser的單一解析器。parent =參數獲取一個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選項(一個在父類中，一個在子類中)，並引發一個錯誤。

Note

在通過parent =傳遞解析器之前，必須完全初始化它們。如果在子解析器之後更改父解析器，這些更改將不會反映在子解析器中。

formatter_class

ArgumentParser對象允許通過指定另一個格式化類來訂製幫助格式化。目前有四類:

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

RawDescriptionHelpFormatter和RawTextHelpFormatter對文本描述的顯示方式提供了更多的控制。默認情況下，ArgumentParser對象將描述和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    optional arguments:   -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=表示描述和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    optional arguments:   -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 [bar ...]]    positional arguments:   bar         BAR! (default: [1, 2, 3])    optional arguments:   -h, --help  show this help message and exit   --foo FOO   FOO! (default: 42)

MetavarTypeHelpFormatter為每個參數使用類型參數的名稱作為其值的顯示名稱(而不是像常規格式化程式那樣使用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    optional arguments:    -h, --help  show this help message and exit    --foo int

prefix_chars

大多數命令行選項將使用-作為前綴，例如-f/——foo。需要支援不同或額外前綴字元的解析器，例如+f或/foo選項，可以使用ArgumentParser構造函數的prefix_chars= argument指定它們:

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

有時，例如，當處理一個特別長的參數列表時，將參數列表保存在一個文件中，而不是在命令行中鍵入參數，可能是有意義的。如果將fromfile_prefix_chars=參數提供給ArgumentParser構造函數，那麼以任何指定字元開頭的參數都將被視為文件，並由它們包含的參數替換。例如:

>>> with open('args.txt', 'w') as fp:  ...     fp.write('-fnbar')  >>> 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']。fromfile_prefix_chars=參數默認為None，這意味著參數永遠不會被視為文件引用。

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

通常，當您將參數列表傳遞給ArgumentParser的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

New in version 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 t_handler= argument:

>>> 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]    optional arguments:   -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對象會添加一個選項，該選項只顯示解析器的幫助消息。例如，考慮一個名為myprogram.py的文件，其中包含以下程式碼:

import argparse  parser = argparse.ArgumentParser()  parser.add_argument('--foo', help='foo help')  args = parser.parse_args()

如果在命令行中提供-h或——help，將列印ArgumentParser help:

$ python myprogram.py --help  usage: myprogram.py [-h] [--foo FOO]    optional arguments:   -h, --help  show this help message and exit   --foo FOO   foo help

有時，禁用此幫助選項的添加可能很有用。這可以通過將False作為add_help=參數傳遞給ArgumentParser來實現:

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

help選項通常是-h/——help。例外情況是，如果指定了前綴_chars=，並且不包含-，在這種情況下-h和——help都不是有效的選項。在本例中，prefix_chars中的第一個字元用於為幫助選項添加前綴:

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')  >>> parser.print_help()  usage: PROG [+h]    optional arguments:    +h, ++help  show this help message and exit

The add_argument() 函數

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

定義如何解析單個命令行參數。每一個參數都有其更詳細的描述如下，但簡而言之，它們是:

name or flags – 一個名稱或一個選項字元串列表，例如foo或-f，——foo。
action – 當在命令行中遇到這個參數時要採取的基本操作類型。
nargs – 應該使用的命令行參數的數量。
const – 一些操作和nargs選擇所需的常量。
default – 如果參數不在命令行中生成的值。
type – 應該將命令行參數轉換為的類型。
choices – 參數允許值的容器。
required – 是否可以省略命令行選項(僅限選項)。
help – 一個簡短的描述什麼論點做。
metavar – 使用消息中參數的名稱。
dest – 要添加到parse_args()返回的對象中的屬性的名稱。

下面的部分將描述如何使用這些方法。

name or flags

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' – 它只存儲參數的值。這是默認操作。例如: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('–foo') >>> parser.parse_args('–foo 1'.split()) Namespace(foo='1')
'store_const' – 它存儲由const關鍵字參數指定的值。「store_const」操作通常與指定某種標誌的可選參數一起使用。例如: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('–foo', action='store_const', const=42) >>> parser.parse_args(['–foo']) Namespace(foo=42)
'store_true' and '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'>])
'count' – 這將計算關鍵字參數出現的次數。例如，這對於增加冗長程度很有用: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('–verbose', '-v', action='count') >>> parser.parse_args(['-vvv']) Namespace(verbose=3)
'help' – 這將為當前解析器中的所有選項列印完整的幫助消息，然後退出。默認情況下，幫助操作會自動添加到解析器中。有關如何創建輸出的詳細資訊，請參見ArgumentParser。
'version' – 這需要在add_argument()調用中使用version= keyword參數，並在調用時列印版本資訊並退出: >>> 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

還可以通過傳遞實現相同介面的action子類或其他對象來指定任意操作。推薦的方法是擴展Action，覆蓋_call__方法和可選的_init__方法。

自定義操作的一個例子:

>>> class FooAction(argparse.Action):  ...     def __init__(self, option_strings, dest, nargs=None, **kwargs):  ...         if nargs is not None:  ...             raise ValueError("nargs not allowed")  ...         super(FooAction, self).__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')

nargs

ArgumentParser對象通常將一個命令行參數與一個要執行的操作關聯起來。nargs關鍵字參數將不同數量的命令行參數與一個操作關聯起來。支援的值是:

N (an integer). 命令行中的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生成一個包含一項的列表。這與默認值不同，默認值中項目是由自己生成的。
'?'. 如果可能，一個參數將從命令行中使用，並作為單個項目生成。如果不存在命令行參數，則會生成默認值。注意，對於可選參數，還有另外一種情況——出現了選項字元串，但後面沒有命令行參數。在本例中，將生成來自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'])
'+'. Just like '*',所有當前的命令行arg都被收集到一個列表中。此外，如果沒有至少一個命令行參數，將生成錯誤消息。例如: >>> 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
argparse.REMAINDER. 所有剩餘的命令行參數都被收集到一個列表中。這對於調度到其他命令行實用程式的命令行實用程式通常很有用: >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('–foo') >>> parser.add_argument('command') >>> parser.add_argument('args', nargs=argparse.REMAINDER) >>> print(parser.parse_args('–foo B cmd –arg1 XX ZZ'.split())) Namespace(args=['–arg1', 'XX', 'ZZ'], command='cmd', foo='B')

如果沒有提供nargs關鍵字參數，則使用的參數數量由操作決定。通常，這意味著將使用一個命令行參數，並生成一個項目(而不是列表)。

const

add_argument()的const參數用於保存常量，這些常量不是從命令行讀取的，而是用於各種ArgumentParser操作。它最常見的兩個用途是:

當使用action='store_const'或action='append_const'調用add_argument()時。這些操作將const值添加到parse_args()返回的對象的一個屬性中。有關示例，請參見操作描述。
當使用選項字元串(如-f或——foo)和nargs='?'調用add_argument()時。這將創建一個可選參數，後面可以跟著零個或一個命令行參數。在解析命令行時，如果遇到選項字元串後面沒有命令行參數，那麼將使用const的值。有關示例，請參見nargs描述。

對於「store_const」和「append_const」操作，必須給出const關鍵字參數。對於其他操作，默認為None。

default

所有可選參數和一些位置參數都可以在命令行中省略。add_argument()的默認關鍵字參數的值默認為None，它指定如果命令行參數不存在，應該使用什麼值。對於可選參數，在命令行不存在選項字元串時使用默認值:

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

如果默認值是字元串，則解析器將解析該值，就像解析命令行參數一樣。特別是，在設置名稱空間返回值的屬性之前，如果提供了類型轉換參數，解析器將應用任何類型轉換參數。否則，解析器將使用如下值:

>>> 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等於?的位置參數?或者*，當沒有命令行參數時使用默認值:

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

提供默認= argparse。如果命令行參數不存在，則不會添加任何屬性:

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

type

默認情況下，ArgumentParser對象以簡單字元串的形式讀取命令行參數。然而，命令行字元串通常應該被解釋為另一種類型，比如float或int. add_argument()的type關鍵字參數允許執行任何必要的類型檢查和類型轉換。常見的內置類型和函數可以直接用作類型參數的值:

>>> parser = argparse.ArgumentParser()  >>> parser.add_argument('foo', type=int)  >>> parser.add_argument('bar', type=open)  >>> parser.parse_args('2 temp.txt'.split())  Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)

有關類型參數何時應用於默認參數的資訊，請參閱default關鍵字參數一節。為了方便使用各種類型的文件，argparse模組提供了工廠文件類型，它接受open()函數的mode=、bufsize=、encoding=和errors=參數。例如，FileType('w')可以用來創建一個可寫文件:

>>> parser = argparse.ArgumentParser()  >>> parser.add_argument('bar', type=argparse.FileType('w'))  >>> parser.parse_args(['out.txt'])  Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)

type=可以接受任何接受單個字元串參數並返迴轉換值的可調用值:

>>> def perfect_square(string):  ...     value = int(string)  ...     sqrt = math.sqrt(value)  ...     if sqrt != int(sqrt):  ...         msg = "%r is not a perfect square" % string  ...         raise argparse.ArgumentTypeError(msg)  ...     return value  ...  >>> parser = argparse.ArgumentParser(prog='PROG')  >>> parser.add_argument('foo', type=perfect_square)  >>> parser.parse_args(['9'])  Namespace(foo=9)  >>> parser.parse_args(['7'])  usage: PROG [-h] foo  PROG: error: argument foo: '7' is not a perfect square

對於類型檢查器來說，options關鍵字參數可能更方便，因為它只檢查一系列值:

>>> parser = argparse.ArgumentParser(prog='PROG')  >>> parser.add_argument('foo', type=int, choices=range(5, 10))  >>> parser.parse_args(['7'])  Namespace(foo=7)  >>> parser.parse_args(['11'])  usage: PROG [-h] {5,6,7,8,9}  PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)

choices

應該從一組受限制的值中選擇一些命令行參數。可以通過將容器對象作為choice關鍵字參數傳遞給add_argument()來處理這些問題。當解析命令行時，將檢查參數值，如果參數不是可接受的值之一，將顯示錯誤消息:

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

注意，在執行任何類型轉換之後，都會檢查選項容器中的包含內容，因此選項容器中的對象的類型應該與指定的類型匹配:

>>> parser = argparse.ArgumentParser(prog='doors.py')  >>> parser.add_argument('door', type=int, choices=range(1, 4))  >>> print(parser.parse_args(['3']))  Namespace(door=3)  >>> parser.parse_args(['4'])  usage: doors.py [-h] {1,2,3}  doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

任何支援in操作符的對象都可以作為選擇值傳遞，因此dict對象、set對象、訂製容器等都是受支援的。

required

通常，argparse模組假設-f和-bar等標誌表示可選參數，這些參數在命令行中總是可以省略。要使選項成為必需的，可以為required= keyword參數指定True，然後將其指定為add_argument():

>>> parser = argparse.ArgumentParser()  >>> parser.add_argument('--foo', required=True)  >>> parser.parse_args(['--foo', 'BAR'])  Namespace(foo='BAR')  >>> parser.parse_args([])  usage: argparse.py [-h] [--foo FOO]  argparse.py: error: option --foo is required

如示例所示，如果一個選項被標記為required，那麼如果該選項不在命令行中，parse_args()將報告一個錯誤。必需選項通常被認為是不好的形式，因為用戶希望選項是可選的，因此應該儘可能避免它們。

help

幫助值是一個字元串，包含參數的簡短描述。當用戶請求幫助(通常在命令行使用-h或——help)時，這些幫助描述將與每個參數一起顯示:

>>> parser = argparse.ArgumentParser(prog='frobble')  >>> parser.add_argument('--foo', action='store_true',  ...                     help='foo the bars before frobbling')  >>> parser.add_argument('bar', nargs='+',  ...                     help='one of the bars to be frobbled')  >>> parser.parse_args(['-h'])  usage: frobble [-h] [--foo] bar [bar ...]    positional arguments:   bar     one of the bars to be frobbled    optional arguments:   -h, --help  show this help message and exit   --foo   foo the bars before frobbling

幫助字元串可以包含各種格式說明符，以避免重複程式名或參數默認值等內容。可用的說明符包括程式名、%(prog)s和add_argument()的大多數關鍵字參數，例如%(默認值)s、%(類型)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)    optional arguments:   -h, --help  show this help message and exit

由於幫助字元串支援%-格式化，如果希望幫助字元串中出現文字%，則必須將其轉義為%%。通過將幫助值設置為argparse. suppress, argparse支援對某些選項禁用幫助條目:

>>> parser = argparse.ArgumentParser(prog='frobble')  >>> parser.add_argument('--foo', help=argparse.SUPPRESS)  >>> parser.print_help()  usage: frobble [-h]    optional arguments:    -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    optional arguments:   -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    optional arguments:   -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]    optional arguments:   -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通過獲取第一個長選項字元串並去掉初始字元串——string來生成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')

Action類

Action類實現Action API，一個可調用的API返回一個可調用的API，該API處理命令行中的參數。任何遵循此API的對象都可以作為操作參數傳遞給add_argument()。

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

ArgumentParser使用Action對象來表示從命令行中的一個或多個字元串解析單個參數所需的資訊。Action類必須接受兩個位置參數和傳遞給ArgumentParser.add_argument()的關鍵字參數(除了Action本身)。Action實例(或任何可調用Action參數的返回值)應該定義屬性「dest」、「option_string」、「default」、「type」、「required」、「help」等。確保定義這些屬性的最簡單方法是調用action . _init__。Action實例應該是可調用的，因此子類必須覆蓋_call__方法，該方法應該接受四個參數:

parser – 包含此操作的ArgumentParser對象。
namespace – 將由parse_args()返回的名稱空間對象。大多數操作使用setattr()向該對象添加屬性。
values – 關聯的命令行參數，以及應用的任何類型轉換。類型轉換由Type關鍵字參數指定為add_argument()。
option_string – 用於調用此操作的選項字元串。option_string參數是可選的，如果操作與位置參數關聯，則該參數將不存在。

方法可以執行任意操作，但通常會基於dest和值在名稱空間上設置屬性。

The parse_args() method

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

將參數字元串轉換為對象，並將它們指定為名稱空間的屬性。返回填充的名稱空間。之前對add_argument()的調用確定了創建什麼對象以及如何分配對象。有關詳細資訊，請參閱add_argument()文檔。

args – 要解析的字元串列表。默認值取自sys.argv。
namespace – 獲取屬性的對象。默認值是一個新的空名稱空間對象。

Option value syntax

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

Invalid arguments

在解析命令行時，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

Arguments containing `-`

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)

Argument縮減

默認情況下，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禁用此特性。

Beyond `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])

The Namespace object

class argparse.Namespace

parse_args()默認情況下使用Simple類創建一個包含屬性的對象並返回它。這個類非常簡單，只是一個帶有可讀字元串表示的對象子類。如果您希望屬性具有類似於詞典的視圖，可以使用標準Python習語vars():

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

讓ArgumentParser將屬性分配給一個已經存在的對象，而不是一個新的名稱空間對象，這可能也很有用。這可以通過指定namespace= keyword參數來實現:

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

Other utilities

Sub-commands

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

許多程式將其功能分解為許多子命令，例如，svn程式可以調用svn checkout、svn update和svn commit等子命令。當一個程式執行幾個不同的函數，而這些函數又需要不同類型的命令行參數時，以這種方式分割功能可能是一個特別好的主意。ArgumentParser支援使用add_subparsers()方法創建這樣的子命令。add_subparsers()方法通常不帶參數調用，並返回一個特殊的操作對象。這個對象只有一個方法add_parser()，它接受命令名和任何ArgumentParser構造函數參數，並返回一個可以像往常一樣修改的ArgumentParser對象。

對參數的描述：

title – 幫助輸出中子解析器組的標題;默認情況下，如果提供描述，則使用「子命令」，否則使用title作為位置參數。
description – 幫助輸出中的子解析器組的描述，默認情況下為None。
prog – 使用子命令幫助將顯示的使用資訊，默認情況下程式的名稱和子解析器參數之前的任何位置參數。
parser_class – 用於創建子解析器實例的類，默認情況下是當前解析器的類(例如ArgumentParser)。
action – 當在命令行中遇到這個參數時要採取的基本操作類型。
dest – 將存儲子命令名的屬性的名稱;默認情況下，不存儲任何值。
required – 是否必須提供子命令，默認情況下為False。
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='sub-command 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='XYZ', 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}   sub-command help      a     a help      b     b help    optional arguments:    -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    optional arguments:    -h, --help  show this help message and exit    >>> parser.parse_args(['b', '--help'])  usage: PROG b [-h] [--baz {X,Y,Z}]    optional arguments:    -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} ...    optional arguments:    -h, --help  show this help message and exit    subcommands:    valid subcommands      {foo,bar}   additional help

此外，add_parser支援一個附加的別名參數，該參數允許多個字元串引用同一個子解析器。這個例子，像svn一樣，別名co作為結帳的縮寫:

>>> 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_subparsers()方法的使用與對set_defaults()的調用結合起來，這樣每個子解析器都知道應該執行哪個Python函數。例如:

>>> # sub-command 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()  >>>  >>> # 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')

FileType objects

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

FileType工廠創建可以傳遞給ArgumentParser.add_argument()的類型參數的對象。將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對象理解偽參數'-'，並自動將其轉換為sys。stdin用於可讀的文件類型對象和sys。可寫文件類型對象的標準輸出:

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

Argument groups

ArgumentParser.add_argument_group(title=None, description=None)

默認情況下，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()方法返回一個參數組對象，該對象具有一個add_argument()方法，就像一個常規的ArgumentParser一樣。當一個參數被添加到組中時，解析器就像對待一個普通的參數一樣對待它，但是會在一個單獨的組中顯示該參數以獲取幫助消息。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

注意，任何不在用戶定義的組中的參數都將回到通常的「位置參數」和「可選參數」部分。

Mutual exclusion

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()方法也接受一個必需的參數，以表明至少需要一個互斥參數:

>>> 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()的標題和描述參數。

Parser defaults

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'

Printing help

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

ArgumentParser.print_usage(file=None)

列印一個關於應該如何在命令行上調用ArgumentParser的簡短描述。如果文件為空，則sys。stdout。

ArgumentParser.print_help(file=None)

列印一條幫助消息，包括程式使用情況和關於ArgumentParser註冊的參數的資訊。如果文件為空，則sys.stdout。這些方法也有一些變體，它們只是返回一個字元串，而不是列印它:

ArgumentParser.format_usage()

返回一個字元串，該字元串包含應該如何在命令行上調用ArgumentParser的簡短描述。

ArgumentParser.format_help()

返回一個包含幫助消息的字元串，包括程式使用情況和關於ArgumentParser註冊的參數的資訊。

Partial parsing

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

Warning

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

Customizing file parsing

ArgumentParser.convert_arg_line_to_args(arg_line)

從文件中讀取的參數(請參閱fromfile_prefix_chars關鍵字參數到ArgumentParser構造函數)每一行讀取一個參數。convert_arg_line_to_args()可以被覆蓋，以便更好地閱讀。這個方法接受一個參數arg_line，它是從參數文件中讀取的字元串。它返回從該字元串解析的參數列表。方法按順序每行從參數文件中讀取一次。此方法的一個有用覆蓋是將每個空格分隔的單詞作為一個參數。下面的例子演示了如何做到這一點:

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

Exiting methods

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

此方法終止程式，以指定的狀態退出，如果給定，則在此之前列印一條消息。

ArgumentParser.error(message)

此方法將一個使用消息(包括發送給標準錯誤的消息)列印出來，並使用狀態程式碼2終止程式。

Intermixed parsing

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特性，如果使用不支援的特性，就會引發異常。特別是子解析器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()將引發錯誤。

Upgrading optparse code

最初，argparse模組試圖保持與optparse的兼容性。但是，optparse很難透明地擴展，特別是需要進行更改來支援新的nargs=說明符和更好的使用消息。當optparse中的大多數內容要麼是複製粘貼的，要麼是修改過的，那麼試圖保持向後兼容性似乎就不再可行了。

argparse模組在許多方面改進了標準庫optparse模組，包括:

處理位置參數。
支援sub-commands。
允許使用+和/這樣的替代選項前綴。
處理零個或多個樣式參數和一個或多個樣式參數。
生成更多資訊的使用消息。
為自定義類型和操作提供更簡單的介面。

從optparse到argparse的部分升級路徑:

用ArgumentParser.add_argument()調用替換所有的optparser . optionparser .add_option()調用。
用args = parser.parse_args()替換(options, args) = parser.parse_args()，並為位置參數添加額外的ArgumentParser.add_argument()調用。請記住，以前稱為options，現在在argparse上下文中稱為args。
使用parse_intermixed_args()代替parse_args()來替換optparse.OptionParser.disable_interspersed_args()。
用類型或操作參數替換回調操作和callback_*關鍵字參數。
用相應的類型對象(例如int、float、complex等)替換類型關鍵字參數的字元串名稱。
取代optparse。具有名稱空間和optparse的值。OptionError optparse。OptionValueError ArgumentError。
使用標準Python語法用隱式參數(如%default或%prog)替換字元串，使用字典格式化字元串，即%(default)s和%(prog)s。
用對parser的調用替換OptionParser構造函數版本參數。add_argument('——version'， action='version'， version='<版本>')。
用ArgumentParser.add_argument()調用替換所有的optparser . optionparser .add_option()調用。
用args = parser.parse_args()替換(options, args) = parser.parse_args()，並為位置參數添加額外的ArgumentParser.add_argument()調用。請記住，以前稱為options，現在在argparse上下文中稱為args。
使用parse_intermixed_args()代替parse_args()來替換optparse.OptionParser.disable_interspersed_args()。
用類型或操作參數替換回調操作和callback_*關鍵字參數。
用相應的類型對象(例如int、float、complex等)替換類型關鍵字參數的字元串名稱。
取代optparse。具有名稱空間和optparse的值。OptionError optparse。OptionValueError ArgumentError。
使用標準Python語法用隱式參數(如%default或%prog)替換字元串，使用字典格式化字元串，即%(default)s和%(prog)s。
用對parser的調用替換OptionParser構造函數版本參數。add_argument('——version'， action='version'， version='<版本>')。