`argparse` --- コマンドラインオプション、引数、サブコマンドのパーサー¶

バージョン 3.2 で追加.

ソースコード: Lib/argparse.py

argparse モジュールは、ユーザーフレンドリーなコマンドラインインターフェースの作成を簡単にします。プログラムは必要とする引数が何かを定義し、 argparse は sys.argv からそれらの引数を解析する方法を見つけ出します。また、 argparse モジュールはヘルプや使用方法のメッセージを自動的に生成します。さらに、このモジュールはユーザーが不正な引数をプログラムに与えた場合にエラーを発生させます。

中核的な機能¶

argparse モジュールのコマンドラインインターフェースのサポートは、 argparse.ArgumentParser のインスタンスを中心として構築されています。これは引数の仕様に対するコンテナであり、引数解析器（パーサー）全体に適用されるオプションを持っています:

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

ArgumentParser.add_argument() メソッドは各引数の仕様をパーサーに付属させます。このメソッドは位置引数、値を受け取るオプション、機能のオン／オフを切り替えるフラグをサポートします:

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

ArgumentParser.parse_args() メソッドはパーサーを実行し、抽出したデータを argparse.Namespace オブジェクト内に配置します:

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

add_argument() のためのクイックリンク¶

名前	説明	値
action	引数をどのように処理するかを指定します	`'store'`, `'store_const'`, `'store_true'`, `'append'`, `'append_const'`, `'count'`, `'help'`, `'version'`
choices	特定の選択肢に値を制限します	`['foo', 'bar']`, `range(1, 10)`, または `Container` インスタンス
const	定数値を保存します
default	引数が指定されなかったときに使われるデフォルト値です	特に指定がない場合は `None` となります
dest	引数解析結果の名前空間で使われる属性名を指定します
help	引数のためのヘルプメッセージです
metavar	ヘルプで表示される、引数の代わりの名前です
nargs	引数として受け取ることのできる数です	`int`, `'?'`, `'*'`, または `'+'`
required	その引数が必須か、オプションかを指定します	`True` または `False`
type	引数を与えられた型に自動的に変換します	`int`, `float`, `argparse.FileType('w')`, または呼び出し可能な関数

使用例¶

次のコードは、整数のリストを受け取って合計か最大値を返す 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', encoding=sys.getfilesystemencoding()) as fp:
...     fp.write('-f\nbar')
...
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')

ファイルから読み込まれる引数は、デフォルトでは1行に1つ (ただし、convert_arg_line_to_args() も参照してください) で、コマンドライン上でファイルを参照する引数があった場所にその引数があったものとして扱われます。このため、上の例では、['-f', 'foo', '@args.txt'] は ['-f', 'foo', '-f', 'bar'] と等価になります。

ArgumentParser uses filesystem encoding and error handler to read the file containing arguments.

fromfile_prefix_chars= 引数のデフォルト値は None で、引数がファイル参照として扱われることがないことを意味しています。

バージョン 3.12 で変更: ArgumentParser changed encoding and errors to read arguments files from default (e.g. locale.getpreferredencoding(False) and "strict") to filesystem encoding and error handler. Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.

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][, deprecated])¶

1つのコマンドライン引数がどう解析されるかを定義します。各引数についての詳細は後述しますが、簡単に言うと:

name または flags - 名前か、あるいはオプション文字列のリスト (例: foo や -f, --foo)。
action - コマンドラインにこの引数があったときのアクション。
nargs - 受け取るべきコマンドライン引数の数。
const - 一部の action と nargs の組み合わせで利用される定数。
default - コマンドラインに対応する引数が存在せず、さらに namespace オブジェクトにも存在しない場合に利用される値。
type - コマンドライン引数が変換されるべき型。
choices - 引数として許される値のシーケンス。
required - コマンドラインオプションが省略可能かどうか (オプション引数のみ)。
help - 引数が何なのかを示す簡潔な説明。
metavar - 使用法メッセージの中で使われる引数の名前。
dest - parse_args() が返すオブジェクトに追加される属性名。
deprecated - Whether or not use of the argument is deprecated.

以下の節では各オプションの利用方法を説明します。

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 オブジェクトは通常1つのコマンドライン引数を1つのアクションに渡します。nargs キーワード引数は1つのアクションにそれ以外の数のコマンドライン引数を割り当てます。多義性のある引数の指定を参照してください。指定できる値は:

N (整数) -- N 個の引数がコマンドラインから集められ、リストに格納されます。例えば:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2)
>>> parser.add_argument('bar', nargs=1)
>>> parser.parse_args('c --foo a b'.split())
Namespace(bar=['c'], foo=['a', 'b'])
```
nargs=1 は1要素のリストを作ることに注意してください。これはデフォルトの、要素がそのまま属性になる動作とは異なります。

'?' -- 可能なら1つの引数がコマンドラインから取られ、1つのアイテムを作ります。コマンドライン引数が存在しない場合、default の値が生成されます。オプション引数の場合、さらにオプション引数が指定され、その後にコマンドライン引数がないというケースもありえます。この場合は const の値が生成されます。この動作の例です:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> parser.add_argument('bar', nargs='?', default='d')
>>> parser.parse_args(['XX', '--foo', 'YY'])
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 オブジェクト、 class: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')

deprecated¶

During a project's lifetime, some arguments may need to be removed from the command line. Before removing them, you should inform your users that the arguments are deprecated and will be removed. The deprecated keyword argument of add_argument(), which defaults to False, specifies if the argument is deprecated and will be removed in the future. For arguments, if deprecated is True, then a warning will be printed to standard error when the argument is used:

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

バージョン 3.13 で変更.

Action クラス¶

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() のドキュメントを参照してください。

args - 解析する文字列のリスト。デフォルトでは sys.argv から取得されます。
namespace - 属性を代入するオブジェクト。デフォルトでは、新しい空の Namespace オブジェクトです。

オプション値の文法¶

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)

See also the argparse howto on ambiguous arguments for more details.

引数の短縮形 (先頭文字でのマッチング)¶

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 additional aliases argument, which allows multiple strings to refer to the same subparser. This example, like svn, aliases co as a shorthand for checkout:

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

add_parser() supports also an additional deprecated argument, which allows to deprecate the subparser.

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

バージョン 3.13 で追加.

サブコマンドを扱う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(). However, a mutually exclusive group can be added to an argument group that has a title and description. For example:

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

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

Group title:
  Group description

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

バージョン 3.11 で変更: 相互排他グループについて add_argument_group() や add_mutually_exclusive_group() を呼び出すことは非推奨です。これらの機能はこれまで一度もサポートされたことがなく、常に正しく動作するとは限りません。これらの関数は継承により偶然 API に存在することになったもので、将来削除される予定です。

パーサーのデフォルト値¶

ArgumentParser.set_defaults(**kwargs)¶

ほとんどの場合、 parse_args() が返すオブジェクトの属性はコマンドライン引数の内容と引数のアクションによってのみ決定されます。 set_defaults() を使うと与えられたコマンドライン引数の内容によらず追加の属性を決定することが可能です:

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

パーサーレベルのデフォルト値は常に引数レベルのデフォルト値を上書きします:

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

パーサーレベルの 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¶: コマンドラインの文字列を、指定された型に変換するのに失敗した時に送出されます。

argparse --- コマンドラインオプション、引数、サブコマンドのパーサー¶