argparse
--- Parser for command-line options, arguments and sub-commands¶
バージョン 3.2 で追加.
ソースコード: Lib/argparse.py
argparse
モジュールは、ユーザーフレンドリーなコマンドラインインターフェースの作成を簡単にします。プログラムは必要とする引数が何かを定義し、 argparse
は sys.argv
からそれらの引数を解析する方法を見つけ出します。また、 argparse
モジュールはヘルプや使用方法のメッセージを自動的に生成します。さらに、このモジュールはユーザーが不正な引数をプログラムに与えた場合にエラーを発生させます。
中核的な機能¶
The argparse
module's support for command-line interfaces is built
around an instance of argparse.ArgumentParser
. It is a container for
argument specifications and has options that apply the parser as whole:
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)
add_argument() のためのクイックリンク¶
名前 |
説明 |
値 |
---|---|---|
引数をどのように処理するかを指定します |
|
|
特定の選択肢に値を制限します |
|
|
定数値を保存します |
||
引数が指定されなかったときに使われるデフォルト値です |
特に指定がない場合は |
|
引数解析結果の名前空間で使われる属性名を指定します |
||
引数のためのヘルプメッセージです |
||
ヘルプで表示される、引数の代わりの名前です |
||
引数として受け取ることのできる数です |
|
|
その引数が必須か、オプションかを指定します |
|
|
引数を与えられた型に自動的に変換します |
使用例¶
次のコードは、整数のリストを受け取って合計か最大値を返す 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
という名前のファイルに保存したとすると、このファイルはコマンドラインから実行可能で、次のような有用なヘルプメッセージを提供します:
$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]
Process some integers.
positional arguments:
N an integer for the accumulator
options:
-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 データ型にするために必要なすべての情報を保持します。
引数を追加する¶
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 オブジェクト¶
- 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 - オプションの引数の prefix になる文字集合 (デフォルト: '-')
fromfile_prefix_chars - 追加の引数を読み込むファイルの prefix になる文字集合 (デフォルト:
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
オブジェクトはヘルプメッセージ中に表示するプログラム名を 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]
options:
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
options:
-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]
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
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
options:
-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
options:
-h, --help show this help message and exit
--foo [FOO] foo help
%(prog)s
フォーマット指定子を、使用法メッセージ内でプログラム名として利用できます。
description¶
多くの場合、ArgumentParser
のコンストラクターを呼び出すときに description=
キーワード引数が使用されます。この引数はプログラムが何をしてどう動くのかについての短い説明になります。ヘルプメッセージで、この説明がコマンドラインの利用法と引数のヘルプメッセージの間に表示されます:
>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]
A foo that bars
options:
-h, --help show this help message and exit
デフォルトでは、説明は与えられたスペースに合わせて折り返されます。この挙動を変更するには、formatter_class 引数を参照してください。
epilog¶
いくつかのプログラムは、プログラムについての追加の説明を引数の説明の後に表示します。このテキストは 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
options:
-h, --help show this help message and exit
And that's how you'd foo a bar
description 引数と同じく、epilog=
テキストもデフォルトで折り返され、ArgumentParser
の formatter_class 引数で動作を調整できます。
parents¶
ときどき、いくつかのパーサーが共通の引数セットを共有することがあります。それらの引数を繰り返し定義する代わりに、すべての共通引数を持ったパーサーを 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=
に渡す前にパーサーを完全に初期化する必要があります。子パーサーを作成してから親パーサーを変更した場合、その変更は子パーサーに反映されません。
formatter_class¶
ArgumentParser
オブジェクトは代わりのフォーマットクラスを指定することでヘルプのフォーマットをカスタマイズできます。現在、4つのフォーマットクラスがあります:
- 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
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
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
prefix_chars¶
ほとんどのコマンドラインオプションは、-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
のコンストラクターに 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
で、引数がファイル参照として扱われることがないことを意味しています。
argument_default¶
一般的には、引数のデフォルト値は add_argument()
メソッドにデフォルト値を渡すか、set_defaults()
メソッドに名前と値のペアを渡すことで指定します。しかしまれに、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()
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
バージョン 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
ときどき (例えば 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]
options:
-h, --help show this help message and exit
-f FOO old foo help
--foo FOO new foo help
ArgumentParser
オブジェクトは、すべてのオプション文字列が上書きされた場合にだけアクションを削除することに注目してください。上の例では、 --foo
オプション文字列だけが上書きされているので、古い -f/--foo
アクションは -f
アクションとして残っています。
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]
options:
-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]
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¶
通常、不正な引数リストが ArgumentParser
の parse_args()
メソッドに渡された場合、プログラムはエラー情報を出力して終了します。
もしエラーを例外としてプログラム内でキャッチしたい場合は、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])¶
1つのコマンドライン引数がどう解析されるかを定義します。各引数についての詳細は後述しますが、簡単に言うと:
name または flags - 名前か、あるいはオプション文字列のリスト (例:
foo
や-f, --foo
)。action - コマンドラインにこの引数があったときのアクション。
nargs - 受け取るべきコマンドライン引数の数。
default - コマンドラインに対応する引数が存在せず、さらに namespace オブジェクトにも存在しない場合に利用される値。
type - コマンドライン引数が変換されるべき型。
choices - 引数として許される値のシーケンス。
required - コマンドラインオプションが省略可能かどうか (オプション引数のみ)。
help - 引数が何なのかを示す簡潔な説明。
metavar - 使用法メッセージの中で使われる引数の名前。
dest -
parse_args()
が返すオブジェクトに追加される属性名。
以下の節では各オプションの利用方法を説明します。
name または 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 キーワード引数で指定された値を格納します。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'>])
'count'
- このアクションはキーワード引数の数を数えます。例えば、verboseレベルを上げるのに役立ちます:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--verbose', '-v', action='count', default=0) >>> parser.parse_args(['-vvv']) Namespace(verbose=3)
default は明示的に 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
'extend'
- このアクションはリストを格納して、各引数の値でそのリストを拡張します。利用例:>>> 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 で追加.
また、Action のサブクラス、またはそれと同じインターフェースを実装するオブジェクトを渡すことにより、任意のアクションを指定することができます。例えば argparse
モジュールには BooleanOptionalAction
があり、--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
メソッド) をオーバーライドすることです。
カスタムアクションの例です:
>>> 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 objects usually associate a single command-line argument with a
single action to be taken. The nargs
keyword argument associates a
different number of command-line arguments with a single action. The supported
values are:
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']) Namespace(bar='XX', foo='YY') >>> parser.parse_args(['XX', '--foo']) Namespace(bar='XX', foo='c') >>> parser.parse_args([]) 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=<_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'])
'+'
--'*'
と同じように、すべてのコマンドライン引数をリストに集めます。加えて、最低でも1つのコマンドライン引数が存在しない場合にエラーメッセージを生成します。例えば:>>> 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 によって決定されます。通常これは、1つのコマンドライン引数は1つのアイテムになる (リストにはならない) ことを意味します。
const¶
add_argument()
の const
引数は、コマンドライン引数から読み込まれないけれども ArgumentParser
のいくつかのアクションで必要とされる値のために使われます。この引数のよくある2つの使用法は:
add_argument()
がaction='store_const'
かaction='append_const'
で呼び出されたとき、これらのアクションはconst
の値をparse_args()
が返すオブジェクトの属性に追加します。サンプルは action の説明を参照してください。const
がadd_argument()
に与えられなければ、None
のデフォルト値を受け取ります。add_argument()
がオプション文字列 (-f
や--foo
) とnargs='?'
で呼び出された場合。この場合0個か1つのコマンドライン引数を取るオプション引数が作られます。オプション引数にコマンドライン引数が続かなかった場合、代わりにconst
の値がNone
であると見なされます。サンプルは nargs の説明を参照してください。
バージョン 3.11 で変更: action='append_const'
や action='store_const'
の場合も含め、デフォルトでは const=None
です。
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)
対象となる namespace がすでにその属性を持っている場合、それは 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)
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 converter により、必要な型チェックと型変換を行うことができます。
もし type キーワードが default キーワードとともに使用された場合、default の値が文字列のときのみ、type converter による変換などが行われます。
type
キーワードの引数として、単一の文字列を受け取るような任意の呼び出しオブジェクト (callable) が使用できます。もし呼び出しが ArgumentTypeError
, TypeError
, または ValueError
型の例外を送出した場合は、parser がそれをキャッチして適切なエラーメッセージが表示されます。それ以外の型の例外は処理されません。
一般的なビルトインデータ型や関数を type
引数の値として直接指定できます:
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('source_file', type=open)
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')
Type converter として bool()
関数を使用することは推奨されません。なぜなら、これは空文字列を False
に、それ以外の全てを True
に変換しますが、これはおそらく望まれる動作ではないからです (訳注: 文字列 'false'
を False
に変換してくれたりはしません)。
一般論として、type
キーワードに指定するものは、せいぜい上記の3種類の例外を発生するくらいの、お手軽な変換に限るべきです。より複雑な (interesting) エラー処理、またはリソース管理を伴うものは、引数を解析したあとに別個の処理として行うべきです。
たとえば、JSON または YAML からの変換は複雑なエラーケースを持つので、type
がサポートする以上のエラー表示を必要とするでしょう。(JSON デコーダが発生しうる) JSONDecodeError
は適切に整形されて表示されません。また、FileNotFoundError
が発生しても parser は何も処理しません。
また、type
キーワードに FileType
を指定した場合には制限があります。ある引数に FileType を指定してファイルが開かれ、その後ろのどこかの引数で処理が失敗した場合、エラーが表示されますが、開かれたファイルは自動では close されません。これを好まない場合は、parser による引数の処理が終わるまで待ち、その後に 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')
choices シーケンスに含まれているかどうかのチェックは、type による型変換が実行された後であることに注意してください。このため、choices シーケンス中のオブジェクトの型は指定された type にマッチしている必要があります:
>>> 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)
任意のシーケンスを 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
の説明が各引数に表示されます:
>>> 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
options:
-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)
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 の値を大文字に変換して利用します。このため、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
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')
Action クラス¶
Acrtion クラスは 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 クラス 2 つの位置引数と、action
それ自身を除く ArgumentParser.add_argument()
に渡されるすべてのキーワード引数を受け付けなければなりません。
Action のインスタンス (あるいは action
引数に渡す任意の呼び出し可能オブジェクトの返り値) は、属性 "dest", "option_strings", "default", "type", "required", "help", などを定義しなければなりません。これらの属性を定義するのを確実にするためにもっとも簡単な方法は、Action.__init__
を呼び出すことです。
Action インスタンスは呼び出し可能でなければならず、したがって、サブクラスは 4 つの引数を受け取る __call__
メソッドをオーバライドしなければなりません:
parser
- このアクションを持っている ArgumentParser オブジェクト。namespace
-parse_args()
が返すNamespace
オブジェクト。ほとんどのアクションはこのオブジェクトに属性をsetattr()
を使って追加します。values
- 型変換が適用された後の、関連付けられたコマンドライン引数。型変換はadd_argument()
メソッドの type キーワード引数で指定されます。option_string
- このアクションを実行したオプション文字列。option_string
引数はオプションで、アクションが位置引数に関連付けられた場合は渡されません。
__call__
メソッドでは任意のアクションを行えます。典型的には dest
および values
に基いて namespace
に属性をセットします。
Action のサブクラスを定義する際に format_usage
メソッドを実装することができます。このメソッドは引数を受け取らず、プログラムの使用方法 (usage) を表示する際に使われる文字列を返すようにします。このメソッドが実装されていない場合は、sensible default (訳注: システムにより上手く設定されたデフォルト値) が使われます。
parse_args() メソッド¶
- ArgumentParser.parse_args(args=None, namespace=None)¶
引数の文字列をオブジェクトに変換し、namespace オブジェクトの属性に代入します。結果の namespace オブジェクトを返します。
事前の
add_argument()
メソッドの呼び出しにより、どのオブジェクトが生成されてどう代入されるかが決定されます。詳細はadd_argument()
のドキュメントを参照してください。
オプション値の文法¶
parse_args()
メソッドは、オプションの値がある場合、そのオプションの値の指定に複数の方法をサポートしています。もっとも単純な場合には、オプションとその値は次のように2つの別々の引数として渡されます:
>>> 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)
長いオプション (1文字よりも長い名前を持ったオプション) では、オプションとその値は次のように =
で区切られた1つのコマンドライン引数として渡すこともできます:
>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)
短いオプション (1文字のオプション) では、オプションとその値は次のように連結して渡すことができます:
>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')
最後の1つのオプションだけが値を要求する場合、または値を要求するオプションがない場合、複数の短いオプションは次のように1つの接頭辞 -
だけで連結できます:
>>> 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)
引数の短縮形 (先頭文字でのマッチング)¶
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])
Namespace オブジェクト¶
- 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'}
ArgumentParser
が、新しい 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][, option_strings][, dest][, required][, help][, metavar])¶
多くのプログラムは、その機能をサブコマンドへと分割します。 例えば
svn
プログラムはsvn checkout
,svn update
,svn commit
などのサブコマンドを利用できます。 機能をサブコマンドに分割するのは、プログラムがいくつかの異なった機能を持っていて、 それぞれが異なるコマンドライン引数を必要とする場合には良いアイデアです。ArgumentParser
はadd_subparsers()
メソッドによりサブコマンドを サポートしています。add_subparsers()
メソッドは通常引数なしに呼び出され、 特殊なアクションオブジェクトを返します。このオブジェクトには1つのメソッドadd_parser()
があり、コマンド名とArgumentParser
コンストラクターの任意の引数を受け取り、通常の方法で操作できるArgumentParser
オブジェクトを返します。引数の説明:
title - ヘルプ出力でのサブパーサーグループのタイトルです。デフォルトは、description が指定されている場合は "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='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 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
Furthermore,
add_parser
supports an additionalaliases
argument, which allows multiple strings to refer to the same subparser. This example, likesvn
, aliasesco
as a shorthand forcheckout
:>>> 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')
サブコマンドを扱う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(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 引数に渡すことができるオブジェクトを生成します。 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)¶
デフォルトでは、
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
ユーザー定義グループにないすべての引数は通常の "位置引数" と "オプション引数" セクションに表示されます。
バージョン 3.11 で変更: 引数グループについて
add_argument_group()
を呼び出すことは非推奨です。この機能はこれまでサポートされたことはなく、常に正しく動作するとは限りません。この関数は継承を通じて思いがけず API に存在することになったもので、将来削除される予定です。
相互排他¶
- ArgumentParser.add_mutually_exclusive_group(required=False)¶
相互排他グループを作ります。
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()
メソッドの引数 required に True 値を指定すると、その相互排他引数のどれか1つを選ぶことが要求されます:>>> 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
Note that currently mutually exclusive argument groups do not support the title and description arguments of
add_argument_group()
.バージョン 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')
パーサーレベルの default は、複数のパーサーを扱うときに特に便利です。このタイプの例については
add_subparsers()
メソッドを参照してください。
- ArgumentParser.get_default(dest)¶
add_argument()
かset_defaults()
によって指定された、 namespace の属性のデフォルト値を取得します:>>> 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()
と同じように動作しますが、余分な引数が存在してもエラーを生成しません。代わりに、評価された 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'])
警告
先頭文字でのマッチング ルールは parse_known_args()
にも適用されます。たとえ既知のオプションの先頭文字に過ぎない場合でも、パーサは引数リストに残さずに、オプションを受け取る場合があります。
ファイル解析のカスタマイズ¶
- ArgumentParser.convert_arg_line_to_args(arg_line)¶
ファイルから引数を読み込む場合 (
ArgumentParser
コンストラクターの fromfile_prefix_chars キーワード引数を参照)、1行につき1つの引数を読み込みます。convert_arg_line_to_args()
を変更することでこの動作をカスタマイズできます。このメソッドは、引数ファイルから読まれた文字列である1つの引数 arg_line を受け取ります。そしてその文字列を解析した結果の引数のリストを返します。このメソッドはファイルから1行読みこむごとに、順番に呼ばれます。
このメソッドをオーバーライドすると便利なこととして、スペースで区切られた行の単語1つ1つを別々の引数として扱えます。次の例でその方法を示します:
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 を終了前に表示します。ユーザは、この振る舞いを違うものにするために、メソッドをオーバーライドすることができます。
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)¶
このメソッドは 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()
は、解析した内容を含む名前空間と、残りの引数を含んだリストの、2つの要素を持つタプルを返します。
parse_intermixed_args()
は、解析されない引数が残された場合にはエラーを送出します。
バージョン 3.7 で追加.
optparse からのアップグレード¶
もともと、argparse
モジュールは optparse
モジュールとの互換性を保って開発しようと試みられました。しかし、特に新しい nargs=
指定子とより良い使用法メッセージのために必要な変更のために、optparse
を透過的に拡張することは難しかったのです。optparse
のほとんどすべてがコピーアンドペーストされたりモンキーパッチを当てられたりしたとき、もはや後方互換性を保とうとすることは現実的ではありませんでした。
argparse
モジュールは標準ライブラリ optparse
モジュールを、以下を含むたくさんの方法で改善しています:
位置引数を扱う
サブコマンドのサポート
+
,/
のような代替オプションプレフィクスを許容するzero-or-more スタイル、one-or-more スタイルの引数を扱う
より有益な使用方法メッセージの生成
カスタム
type
, カスタムaction
のために遥かに簡単なインターフェイスを提供する
optparse
から argparse
への現実的なアップグレードパス:
すべての
optparse.OptionParser.add_option()
の呼び出しを、ArgumentParser.add_argument()
の呼び出しに置き換える。(options, args) = parser.parse_args()
をargs = parser.parse_args()
に置き換え、位置引数のために必要に応じてArgumentParser.add_argument()
の呼び出しを追加する。これまでoptions
と呼ばれていたものが、argparse
ではargs
と呼ばれていることに留意してください。optparse.OptionParser.disable_interspersed_args()
を、parse_args()
ではなくparse_intermixed_args()
で置き換える。コールバック・アクションと
callback_*
キーワード引数をtype
やaction
引数に置き換える。type
キーワード引数に渡していた文字列の名前を、それに応じたオブジェクト (例: int, float, complex, ...) に置き換える。optparse.Values
をNamespace
に置き換え、optparse.OptionError
とoptparse.OptionValueError
をArgumentError
に置き換える。%default
や%prog
などの暗黙の引数を含む文字列を、%(default)s
や%(prog)s
などの、通常の Python で辞書を使う場合のフォーマット文字列に置き換える。OptionParser のコンストラクターの
version
引数を、parser.add_argument('--version', action='version', version='<the version>')
に置き換える
例外¶
- exception argparse.ArgumentError¶
引数 (オプション引数または位置引数) の生成時または利用時のエラーです。
この例外の文字列表現は、エラーの原因となった引数についての情報を補足するメッセージです。
- exception argparse.ArgumentTypeError¶
コマンドラインの文字列を、指定された型に変換するのに失敗した時に送出されます。