バージョン 2.7 で追加.
argparse モジュールはユーザーフレンドリーなコマンドラインインタフェースの作成を簡単にします。プログラムがどんな引数を必要としているのかを定義すると、 argparse が sys.argv からそのオプションをパースする部分の面倒を見ます。 argparse モジュールは自動的にヘルプと使用方法メッセージを生成し、ユーザーが不正な引数をプログラムに指定したときにエラーを発生させます。
次のコードは、整数のリストを受け取って合計か最大値を返す Python プログラムです:
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.py という名前のファイルに保存されたと仮定します。コマンドラインから実行して、便利なヘルプメッセージを提供することができます。
$ 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)
妥当な引数を与えて実行された場合、このプログラムはコマンドライン引数の整数列の合計か最大値を表示します:
$ prog.py 1 2 3 4
4
$ prog.py 1 2 3 4 --sum
10
不正な引数が与えられた場合、エラーを発生させます:
$ 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 データ型にするために必要な全ての情報を保持します。
ArgumentParser にプログラム引数の情報を与えるために、 add_argument() メソッドを呼び出します。一般的に、このメソッドの呼び出しは 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 と accumulate という2つの属性を持ったオブジェクトを返します。 integers 属性は1つ以上の整数のリストで、 accumulate 属性はコマンドラインから --sum が指定された場合は sum() 関数、それ以外の場合は max() 関数になります。
ArgumentParser は引数を parse_args() メソッドでパースします。このメソッドはコマンドラインを調べ、各引数を正しい型に変換して、適切なアクションを実行します。ほとんどの場合、これはシンプルな namespace オブジェクトをコマンドラインの解析結果から構築することを意味します:
>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])
スクリプトでは、 parse_args() は典型的には引数なしで呼び出され、 ArgumentParser は自動的に sys.argv からコマンドライン引数を取得します。
新しい ArgumentParser オブジェクトを生成します。各引数についてはあとで詳しく説明しますが、簡単に言うと:
以下のセクションでは各オプションの利用方法を解説します。
多くの場合、 ArgumentParser のコンストラクタを呼び出すときに description= キーワード引数が利用されます。この引数はプログラムが何をしてどう動くのかについての短い説明です。ヘルプメッセージで、この description はコマンドラインの利用法と引数のヘルプメッセージの間に表示されます:
>>> 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
デフォルトでは、 description は行ラップされるので、与えられたスペースにマッチします。この挙動を変更するには、 formatter_class 引数を参照してください。
いくつかのプログラムは、プログラムについての追加の説明を引数の解説の後に表示します。このテキストは ArgumentParser の epilog= 引数に指定することができます:
>>> 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= テキストもデフォルトで行ラップされ、 ArgumentParser の formatter_class 引数で動作を調整することができます。
デフォルトでは、 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
必要に応じて、この help オプションを無効にする場合があります。これは ArgumentParser の add_help= 引数に False を渡すことで可能です:
>>> 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
ヘルプオプションは通常 -h/--help です。例外は prefix_chars= が指定されてその中に '-' が無かった場合で、その場合は -h と --help は有効なオプションではありません。この場合、 prefix_chars の最初の文字がヘルプオプションの prefix として利用されます:
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]
optional arguments:
+h, ++help show this help message and exit
ほとんどのコマンドラインオプションは、 -f/--foo のように prefix に '-' を使います。 +f や /foo のような、他の、あるいは追加の prefix 文字をサポートしなければならない場合、 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 オプションが許可されなくなります。
ときどき、例えば非常に長い引数リストを扱う場合に、その引数リストを毎回コマンドラインにタイプする代わりにファイルに置いておきたい場合があります。 ArgumentParser のコンストラクタに fromfile_prefix_chars= 引数が指定された場合、指定された文字のいずれかで始まる引数はファイルとして扱われ、そのファイルに含まれる引数リストに置換されます。例えば:
>>> with open('args.txt', 'w') 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')
ファイルから読み込まれる引数は、デフォルトでは1行に1つ(ただし、 convert_arg_line_to_args() も参照してください)で、コマンドライン上でファイルを参照する引数があった場所にその引数があったものとして扱われます。なので、上の例では、 ['-f', 'foo', '@args.txt'] は ['-f', 'foo', '-f', 'bar'] と等価になります。
fromfile_prefix_chars= 引数のデフォルト値は None で、引数がファイル参照だとして扱われることが無いことを意味しています。
一般的には、引数のデフォルト値は add_argument() メソッドにデフォルト値を渡すか、 set_defaults() メソッドに name-value ペアを渡すことで指定します。しかしまれに、1つのパーサー全体に適用されるデフォルト引数が便利なことがあります。これをするには、 ArgumentParser に argument_default= キーワード引数を渡します。例えば、全体で 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()
ときどき、いくつかのパーサーが共通の引数セットを共有することがあります。それらの引数を繰り返し定義する代わりに、全ての共通引数を持った parser を 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 は2つの -h/--help オプションを与えられる (1つは親から、もうひとつは子から) ことになり、エラーを発生させます。
ノート
parents= に渡す前にパーサーを完全に初期化する必要があります。子パーサーを作成してから親パーサーを変更した場合、その変更は子パーサーに反映されません。
ArgumentParser オブジェクトは代わりのフォーマットクラスを指定することでヘルプのフォーマットをカスタマイズすることができます。現在、3つのフォーマットクラスがあります:
最初の2つは説明のテキストがどう表示されるかについてより制御できるようになっており、残りの1つは引数のデフォルト値についての情報を自動的に追加します。
デフォルトでは、 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
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
formatter_class= に RawDescriptionHelpFormatter を渡すと、 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
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)
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
ときどき (例えば、 parents を利用する場合など), 古い引数を同じオプション文字列で上書きするほうが便利な場合があります。この動作をするには、 ArgumentParser の conflict_handler= 引数に 'resolve' を渡します:
>>> 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 オブジェクトは、全てのオプション文字列がオーバーライドサれた場合にだけアクションを削除することに注目してください。上の例では、 --foo オプション文字列だけがオーバーライドされているので、古い -f/--foo アクションは -f アクションとして残っています。
デフォルトでは、 ArgumentParser オブジェクトはヘルプメッセージ中に表示するプログラム名を sys.argv[0] から取得します。このデフォルトの動作は、プログラムがコマンドライン上でどう起動されたにヘルプメッセージをマッチさせるので、か多くの場合に正しい挙動です。例えば、 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
このデフォルトの動作を変更するには、 ArgumentParser の prog= 引数に他の値を指定します:
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]
optional arguments:
-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]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
デフォルトでは、 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= キーワード引数でオーバーライドできます:
>>> 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 フォーマット指定子を、使用法メッセージ中でプログラム名として利用できます。
1つのコマンドライン引数がどう解析されるかを定義します。各引数についての解説は以下で行いますが、簡潔には:
以下のセクションではこれらの使い方を説明します。
add_argument() メソッドは、指定されているのが -f や --foo のようなオプション引数なのか、ファイル名リストなどの位置引数なのかを知る必要があります。そのため、 add_argument() の第1引数は、フラグのリストか、シンプルな引数名のどちらかになります。例えば、オプション引数は次のようにして作ります:
>>> parser.add_argument('-f', '--foo')
一方、位置引数は次のようにして作ります:
>>> parser.add_argument('bar')
parse_args() が呼ばれた時、オプション引数は - prefix により識別され、それ以外の引数は位置引数として扱われます:
>>> 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: too few arguments
ArgumentParser オブジェクトはコマンドライン引数にアクションを割り当てます。このアクションは、割り当てられたコマンドライン引数に関してどんな処理でもできますが、ほとんどのアクションは単に parse_args() が返すオブジェクトに属性を追加するだけです。 action キーワード引数は、コマンドライン引数がどう処理されるかを指定します。サポートされているアクションは:
'store' - これは単に引数の値を格納します。これはデフォルトのアクションです。例えば:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args('--foo 1'.split())
Namespace(foo='1')
'store_const' - このアクションは const キーワード引数で指定された値を格納します。 (const キーワード引数のデフォルト値はあまり役に立たない None であることに注意) 'store_const' アクションは、何かの種類のフラグを指定するオプション引数によく使われます。例えば:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args('--foo'.split())
Namespace(foo=42)
'store_true', 'store_false' - これらのアクションはそれぞれ True と False を格納します。これらは 'store_const' の特別版になります。例えば:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
Namespace(bar=False, foo=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=[<type 'str'>, <type 'int'>])
'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
Action API を実装したオブジェクトを渡すことで、任意のアクションを指定することもできます。独自のアクションを作る一番手軽な方法は argparse.Action を継承して、適切な __call__ メソッドを実装することです。 __call__ メソッドは 4つの引数を受け取らなければなりません:
カスタムアクションの例です:
>>> class FooAction(argparse.Action):
... 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')
ArgumentParser オブジェクトは通常1つのコマンドライン引数を1つのアクションに渡します。 nargs キーワード引数は1つのアクションにそれ以外の数のコマンドライン引数を割り当てます。指定できる値は:
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 は1要素のリストを作ることに注意してください。これはデフォルトの、要素がそのまま属性になる動作とは異なります。
'?'. 可能なら1つの引数がコマンドラインから取られ、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'.split())
Namespace(bar='XX', foo='YY')
>>> parser.parse_args('XX --foo'.split())
Namespace(bar='XX', foo='c')
>>> parser.parse_args(''.split())
Namespace(bar='d', foo='d')
nargs='?' のよくある利用例の1つは、入出力ファイルの指定オプションです:
>>> 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=<open file 'input.txt', mode 'r' at 0x...>,
outfile=<open file 'output.txt', mode 'w' at 0x...>)
>>> parser.parse_args([])
Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>,
outfile=<open file '<stdout>', mode 'w' at 0x...>)
'*'. 全てのコマンドライン引数がリストに集められます。複数の位置引数が 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'])
'+'. '*' と同じように、全てのコマンドライン引数をリストに集めます。加えて、最低でも1つのコマンドライン引数が存在しない場合にエラーメッセージを生成します。例えば:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
>>> parser.parse_args('a b'.split())
Namespace(foo=['a', 'b'])
>>> parser.parse_args(''.split())
usage: PROG [-h] foo [foo ...]
PROG: error: too few arguments
nargs キーワード引数が指定されない場合、消費される引数の数は action によって決定されます。通常これは、1つのコマンドライン引数は1つのアイテムになる(リストにはならない)ことを意味します。
add_argument() の const 引数は、コマンドライン引数から読み込まれないけれども ArgumentParser のいくつかのアクションで必要とされる値のために使われます。この引数の2つのよくあるユースケースは:
const キーワード引数のデフォルト値は None です。
全てのオプション引数といくつかの位置引数はコマンドライン上で省略されることがあります。 add_argument() の default キーワード引数(デフォルト: None)は、コマンドライン引数が存在しなかった場合に利用する値を指定します。オプション引数では、オプション文字列がコマンドライン上に存在しなかったときに default の値が利用されます:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args('--foo 2'.split())
Namespace(foo='2')
>>> parser.parse_args(''.split())
Namespace(foo=42)
位置引数では、 nargs ='?' か '*' で、コマンドライン引数が存在しなかったときに default 値が利用されます:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args('a'.split())
Namespace(foo='a')
>>> parser.parse_args(''.split())
Namespace(foo=42)
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')
デフォルトでは、 ArgumentParser オブジェクトはコマンドライン引数を単なる文字列として読み込みます。しかし、コマンドラインの文字列は float, int, file など別の型として扱うべき事がよくあります。 add_argument() の type キーワード引数により型チェックと型変換を行うことができます。たくさんのよく使われるビルトイン型を type 引数の値として直接指定することができます:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=file)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<open file 'temp.txt', mode 'r' at 0x...>, foo=2)
いろいろな種類のファイルを簡単に扱うために、 argparse モジュールは mode= と bufsize= 引数を取る FileType ファクトリを提供しています。例えば、書き込み可能なファイルを作るために FileType('w') を利用できます:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>)
type= には1つの文字列を引数に受け取って型変換結果を返すような任意の callable を渡すことができます:
>>> 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'.split())
Namespace(foo=9)
>>> parser.parse_args('7'.split())
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square
さらに、 choices キーワード引数を使って、値の範囲をチェックすることもできます:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=xrange(5, 10))
>>> parser.parse_args('7'.split())
Namespace(foo=7)
>>> parser.parse_args('11'.split())
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
詳細は choices セクションを参照してください。
コマンドライン引数をいくつかの選択肢のなかから選ばせたい場合があります。これは add_argument() に choices キーワード引数を渡すことで可能です。コマンドラインを解析する時、引数の値がチェックされ、その値が選択肢の中に含まれていない場合はエラーメッセージを表示します:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', choices='abc')
>>> parser.parse_args('c'.split())
Namespace(foo='c')
>>> parser.parse_args('X'.split())
usage: PROG [-h] {a,b,c}
PROG: error: argument foo: invalid choice: 'X' (choose from 'a', 'b', 'c')
choices コンテナに含まれているかどうかのチェックは、 type による型変換が実行された後であることに注意してください。なので、 choices に格納するオブジェクトの型は指定された type にマッチしている必要があります:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=complex, choices=[1, 1j])
>>> parser.parse_args('1j'.split())
Namespace(foo=1j)
>>> parser.parse_args('-- -4'.split())
usage: PROG [-h] {1,1j}
PROG: error: argument foo: invalid choice: (-4+0j) (choose from 1, 1j)
in 演算をサポートしている任意のオブジェクトを choices に渡すことができます。なので、 dict, set, その他カスタムコンテナなどは全てサポートしています。
通常、 argparse モジュールは -f や --bar といったフラグは オプション(optional) 引数だと仮定し、コマンドライン上になくても良いものとして扱います。オプションを 要求(required) するには、 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: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required
上の例のように、オプションが required と指定されると、 parse_args() はそのオプションがコマンドラインに存在しないときにエラーを表示します。
ノート
ユーザーは option は 自由に選択できる(optional) だと期待するので、 required option は一般的には悪いもので、できる限り避けるべきです。
help の値はその引数の簡潔な説明を含む文字列です。ユーザーが(コマンドライン上で -h か --help を指定するなどして) ヘルプを要求したとき、この 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'.split())
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
help 文字列には、プログラム名や引数の default などを繰り返し記述するのを避けるためのフォーマット指定子を含めることができます。利用できる指定子には、プログラム名 %(prog)s と、 %(default)s や %(type)s など add_argument() のキーワード引数の多くが含まれます:
>>> 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
ArgumentParser がヘルプメッセージを出力する時、各引数に対してなんらかの参照方法が必要です。デフォルトでは、 ArgumentParser オブジェクトは各オブジェクトの “名前” として dest を利用します。デフォルトでは、位置引数には dest の値をそのまま利用し、オプション引数については dest の値を大文字に変換して利用します。なので、1つの dest='bar' である位置引数は bar として参照されます。 1つのオプション引数 --foo が1つのコマンドライン引数を要求するときは、その引数は 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
ほとんどの ArgumentParser のアクションは parse_args() が返すオブジェクトに対する属性として値を追加します。この属性の名前は add_argument() の dest キーワード引数によって決定されます。位置引数のアクションについては、 dest は通常 add_argument() の第一引数として渡します:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args('XXX'.split())
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')
引数の文字列をオブジェクトに変換し、 namespace オブジェクトの属性に代入します。結果の namespace オブジェクトを返します。
事前の add_argument() メソッドの呼び出しが、どのオブジェクトが生成されてどう代入されるかを決定します。詳細は add_argument() のドキュメントを参照してください。
デフォルトでは、引数文字列は sys.argv から取られ、新しい空の Namespace オブジェクトが属性のために作られます。
parse_args() メソッドはオプションの値(があれば) を指定する複数の方法をサポートしています。一番シンプルな方法は、オプションとその値は2つの別々の引数として渡されます:
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args('-x X'.split())
Namespace(foo=None, x='X')
>>> parser.parse_args('--foo FOO'.split())
Namespace(foo='FOO', x=None)
長いオプション (1文字よりも長い名前を持ったオプション) では、オプションとその値は = で区切られた1つのコマンドライン引数として渡すこともできます:
>>> parser.parse_args('--foo=FOO'.split())
Namespace(foo='FOO', x=None)
短いオプション (1文字のオプション) では、オプションとその値は連結して渡すことができます:
>>> parser.parse_args('-xX'.split())
Namespace(foo=None, x='X')
複数の短いオプションは、最後の1つ(か、0個)のオプションだけが値を要求する場合には、1つの - prefix だけで連結することができます:
>>> 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'.split())
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)
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
引数が複数のオプションになり得る場合はエラーになります。
ArgumentParser が sys.argv 以外の引数をパースできると役に立つ場合があります。その場合は文字列のリストを parse_args() に渡します。これはインタラクティブプロンプトからテストするときに便利です:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
... 'integers', metavar='int', type=int, choices=xrange(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'.split())
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
デフォルトでは、 parse_args() は Namespace の新しいオブジェクトに必要な属性を設定して返します。このクラスはシンプルに設計されており、単に読みやすい文字列表現を持った object のサブクラスです。もし属性を辞書のように扱える方が良ければ、 vars() を使う標準的な Python のイディオムを利用することができます:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}
ArgumentParser が、新しい Namespace オブジェクトではなく、既存のオブジェクトに属性を設定する方が良い場合があります。これは namespace= キーワード引数を指定することで可能です:
>>> class C(object):
... pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'
多くのプログラムは、その機能をサブコマンドへと分割します。例えば svn プログラムは svn checkout, svn update, svn commit などのサブコマンドを利用できます。機能をサブコマンドに分割するのは、プログラムがいくつかの異なった機能を持っていて、それぞれが異なるコマンドライン引数を必要とする場合には良いアイデアです。 ArgumentParser は add_subparsers() メソッドによりサブコマンドをサポートしています。 add_subparsers() メソッドは通常引数なしに呼び出され、特殊なアクションオブジェクトを返します。このオブジェクトには1つのメソッド add_parser() があり、コマンド名と ArgumentParser コンストラクタの任意の引数を受け取り、通常の方法で操作できる ArgumentParser オブジェクトを返します。
いくつかの使用例:
>>> # 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 arg 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
サブコマンドを扱う1つの便利な方法は 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 ファクトリは ArgumentParser.add_argument() の type 引数に渡すことができるオブジェクトを生成します。 type が FileType オブジェクトである引数はコマンドライン引数を、指定されたモードとバッファサイズでファイルとして開きます:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--output', type=argparse.FileType('wb', 0))
>>> parser.parse_args(['--output', 'out'])
Namespace(output=<open file 'out', mode 'wb' at 0x...>)
FileType オブジェクトは擬似引数 '-' を識別し、読み込み用の FileType であれば sys.stdin を、書き込み用の FileType であれば sys.stdout に変換します:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>)
デフォルトでは、 ArgumentParser はヘルプメッセージを表示するときに、コマンドライン引数を “positional arguments”(位置引数) と “optional arguments”(オプション引数) にグループ化します。このデフォルトの動作よりも良い引数のグループ化方法がある場合、 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
ユーザー定義グループ以外の全ての引数は通常の “positional arguments” と “optional arguments” セクションに表示されます。
相互排他グループを作ります。 argparse は相互排他グループの中でただ1つの引数のみが存在することを確認します:
>>> 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() メソッドは、その相互排他引数のどれか 1つを選ぶことが要求されることを示す 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 引数をサポートしていません。
ほとんどの場合、 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')
パーサーレベルの default は、複数のパーサーを扱うときに特に便利です。このタイプの例については add_subparsers() メソッドを参照してください。
add_argument() か set_defaults() によって指定された、 namespace の属性のデフォルト値を取得します:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'
ほとんどの典型的なアプリケーションでは、 parse_args() が使用法やエラーメッセージのフォーマットと表示について面倒を見ます。しかし、いくつかのフォーマットメソッドが利用できます:
ArgumentParser がコマンドラインからどう実行されるべきかの短い説明を表示します。 file が None の時は、 sys.stdout に出力されます。
プログラムの使用法と ArgumentParser に登録された引数についての情報を含むヘルプメッセージを表示します。 file が None の時は、 sys.stdout に出力されます。
これらのメソッドの、表示する代わりにシンプルに文字列を返すバージョンもあります:
ArgumentParser がコマンドラインからどう実行されるべきかの短い説明を格納した文字列を返します。
プログラムの使用法と ArgumentParser に登録された引数についての情報を含むヘルプメッセージを格納した文字列を返します。
ときどき、スクリプトがコマンドライン引数のいくつかだけを解析し、残りの引数は別のスクリプトやプログラムに渡すことがあります。こういった場合、 parse_known_args() メソッドが便利です。これは parse_args() と同じように動作しますが、余分な引数が存在してもエラーを生成しません。代わりに、評価された namespace オブジェクトと、残りの引数文字列のリストからなる2要素タプルを返します。
>>> 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'])
ファイルから引数を読み込む場合(ArgumentParser コンストラクタの fromfile_prefix_chars キーワード引数を参照)、1行につき1つの引数を読み込みます。 convert_arg_line_to_args() をオーバーライドしてこの動作をカスタマイズすることができます。
このメソッドは、引数ファイルから読まれた文字列である1つの引数 arg_line を受け取ります。そしてその文字列を解析した結果の引数のリストを返します。このメソッドはファイルから1行読みこむごとに、順番に呼ばれます。
このメソッドをオーバーライドする便利な例として、スペース区切りのワードを 1つの引数として扱います:
def convert_arg_line_to_args(self, arg_line):
for arg in arg_line.split():
if not arg.strip():
continue
yield arg
もともと、 argparse モジュールを optparse モジュールとの互換性を保って開発しようという試みがありました。しかし、特に新しい nargs= 指定子とより良い使用法メッセージのために必要な変更のために、 optparse を透過的に拡張することは難しかったのです。 optparse のほとんどすべてがコピーペーストされたりモンキーパッチを当てられたりしたとき、もはや後方互換性を保とうとすることは現実的ではありませんでした。
optparse から argparse への現実的なアップグレード・パス: