16.4. argparse —コマンドラインオプション、引数、およびサブコマンドのパーサー—Pythonドキュメント
16.4。 argparse —コマンドラインオプション、引数、およびサブコマンドのパーサー
バージョン3.2の新機能。
ソースコード: :source: `Lib / argparse.py`
チュートリアル
このページには、APIリファレンス情報が含まれています。 Pythonコマンドライン解析のより穏やかな紹介については、 argparseチュートリアルをご覧ください。
argparse モジュールを使用すると、ユーザーフレンドリーなコマンドラインインターフェイスを簡単に作成できます。 プログラムは必要な引数を定義し、 argparse は sys.argv からそれらを解析する方法を理解します。 argparse モジュールは、ヘルプメッセージと使用法メッセージも自動的に生成し、ユーザーがプログラムに無効な引数を指定するとエラーを発行します。
16.4.1。 例
次のコードは、整数のリストを取得し、合計または最大値を生成する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
optional arguments:
-h, --help show this help message and exit
--sum sum the integers (default: find the max)
適切な引数を指定して実行すると、コマンドライン整数の合計または最大値が出力されます。
$ python prog.py 1 2 3 4
4
$ python prog.py 1 2 3 4 --sum
10
無効な引数が渡されると、エラーが発生します。
$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: 'a'
次のセクションでは、この例について説明します。
16.4.1.1。 パーサーの作成
argparse を使用する最初のステップは、 ArgumentParser オブジェクトを作成することです。
>>> parser = argparse.ArgumentParser(description='Process some integers.')
ArgumentParser オブジェクトは、コマンドラインをPythonデータ型に解析するために必要なすべての情報を保持します。
16.4.1.2。 引数の追加
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つ以上のintのリストになり、--sum
があった場合、accumulate
属性は sum()関数になります。コマンドラインで指定するか、そうでない場合は max()関数で指定します。
16.4.1.3。 引数の解析
ArgumentParser は、 parse_args()メソッドを介して引数を解析します。 これにより、コマンドラインが検査され、各引数が適切なタイプに変換されてから、適切なアクションが呼び出されます。 ほとんどの場合、これは、コマンドラインから解析された属性から単純な名前空間オブジェクトが構築されることを意味します。
>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])
スクリプトでは、 parse_args()は通常、引数なしで呼び出され、 ArgumentParser は sys.argv からコマンドライン引数を自動的に決定します。
16.4.2。 ArgumentParserオブジェクト
- class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True)
新しい ArgumentParser オブジェクトを作成します。 すべてのパラメータは、キーワード引数として渡す必要があります。 各パラメータには、以下に独自の詳細な説明がありますが、簡単に言うと次のとおりです。
prog -プログラムの名前(デフォルト:
sys.argv[0]
)Usage -プログラムの使用法を説明する文字列(デフォルト:パーサーに追加された引数から生成)
description -引数ヘルプの前に表示するテキスト(デフォルト:なし)
epilog -引数ヘルプの後に表示するテキスト(デフォルト:なし)
parents -引数も含める必要がある ArgumentParser オブジェクトのリスト
formatter_class -ヘルプ出力をカスタマイズするためのクラス
prefix_chars -オプションの引数の前に付ける文字のセット(デフォルト: '-')
fromfile_prefix_chars -追加の引数を読み取るファイルのプレフィックスとなる文字のセット(デフォルト:
None
)arguments_default -引数のグローバルデフォルト値(デフォルト:
None
)conflict_handler -競合するオプションを解決するための戦略(通常は不要)
add_help -
-h/--help
オプションをパーサーに追加します(デフォルト:True
)allow_abbrev -省略形が明確な場合、長いオプションを省略できるようにします。 (デフォルト:
True
)
バージョン3.5で変更: allow_abbrev パラメーターが追加されました。
次のセクションでは、これらのそれぞれの使用方法について説明します。
16.4.2.1。 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]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
このデフォルトの動作を変更するには、prog=
引数を ArgumentParser に使用して別の値を指定できます。
>>> 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
16.4.2.2。 利用方法
デフォルトでは、 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
形式指定子を使用して、使用法メッセージにプログラム名を入力できます。
16.4.2.3。 説明
ArgumentParser コンストラクターへのほとんどの呼び出しは、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
デフォルトでは、説明は指定されたスペースに収まるように行で折り返されます。 この動作を変更するには、 formatter_class 引数を参照してください。
16.4.2.4。 エピローグ
一部のプログラムは、引数の説明の後にプログラムの追加の説明を表示することを好みます。 このようなテキストは、 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 引数で調整できます。 ]。
16.4.2.5。 両親
場合によっては、複数のパーサーが共通の引数セットを共有します。 これらの引数の定義を繰り返すのではなく、すべての共有引数を持ち、parents=
引数から ArgumentParser に渡される単一のパーサーを使用できます。 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つは親に、もう1つは子に)を参照してエラーを発生させます。
ノート
parents=
を介してパーサーを渡す前に、パーサーを完全に初期化する必要があります。 子パーサーの後に親パーサーを変更した場合、それらの変更は子に反映されません。
16.4.2.6。 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
optional arguments:
-h, --help show this help message and exit
likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines
RawDescriptionHelpFormatter をformatter_class=
として渡すことは、 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 は、引数の説明を含む、あらゆる種類のヘルプテキストの空白を維持します。 ただし、複数の新しい行が1つに置き換えられます。 複数の空白行を保持する場合は、改行の間にスペースを追加します。
ArgumentDefaultsHelpFormatter は、デフォルト値に関する情報を各引数ヘルプメッセージに自動的に追加します。
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar [bar ...]]
positional arguments:
bar BAR! (default: [1, 2, 3])
optional arguments:
-h, --help show this help message and exit
--foo FOO FOO! (default: 42)
MetavarTypeHelpFormatter は、各引数の 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
optional arguments:
-h, --help show this help message and exit
--foo int
16.4.2.7。 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
オプションが使用できなくなります。
16.4.2.8。 fromfile_prefix_chars
たとえば、特に長い引数リストを処理する場合、コマンドラインで入力するのではなく、引数のリストをファイルに保持する方が理にかなっている場合があります。 fromfile_prefix_chars=
引数が ArgumentParser コンストラクターに指定された場合、指定された文字のいずれかで始まる引数はファイルとして扱われ、それらに含まれる引数に置き換えられます。 例えば:
>>> 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
です。これは、引数がファイル参照として扱われることはないことを意味します。
16.4.2.9。 引数のデフォルト
一般に、引数のデフォルトは、デフォルトを add_argument()に渡すか、特定の名前と値のペアのセットを使用して set_defaults()メソッドを呼び出すことによって指定されます。 ただし、引数にパーサー全体のデフォルトを1つ指定すると便利な場合があります。 これは、argument_default=
キーワード引数を ArgumentParser に渡すことで実現できます。 たとえば、 parse_args()呼び出しでの属性作成をグローバルに抑制するために、argument_default=SUPPRESS
を提供します。
>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()
16.4.2.10。 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の新機能。
16.4.2.11。 conflict_handler
ArgumentParser オブジェクトは、同じオプション文字列を持つ2つのアクションを許可しません。 デフォルトでは、 ArgumentParser オブジェクトは、すでに使用されているオプション文字列を使用して引数を作成しようとすると、例外を発生させます。
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
..
ArgumentError: argument --foo: conflicting option string(s): --foo
時々(例えば 親)を使用する場合、同じオプション文字列で古い引数を単純にオーバーライドすると便利な場合があります。 この動作を実現するには、値'resolve'
を ArgumentParser のconflict_handler=
引数に指定できます。
>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]
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
アクションとして保持されます。
16.4.2.12。 add_help
デフォルトでは、ArgumentParserオブジェクトは、パーサーのヘルプメッセージを表示するだけのオプションを追加します。 たとえば、次のコードを含むmyprogram.py
という名前のファイルについて考えてみます。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
-h
または--help
がコマンドラインで指定されている場合、ArgumentParserヘルプが出力されます。
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
場合によっては、このヘルプオプションの追加を無効にすると便利なことがあります。 これは、False
をadd_help=
引数として ArgumentParser に渡すことで実現できます。
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]
optional arguments:
--foo FOO foo help
ヘルプオプションは通常-h/--help
です。 これの例外は、prefix_chars=
が指定されていて、-
が含まれていない場合です。この場合、-h
および--help
は有効なオプションではありません。 この場合、prefix_chars
の最初の文字は、ヘルプオプションのプレフィックスとして使用されます。
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]
optional arguments:
+h, ++help show this help message and exit
16.4.3。 add_argument()メソッド
- ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])
- 単一のコマンドライン引数を解析する方法を定義します。 各パラメータには、以下に独自の詳細な説明がありますが、簡単に言うと次のとおりです。
- nameまたはflags -名前またはオプション文字列のリスト。例:
foo
または-f, --foo
。 - action -この引数がコマンドラインで検出されたときに実行される基本的なアクションのタイプ。
- nargs -消費する必要のあるコマンドライン引数の数。
- const -一部の action および nargs の選択に必要な定数値。
- default -引数がコマンドラインにない場合に生成される値。
- type -コマンドライン引数の変換先のタイプ。
- choices -引数の許容値のコンテナー。
- required -コマンドラインオプションを省略できるかどうか(オプションのみ)。
- help -引数の機能の簡単な説明。
- metavar -使用法メッセージの引数の名前。
- dest - parse_args()によって返されるオブジェクトに追加される属性の名前。
- nameまたはflags -名前またはオプション文字列のリスト。例:
次のセクションでは、これらのそれぞれの使用方法について説明します。
16.4.3.1。 名前またはフラグ
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
16.4.3.2。 アクション
ArgumentParser オブジェクトは、コマンドライン引数をアクションに関連付けます。 ほとんどのアクションは、 parse_args()によって返されるオブジェクトに属性を追加するだけですが、これらのアクションは、それらに関連付けられたコマンドライン引数を使用してほぼすべてを実行できます。 action
キーワード引数は、コマンドライン引数の処理方法を指定します。 提供されるアクションは次のとおりです。
'store'
-これは引数の値を格納するだけです。 これがデフォルトのアクションです。 例えば:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo') >>> parser.parse_args('--foo 1'.split()) Namespace(foo='1')
'store_const'
-これは、 const キーワード引数で指定された値を格納します。'store_const'
アクションは、ある種のフラグを指定するオプションの引数とともに最も一般的に使用されます。 例えば:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='store_const', const=42) >>> parser.parse_args(['--foo']) Namespace(foo=42)
'store_true'
および'store_false'
-これらは、値True
およびFalse
をそれぞれ格納するために使用される'store_const'
の特殊なケースです。 さらに、それぞれFalse
とTrue
のデフォルト値を作成します。 例えば:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='store_true') >>> parser.add_argument('--bar', action='store_false') >>> parser.add_argument('--baz', action='store_false') >>> parser.parse_args('--foo --bar'.split()) Namespace(foo=True, bar=False, baz=True)
'append'
-これはリストを格納し、各引数値をリストに追加します。 これは、オプションを複数回指定できるようにする場合に便利です。 使用例:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='append') >>> parser.parse_args('--foo 1 --foo 2'.split()) Namespace(foo=['1', '2'])
'append_const'
-これはリストを格納し、 const キーワード引数で指定された値をリストに追加します。 ( const キーワード引数のデフォルトはNone
であることに注意してください。)'append_const'
アクションは通常、複数の引数が定数を同じリストに格納する必要がある場合に役立ちます。 例えば:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--str', dest='types', action='append_const', const=str) >>> parser.add_argument('--int', dest='types', action='append_const', const=int) >>> parser.parse_args('--str --int'.split()) Namespace(types=[<class 'str'>, <class 'int'>])
'count'
-これは、キーワード引数が発生する回数をカウントします。 たとえば、これは詳細レベルを上げるのに役立ちます。>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--verbose', '-v', action='count') >>> parser.parse_args(['-vvv']) Namespace(verbose=3)
'help'
-これは、現在のパーサーのすべてのオプションの完全なヘルプメッセージを出力して、終了します。 デフォルトでは、ヘルプアクションがパーサーに自動的に追加されます。 出力の作成方法の詳細については、 ArgumentParser を参照してください。'version'
-これは、 add_argument()呼び出しでversion=
キーワード引数を予期し、バージョン情報を出力して、呼び出されると終了します。>>> 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サブクラスまたは他のオブジェクトを渡すことにより、任意のアクションを指定することもできます。 これを行うための推奨される方法は、アクションを拡張して、__call__
メソッドとオプションで__init__
メソッドをオーバーライドすることです。
カスタムアクションの例:
>>> class FooAction(argparse.Action):
... def __init__(self, option_strings, dest, nargs=None, **kwargs):
... if nargs is not None:
... raise ValueError("nargs not allowed")
... super(FooAction, self).__init__(option_strings, dest, **kwargs)
... def __call__(self, parser, namespace, values, option_string=None):
... print('%r %r %r' % (namespace, values, option_string))
... setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')
詳細については、アクションを参照してください。
16.4.3.3。 nargs
ArgumentParserオブジェクトは通常、単一のコマンドライン引数を実行する単一のアクションに関連付けます。 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つの引数がコマンドラインから消費され、単一のアイテムとして生成されます。 コマンドライン引数が存在しない場合、 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
argparse.REMAINDER
。 残りのすべてのコマンドライン引数はリストにまとめられます。 これは通常、他のコマンドラインユーティリティにディスパッチするコマンドラインユーティリティで役立ちます。>>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('--foo') >>> parser.add_argument('command') >>> parser.add_argument('args', nargs=argparse.REMAINDER) >>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())) Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
nargs
キーワード引数が指定されていない場合、消費される引数の数は action によって決定されます。 通常、これは、単一のコマンドライン引数が消費され、単一の項目(リストではない)が生成されることを意味します。
16.4.3.4。 const
add_argument()のconst
引数は、コマンドラインから読み取られないが、さまざまな ArgumentParser アクションに必要な定数値を保持するために使用されます。 それの2つの最も一般的な使用法は次のとおりです。
- add_argument()が
action='store_const'
またはaction='append_const'
で呼び出されたとき。 これらのアクションは、 parse_args()によって返されるオブジェクトの属性の1つにconst
値を追加します。 例については、 action の説明を参照してください。 - add_argument()がオプション文字列(
-f
または--foo
など)およびnargs='?'
で呼び出された場合。 これにより、オプションの引数が作成され、その後に0個または1個のコマンドライン引数を続けることができます。 コマンドラインを解析するときに、コマンドライン引数が後に続くオプション文字列が検出された場合、代わりにconst
の値が想定されます。 例については、 nargs の説明を参照してください。
'store_const'
および'append_const'
アクションでは、const
キーワード引数を指定する必要があります。 その他のアクションの場合、デフォルトでNone
になります。
16.4.3.5。 ディフォルト
コマンドラインでは、すべてのオプションの引数と一部の位置引数を省略できます。 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)
default
値が文字列の場合、パーサーは値をコマンドライン引数であるかのように解析します。 特に、パーサーは、名前空間の戻り値に属性を設定する前に、 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')
16.4.3.6。 タイプ
デフォルトでは、 ArgumentParser オブジェクトは、コマンドライン引数を単純な文字列として読み取ります。 ただし、コマンドライン文字列は、代わりに float や int などの別のタイプとして解釈されることがよくあります。 add_argument()のtype
キーワード引数を使用すると、必要な型チェックと型変換を実行できます。 一般的な組み込みの型と関数は、type
引数の値として直接使用できます。
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=open)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)
type
引数がデフォルトの引数にいつ適用されるかについては、 default キーワード引数のセクションを参照してください。
さまざまなタイプのファイルの使用を容易にするために、argparseモジュールはファクトリFileTypeを提供します。これは、mode=
、bufsize=
、encoding=
、およびerrors=
引数を取ります。 open()関数。 たとえば、FileType('w')
を使用して、書き込み可能なファイルを作成できます。
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)
type=
は、単一の文字列引数を取り、変換された値を返す任意の呼び出し可能オブジェクトを受け取ることができます。
>>> def perfect_square(string):
... value = int(string)
... sqrt = math.sqrt(value)
... if sqrt != int(sqrt):
... msg = "%r is not a perfect square" % string
... raise argparse.ArgumentTypeError(msg)
... return value
...
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=perfect_square)
>>> parser.parse_args(['9'])
Namespace(foo=9)
>>> parser.parse_args(['7'])
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square
choices キーワード引数は、値の範囲を単純にチェックする型チェッカーにとってより便利な場合があります。
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=range(5, 10))
>>> parser.parse_args(['7'])
Namespace(foo=7)
>>> parser.parse_args(['11'])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
詳細については、選択肢セクションを参照してください。
16.4.3.7。 選択肢
一部のコマンドライン引数は、制限された値のセットから選択する必要があります。 これらは、コンテナオブジェクトを choices キーワード引数として add_argument()に渡すことで処理できます。 コマンドラインが解析されると、引数の値がチェックされ、引数が許容値の1つではなかった場合は、エラーメッセージが表示されます。
>>> 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)
in
演算子をサポートするオブジェクトは、 choices 値として渡すことができるため、 dict オブジェクト、 set オブジェクト、カスタムコンテナなどがあります。 すべてサポートされています。
16.4.3.8。 必要
一般に、 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()はエラーを報告します。
ノート
ユーザーはオプションがオプションであると期待しているため、必須オプションは一般に不適切な形式と見なされます。したがって、可能な場合は避ける必要があります。
16.4.3.9。 ヘルプ
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
optional arguments:
-h, --help show this help message and exit
--foo foo the bars before frobbling
help
文字列には、プログラム名や引数 default などの繰り返しを避けるために、さまざまな形式指定子を含めることができます。 使用可能な指定子には、プログラム名、%(prog)s
、および add_argument()へのほとんどのキーワード引数が含まれます。 %(default)s
、%(type)s
など:
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
... help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]
positional arguments:
bar the bar to frobble (default: 42)
optional arguments:
-h, --help show this help message and exit
ヘルプ文字列は%-f ormattingをサポートしているため、リテラル%
をヘルプ文字列に表示する場合は、%%
としてエスケープする必要があります。
argparse は、help
値をargparse.SUPPRESS
に設定することにより、特定のオプションのヘルプエントリのサイレンシングをサポートします。
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]
optional arguments:
-h, --help show this help message and exit
16.4.3.10。 metavar
ArgumentParser がヘルプメッセージを生成する場合、予想される各引数を参照するための何らかの方法が必要です。 デフォルトでは、ArgumentParserオブジェクトは dest 値を各オブジェクトの「名前」として使用します。 デフォルトでは、位置引数アクションの場合、 dest 値が直接使用され、オプションの引数アクションの場合、 dest 値は大文字になります。 したがって、dest='bar'
を使用した単一の位置引数は、bar
と呼ばれます。 単一のコマンドライン引数が後に続く必要がある単一のオプションの引数--foo
は、FOO
と呼ばれます。 例:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage: [-h] [--foo FOO] bar
positional arguments:
bar
optional arguments:
-h, --help show this help message and exit
--foo FOO
別名はmetavar
で指定できます。
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage: [-h] [--foo YYY] XXX
positional arguments:
XXX
optional arguments:
-h, --help show this help message and exit
--foo YYY
metavar
は displayed 名のみを変更することに注意してください- parse_args()オブジェクトの属性の名前は、 dest 値によって決定されます。
nargs
の値が異なると、メタ変数が複数回使用される可能性があります。 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
16.4.3.11。 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')
16.4.3.12。 アクションクラス
アクションクラスは、コマンドラインから引数を処理するcallableを返すcallableであるActionAPIを実装します。 この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)
アクションオブジェクトは、コマンドラインの1つ以上の文字列から単一の引数を解析するために必要な情報を表すためにArgumentParserによって使用されます。 Actionクラスは、action
自体を除いて、2つの位置引数と ArgumentParser.add_argument()に渡されるキーワード引数を受け入れる必要があります。
アクションのインスタンス(またはaction
パラメーターへの呼び出し可能な戻り値)には、属性「dest」、「option_strings」、「default」、「type」、「required」、「help」などが必要です。 定義されています。 これらの属性が定義されていることを確認する最も簡単な方法は、Action.__init__
を呼び出すことです。
アクションインスタンスは呼び出し可能である必要があるため、サブクラスは__call__
メソッドをオーバーライドする必要があります。このメソッドは、次の4つのパラメーターを受け入れる必要があります。
parser
-このアクションを含むArgumentParserオブジェクト。namespace
- parse_args()によって返される Namespace オブジェクト。 ほとんどのアクションは、 setattr()を使用してこのオブジェクトに属性を追加します。values
-関連するコマンドライン引数。型変換が適用されています。 型変換は、 add_argument()への type キーワード引数で指定されます。option_string
-このアクションを呼び出すために使用されたオプション文字列。option_string
引数はオプションであり、アクションが位置引数に関連付けられている場合は存在しません。
__call__
メソッドは任意のアクションを実行できますが、通常はdest
およびvalues
に基づいてnamespace
に属性を設定します。
16.4.4。 parse_args()メソッド
- ArgumentParser.parse_args(args=None, namespace=None)
引数文字列をオブジェクトに変換し、名前空間の属性として割り当てます。 入力された名前空間を返します。
add_argument()への以前の呼び出しは、作成されるオブジェクトとそれらがどのように割り当てられるかを正確に決定します。 詳細については、 add_argument()のドキュメントを参照してください。
16.4.4.1。 オプション値の構文
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文字より長いオプション)の場合、オプションと値は、=
を使用してそれらを区切ることにより、単一のコマンドライン引数として渡すこともできます。
>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)
短いオプション(1文字の長さのオプションのみ)の場合、オプションとその値を連結できます。
>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')
最後のオプションのみ(またはそれらのいずれも)が値を必要としない限り、単一の-
プレフィックスのみを使用して、いくつかの短いオプションを結合できます。
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')
16.4.4.2。 無効な引数
コマンドラインの解析中に、 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
16.4.4.3。 を含む引数-
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)
16.4.4.4。 引数の省略形(プレフィックス一致)
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
に設定することで無効にできます。
16.4.4.5。 下sys.argv
sys.argv の引数以外の引数をArgumentParserで解析すると便利な場合があります。 これは、文字列のリストを 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])
16.4.4.6。 名前空間オブジェクト
- class argparse.Namespace
- parse_args()がデフォルトで使用する単純なクラスで、属性を保持するオブジェクトを作成して返します。
このクラスは意図的に単純で、読み取り可能な文字列表現を持つ object サブクラスにすぎません。 属性をdictのように表示したい場合は、標準のPythonイディオム vars()を使用できます。
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}
また、新しい名前空間オブジェクトではなく、 ArgumentParser に既存のオブジェクトに属性を割り当てさせると便利な場合があります。 これは、namespace=
キーワード引数を指定することで実現できます。
>>> class C:
... pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'
16.4.5。 その他のユーティリティ
16.4.5.1。 サブコマンド
- ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_string][, dest][, help][, metavar])
多くのプログラムは、機能をいくつかのサブコマンドに分割します。たとえば、
svn
プログラムは、svn checkout
、svn update
、 [などのサブコマンドを呼び出すことができます。 X168X]。 プログラムがさまざまな種類のコマンドライン引数を必要とするいくつかの異なる機能を実行する場合、この方法で機能を分割することは特に良い考えです。 ArgumentParser は、 add_subparsers()メソッドを使用したこのようなサブコマンドの作成をサポートします。 add_subparsers()メソッドは通常、引数なしで呼び出され、特別なアクションオブジェクトを返します。 このオブジェクトには、コマンド名と ArgumentParser コンストラクター引数を受け取り、通常どおり変更できる ArgumentParser オブジェクトを返す単一のメソッドadd_parser()
があります。パラメータの説明:
title-ヘルプ出力のサブパーサーグループのタイトル。 説明が提供されている場合はデフォルトで「サブコマンド」、それ以外の場合は位置引数にタイトルを使用します
description-ヘルプ出力のサブパーサーグループの説明。デフォルトでは
None
prog-サブコマンドヘルプで表示される使用法情報。デフォルトでは、プログラムの名前とサブパーサー引数の前の位置引数。
parser_class-サブパーサーインスタンスを作成するために使用されるクラス。デフォルトでは、現在のパーサーのクラス(例: ArgumentParser)
action -この引数がコマンドラインで検出されたときに実行される基本的なアクションのタイプ
dest -サブコマンド名が保存される属性の名前。 デフォルトでは
None
であり、値は保存されません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
属性のみが存在します。同様に、サブパーサーからヘルプメッセージが要求されると、その特定のパーサーのヘルプのみが出力されます。 ヘルプメッセージには、親パーサーまたは兄弟パーサーメッセージは含まれません。 (ただし、各サブパーサーコマンドのヘルプメッセージは、上記のように
help=
引数をadd_parser()
に指定することで表示できます。)>>> parser.parse_args(['--help']) usage: PROG [-h] [--foo] {a,b} ... positional arguments: {a,b} sub-command help a a help b b help optional arguments: -h, --help show this help message and exit --foo foo help >>> parser.parse_args(['a', '--help']) usage: PROG a [-h] bar positional arguments: bar bar help optional arguments: -h, --help show this help message and exit >>> parser.parse_args(['b', '--help']) usage: PROG b [-h] [--baz {X,Y,Z}] optional arguments: -h, --help show this help message and exit --baz {X,Y,Z} baz help
add_subparsers()メソッドは、
title
およびdescription
キーワード引数もサポートします。 いずれかが存在する場合、サブパーサーのコマンドはヘルプ出力の独自のグループに表示されます。 例えば:>>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers(title='subcommands', ... description='valid subcommands', ... help='additional help') >>> subparsers.add_parser('foo') >>> subparsers.add_parser('bar') >>> parser.parse_args(['-h']) usage: [-h] {foo,bar} ... optional arguments: -h, --help show this help message and exit subcommands: valid subcommands {foo,bar} additional help
さらに、
add_parser
は、追加のaliases
引数をサポートします。これにより、複数の文字列が同じサブパーサーを参照できるようになります。 この例は、svn
のように、checkout
の省略形としてco
をエイリアスします。>>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers() >>> checkout = subparsers.add_parser('checkout', aliases=['co']) >>> checkout.add_argument('foo') >>> parser.parse_args(['co', 'bar']) Namespace(foo='bar')
サブコマンドを処理する特に効果的な方法の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')
16.4.5.2。 FileTypeオブジェクト
- class argparse.FileType(mode='r', bufsize=- 1, encoding=None, errors=None)
FileType ファクトリは、 ArgumentParser.add_argument()のtype引数に渡すことができるオブジェクトを作成します。 タイプとして FileType オブジェクトを持つ引数は、要求されたモード、バッファサイズ、エンコーディング、およびエラー処理を備えたファイルとしてコマンドライン引数を開きます(詳細については、 open()関数を参照してください)。 )::
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--raw', type=argparse.FileType('wb', 0)) >>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8')) >>> parser.parse_args(['--raw', 'raw.dat', 'file.txt']) Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)
FileTypeオブジェクトは、疑似引数
'-'
を理解し、これを読み取り可能な FileType オブジェクトの場合はsys.stdin
に、書き込み可能な FileType の場合はsys.stdout
に自動的に変換します。オブジェクト:>>> parser = argparse.ArgumentParser() >>> parser.add_argument('infile', type=argparse.FileType('r')) >>> parser.parse_args(['-']) Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)
バージョン3.4の新機能: エンコーディングおよびエラーキーワード引数。
16.4.5.3。 引数グループ
- 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
ユーザー定義グループにない引数は、通常の「位置引数」セクションと「オプション引数」セクションに戻ることに注意してください。
16.4.5.4。 相互排除
- 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 引数も受け入れ、相互に排他的な引数の少なくとも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
現在、相互に排他的な引数グループは、 add_argument_group()の title および description 引数をサポートしていないことに注意してください。
16.4.5.5。 パーサーのデフォルト
- ArgumentParser.set_defaults(**kwargs)
ほとんどの場合、 parse_args()によって返されるオブジェクトの属性は、コマンドライン引数と引数アクションを調べることによって完全に決定されます。 set_defaults()を使用すると、コマンドラインを検査せずに決定されたいくつかの追加属性を追加できます。
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('foo', type=int) >>> parser.set_defaults(bar=42, baz='badger') >>> parser.parse_args(['736']) Namespace(bar=42, baz='badger', foo=736)
パーサーレベルのデフォルトは常に引数レベルのデフォルトをオーバーライドすることに注意してください。
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default='bar') >>> parser.set_defaults(foo='spam') >>> parser.parse_args([]) Namespace(foo='spam')
パーサーレベルのデフォルトは、複数のパーサーを操作するときに特に役立ちます。 このタイプの例については、 add_subparsers()メソッドを参照してください。
- ArgumentParser.get_default(dest)
add_argument()または set_defaults()のいずれかによって設定された、名前空間属性のデフォルト値を取得します。
>>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default='badger') >>> parser.get_default('foo') 'badger'
16.4.5.6。 印刷ヘルプ
最も一般的なアプリケーションでは、 parse_args()が使用法やエラーメッセージのフォーマットと印刷を処理します。 ただし、いくつかのフォーマット方法を使用できます。
- ArgumentParser.print_usage(file=None)
- ArgumentParser をコマンドラインで呼び出す方法の簡単な説明を出力します。 ファイルが
None
の場合、 sys.stdout が想定されます。
- ArgumentParser.print_help(file=None)
- プログラムの使用法と ArgumentParser に登録されている引数に関する情報を含むヘルプメッセージを出力します。 ファイルが
None
の場合、 sys.stdout が想定されます。
文字列を出力する代わりに単に文字列を返すこれらのメソッドのバリエーションもあります。
- ArgumentParser.format_usage()
- コマンドラインで ArgumentParser を呼び出す方法の簡単な説明を含む文字列を返します。
- ArgumentParser.format_help()
- プログラムの使用法や ArgumentParser に登録されている引数に関する情報を含むヘルプメッセージを含む文字列を返します。
16.4.5.7。 部分的な解析
- ArgumentParser.parse_known_args(args=None, namespace=None)
スクリプトがコマンドライン引数の一部のみを解析し、残りの引数を別のスクリプトまたはプログラムに渡す場合があります。 このような場合、 parse_known_args()メソッドが役立ちます。 parse_args()とほとんど同じように機能しますが、追加の引数が存在する場合にエラーが発生しない点が異なります。 代わりに、入力された名前空間と残りの引数文字列のリストを含む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()
に適用されます。 パーサーは、既知のオプションの1つのプレフィックスである場合でも、残りの引数リストに残すのではなく、オプションを消費する場合があります。
16.4.5.8。 ファイル解析のカスタマイズ
- ArgumentParser.convert_arg_line_to_args(arg_line)
ファイルから読み取られる引数( fromfile_prefix_chars キーワード引数から ArgumentParser コンストラクターを参照)は、1行に1つの引数が読み取られます。 convert_arg_line_to_args()は、読みやすくするためにオーバーライドできます。
このメソッドは、引数ファイルから読み取られた文字列である単一の引数 arg_line を取ります。 この文字列から解析された引数のリストを返します。 このメソッドは、引数ファイルから読み取られた行ごとに1回ずつ呼び出されます。
このメソッドの便利なオーバーライドは、スペースで区切られた各単語を引数として扱うメソッドです。 次の例は、これを行う方法を示しています。
class MyArgumentParser(argparse.ArgumentParser): def convert_arg_line_to_args(self, arg_line): return arg_line.split()
16.4.5.9。 終了メソッド
- ArgumentParser.exit(status=0, message=None)
- このメソッドはプログラムを終了し、指定された status で終了し、指定されている場合は、その前にメッセージを出力します。
- ArgumentParser.error(message)
- このメソッドは、メッセージを含む使用法メッセージを標準エラーに出力し、ステータスコード2でプログラムを終了します。
16.4.6。 optparseコードのアップグレード
元々、 argparse モジュールは、 optparse との互換性を維持しようとしていました。 ただし、 optparse を透過的に拡張することは困難でした。特に、新しいnargs=
指定子とより適切な使用法メッセージをサポートするために必要な変更がありました。 optparse のほとんどすべてがコピー貼り付けまたはモンキーパッチのいずれかであった場合、下位互換性を維持しようとすることはもはや実用的ではないように思われました。
argparse モジュールは、標準ライブラリ optparse モジュールを、次のような多くの点で改善しています。
- 位置引数の処理。
- サブコマンドのサポート。
+
や/
などの代替オプションプレフィックスを許可します。- ゼロ以上および1つ以上のスタイル引数の処理。
- より有益な使用法メッセージを作成します。
- カスタム
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()を、位置引数の
nargs
を argparse.REMAINDER に設定するか、 parse_known_args()を使用して収集します。別のリストにある未解析の引数文字列。 - コールバックアクションと
callback_*
キーワード引数をtype
またはaction
引数に置き換えます。 type
キーワード引数の文字列名を、対応するタイプオブジェクトに置き換えます(例: int、float、complexなど)。optparse.Values
を名前空間およびoptparse.OptionError
に、optparse.OptionValueError
をArgumentError
に置き換えます。- 文字列を
%default
や%prog
などの暗黙の引数で標準のPython構文に置き換えて、辞書を使用して文字列をフォーマットします。つまり、%(default)s
と%(prog)s
です。 - OptionParserコンストラクター
version
引数をparser.add_argument('--version', action='version', version='<the version>')
の呼び出しに置き換えます。