"argparse" --- Parser for command-line options, arguments and sub-commands
**************************************************************************

バージョン 3.2 で追加.

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

======================================================================


チュートリアル
^^^^^^^^^^^^^^

このページは API のリファレンス情報が記載しています。argparse チュート
リアル では、コマンドラインの解析についてより優しく説明しています。

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


中核的な機能
============

The "argparse" module's support for command-line interfaces is built
around an instance of "argparse.ArgumentParser".  It is a container
for argument specifications and has options that apply the parser as
whole:

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

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

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

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

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


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

+------------------------+-------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| 名前                   | 説明                                                        | 値                                                                                                                         |
|========================|=============================================================|============================================================================================================================|
| 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') as fp:
   ...     fp.write('-f\nbar')
   >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
   >>> parser.add_argument('-f')
   >>> parser.parse_args(['-f', 'foo', '@args.txt'])
   Namespace(f='bar')

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

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


argument_default
----------------

一般的には、引数のデフォルト値は "add_argument()" メソッドにデフォルト
値を渡すか、"set_defaults()" メソッドに名前と値のペアを渡すことで指定
します。しかしまれに、1つのパーサー全体に適用されるデフォルト引数が便
利なことがあります。これを行うには、 "ArgumentParser" に
"argument_default=" キーワード引数を渡します。例えば、全体で
"parse_args()" メソッド呼び出しの属性の生成を抑制するには、
"argument_default=SUPPRESS" を指定します:

   >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('bar', nargs='?')
   >>> parser.parse_args(['--foo', '1', 'BAR'])
   Namespace(bar='BAR', foo='1')
   >>> parser.parse_args([])
   Namespace()


allow_abbrev
------------

通常、"ArgumentParser" の "parse_args()" に引数のリストを渡すとき、長
いオプションは 短縮しても認識されます。

この機能は、"allow_abbrev" に "False" を指定することで無効にできます:

   >>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
   >>> parser.add_argument('--foobar', action='store_true')
   >>> parser.add_argument('--foonley', action='store_false')
   >>> parser.parse_args(['--foon'])
   usage: PROG [-h] [--foobar] [--foonley]
   PROG: error: unrecognized arguments: --foon

バージョン 3.5 で追加.


conflict_handler
----------------

"ArgumentParser" オブジェクトは同じオプション文字列に対して複数のアク
ションを許可していません。 デフォルトでは、"ArgumentParser" オブジェク
トは、すでに利用されているオプション文字列を使って新しい引数をつくろう
としたときに例外を送出します:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-f', '--foo', help='old foo help')
   >>> parser.add_argument('--foo', help='new foo help')
   Traceback (most recent call last):
    ..
   ArgumentError: argument --foo: conflicting option string(s): --foo

ときどき (例えば parents を利用する場合など)、古い引数を同じオプション
文字列で上書きするほうが便利な場合があります。この動作をするには、
"ArgumentParser" の "conflict_handler=" 引数に "'resolve'" を渡します:

   >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
   >>> parser.add_argument('-f', '--foo', help='old foo help')
   >>> parser.add_argument('--foo', help='new foo help')
   >>> parser.print_help()
   usage: PROG [-h] [-f FOO] [--foo FOO]

   options:
    -h, --help  show this help message and exit
    -f FOO      old foo help
    --foo FOO   new foo help

"ArgumentParser" オブジェクトは、すべてのオプション文字列が上書きされ
た場合にだけアクションを削除することに注目してください。上の例では、 "
--foo" オプション文字列だけが上書きされているので、古い "-f/--foo" ア
クションは "-f" アクションとして残っています。


add_help
--------

デフォルトでは、ArgumentParser オブジェクトはシンプルにパーサーのヘル
プメッセージを表示するオプションを自動的に追加します。例えば、以下のコ
ードを含む "myprogram.py" ファイルについて考えてください:

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

コマンドラインに "-h" か "--help" が指定された場合、ArgumentParser の
help が表示されます:

   $ python myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

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

必要に応じて、この help オプションを無効にする場合があります。これは
"ArgumentParser" の "add_help=" 引数に "False" を渡すことで可能です:

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

   options:
    --foo FOO  foo help

ヘルプオプションは通常 "-h/--help" です。例外は "prefix_chars=" が指定
されてその中に "-" が無かった場合で、その場合は "-h" と "--help" は有
効なオプションではありません。この場合、"prefix_chars" の最初の文字が
ヘルプオプションの接頭辞として利用されます:

   >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
   >>> parser.print_help()
   usage: PROG [+h]

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


exit_on_error
-------------

通常、不正な引数リストが "ArgumentParser" の "parse_args()" メソッドに
渡された場合、プログラムはエラー情報を出力して終了します。

もしエラーを例外としてプログラム内でキャッチしたい場合は、
"exit_on_error" を "False" に設定してください:

   >>> parser = argparse.ArgumentParser(exit_on_error=False)
   >>> parser.add_argument('--integers', type=int)
   _StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
   >>> try:
   ...     parser.parse_args('--integers a'.split())
   ... except argparse.ArgumentError:
   ...     print('Catching an argumentError')
   ...
   Catching an argumentError

バージョン 3.9 で追加.


add_argument() メソッド
=======================

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

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

   * name または flags - 名前か、あるいはオプション文字列のリスト (例:
     "foo" や "-f, --foo")。

   * action - コマンドラインにこの引数があったときのアクション。

   * nargs - 受け取るべきコマンドライン引数の数。

   * const - 一部の action と nargs の組み合わせで利用される定数。

   * default - コマンドラインに対応する引数が存在せず、さらに
     namespace オブジェクトにも存在しない場合に利用される値。

   * type - コマンドライン引数が変換されるべき型。

   * choices - 引数として許される値のシーケンス。

   * required - コマンドラインオプションが省略可能かどうか (オプション
     引数のみ)。

   * help - 引数が何なのかを示す簡潔な説明。

   * metavar - 使用法メッセージの中で使われる引数の名前。

   * dest - "parse_args()" が返すオブジェクトに追加される属性名。

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


name または flags
-----------------

"add_argument()" メソッドは、指定されている引数が "-f" や "--foo" のよ
うなオプション引数なのか、ファイル名リストなどの位置引数なのかを知る必
要があります。 そのため、 "add_argument()" に初めに渡される引数は、一
連のフラグか、単一の引数名のどちらかになります。

たとえば、オプション引数は次のように作成します:

   >>> parser.add_argument('-f', '--foo')

一方、位置引数は次のように作成します:

   >>> parser.add_argument('bar')

"parse_args()" が呼ばれたとき、オプション引数は接頭辞 "-" により識別さ
れ、それ以外の引数は位置引数として扱われます:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-f', '--foo')
   >>> parser.add_argument('bar')
   >>> parser.parse_args(['BAR'])
   Namespace(bar='BAR', foo=None)
   >>> parser.parse_args(['BAR', '--foo', 'FOO'])
   Namespace(bar='BAR', foo='FOO')
   >>> parser.parse_args(['--foo', 'FOO'])
   usage: PROG [-h] [-f FOO] bar
   PROG: error: the following arguments are required: bar


action
------

"ArgumentParser" オブジェクトはコマンドライン引数にアクションを割り当
てます。このアクションは、割り当てられたコマンドライン引数に関してどん
な処理でもできますが、ほとんどのアクションは単に "parse_args()" が返す
オブジェクトに属性を追加するだけです。"action" キーワード引数は、コマ
ンドライン引数がどう処理されるかを指定します。提供されているアクション
は:

* "'store'" - これは単に引数の値を格納します。これはデフォルトのアクシ
  ョンです。例えば:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo')
     >>> parser.parse_args('--foo 1'.split())
     Namespace(foo='1')

* "'store_const'" - このアクションは const キーワード引数で指定された
  値を格納します。const キーワード引数のデフォルト値は "None" であるこ
  とに注意してください。"'store_const'" アクションは、何かの種類のフラ
  グを指定するオプション引数によく使われます。例えば:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='store_const', const=42)
     >>> parser.parse_args(['--foo'])
     Namespace(foo=42)

* "'store_true'", "'store_false'" - これらは "'store_const'" の、それ
  ぞれ "True" と "False" を格納する特別版になります。加えて、これらは
  それぞれデフォルト値を順に "False" と "True" にします。例えば:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='store_true')
     >>> parser.add_argument('--bar', action='store_false')
     >>> parser.add_argument('--baz', action='store_false')
     >>> parser.parse_args('--foo --bar'.split())
     Namespace(foo=True, bar=False, baz=True)

* "'append'" - このアクションはリストを格納し、それぞれの引数として与
  えられた値をリストに追加します。これは複数回指定可能なオプション引数
  に対して有用です。デフォルト値が空でない場合、デフォルト値は常にパー
  スされたリストに含まれ、コマンドラインで指定した値はデフォルト値の後
  に追加されます。使用例:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='append')
     >>> parser.parse_args('--foo 1 --foo 2'.split())
     Namespace(foo=['1', '2'])

* "'append_const'" - このアクションはリストを格納して、const キーワー
  ド引数に与えられた値をそのリストに追加します。const キーワード引数の
  デフォルト値は "None" であることに注意してください。"'append_const'"
  アクションは、定数を同じリストに複数回格納する場合に便利です。例えば
  :

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
     >>> parser.add_argument('--int', dest='types', action='append_const', const=int)
     >>> parser.parse_args('--str --int'.split())
     Namespace(types=[<class 'str'>, <class 'int'>])

* "'count'" - このアクションはキーワード引数の数を数えます。例えば、
  verboseレベルを上げるのに役立ちます:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--verbose', '-v', action='count', default=0)
     >>> parser.parse_args(['-vvv'])
     Namespace(verbose=3)

  *default* は明示的に *0* と指定されない場合は "None" であることに注
  意してください。

* "'help'" - このアクションは現在のパーサー中のすべてのオプションのヘ
  ルプメッセージを表示し、終了します。出力の生成方法の詳細については
  "ArgumentParser" を参照してください。

* "'version'" - このアクションは "add_argument()" の呼び出しに
  "version=" キーワード引数を期待します。指定されたときはバージョン情
  報を表示して終了します:

     >>> import argparse
     >>> parser = argparse.ArgumentParser(prog='PROG')
     >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
     >>> parser.parse_args(['--version'])
     PROG 2.0

* "'extend'" - このアクションはリストを格納して、各引数の値でそのリス
  トを拡張します。利用例:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
     >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
     Namespace(foo=['f1', 'f2', 'f3', 'f4'])

  バージョン 3.8 で追加.

また、Action のサブクラス、またはそれと同じインターフェースを実装する
オブジェクトを渡すことにより、任意のアクションを指定することができます
。例えば "argparse" モジュールには "BooleanOptionalAction" があり、"--
foo" や "--no-foo" のようなオプションに対して真偽値を設定するアクショ
ンをサポートしています:

   >>> import argparse
   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
   >>> parser.parse_args(['--no-foo'])
   Namespace(foo=False)

バージョン 3.9 で追加.

カスタムアクションを作成する推奨の方法は、"Action" クラスを継承し、
"__call__" メソッド (および、任意で "__init__" および "format_usage"
メソッド) をオーバーライドすることです。

カスタムアクションの例です:

   >>> class FooAction(argparse.Action):
   ...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
   ...         if nargs is not None:
   ...             raise ValueError("nargs not allowed")
   ...         super().__init__(option_strings, dest, **kwargs)
   ...     def __call__(self, parser, namespace, values, option_string=None):
   ...         print('%r %r %r' % (namespace, values, option_string))
   ...         setattr(namespace, self.dest, values)
   ...
   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', action=FooAction)
   >>> parser.add_argument('bar', action=FooAction)
   >>> args = parser.parse_args('1 --foo 2'.split())
   Namespace(bar=None, foo=None) '1' None
   Namespace(bar='1', foo=None) '2' '--foo'
   >>> args
   Namespace(bar='1', foo='2')

詳細は "Action" を参照してください。


nargs
-----

ArgumentParser objects usually associate a single command-line
argument with a single action to be taken.  The "nargs" keyword
argument associates a different number of command-line arguments with
a single action.  The supported values are:

* "N" (整数) -- "N" 個の引数がコマンドラインから集められ、リストに格納
  されます。例えば:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs=2)
     >>> parser.add_argument('bar', nargs=1)
     >>> parser.parse_args('c --foo a b'.split())
     Namespace(bar=['c'], foo=['a', 'b'])

  "nargs=1" は1要素のリストを作ることに注意してください。これはデフォ
  ルトの、要素がそのまま属性になる動作とは異なります。

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

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
     >>> parser.add_argument('bar', nargs='?', default='d')
     >>> parser.parse_args(['XX', '--foo', 'YY'])
     Namespace(bar='XX', foo='YY')
     >>> parser.parse_args(['XX', '--foo'])
     Namespace(bar='XX', foo='c')
     >>> parser.parse_args([])
     Namespace(bar='d', foo='d')

  "nargs='?'" のよくある利用例の1つは、入出力ファイルの指定オプション
  です:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
     ...                     default=sys.stdin)
     >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
     ...                     default=sys.stdout)
     >>> parser.parse_args(['input.txt', 'output.txt'])
     Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
               outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
     >>> parser.parse_args([])
     Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
               outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)

* "'*'" -- すべてのコマンドライン引数がリストに集められます。複数の位
  置引数が "nargs='*'" を持つことにあまり意味はありませんが、複数のオ
  プション引数が "nargs='*'" を持つことはありえます。例えば:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs='*')
     >>> parser.add_argument('--bar', nargs='*')
     >>> parser.add_argument('baz', nargs='*')
     >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
     Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

* "'+'" -- "'*'" と同じように、すべてのコマンドライン引数をリストに集
  めます。加えて、最低でも1つのコマンドライン引数が存在しない場合にエ
  ラーメッセージを生成します。例えば:

     >>> parser = argparse.ArgumentParser(prog='PROG')
     >>> parser.add_argument('foo', nargs='+')
     >>> parser.parse_args(['a', 'b'])
     Namespace(foo=['a', 'b'])
     >>> parser.parse_args([])
     usage: PROG [-h] foo [foo ...]
     PROG: error: the following arguments are required: foo

"nargs" キーワード引数が指定されない場合、受け取る引数の数は action に
よって決定されます。通常これは、1つのコマンドライン引数は1つのアイテム
になる (リストにはならない) ことを意味します。


const
-----

"add_argument()" の "const" 引数は、コマンドライン引数から読み込まれな
いけれども "ArgumentParser" のいくつかのアクションで必要とされる値のた
めに使われます。この引数のよくある2つの使用法は:

* "add_argument()" が "action='store_const'" か
  "action='append_const'" で呼び出されたとき、これらのアクションは
  "const" の値を "parse_args()" が返すオブジェクトの属性に追加します。
  サンプルは action の説明を参照してください。"const" が
  "add_argument()" に与えられなければ、"None" のデフォルト値を受け取り
  ます。

* "add_argument()" がオプション文字列 ("-f" や "--foo") と "nargs='?'"
  で呼び出された場合。この場合0個か1つのコマンドライン引数を取るオプシ
  ョン引数が作られます。オプション引数にコマンドライン引数が続かなかっ
  た場合、代わりに "const" の値が "None" であると見なされます。サンプ
  ルは nargs の説明を参照してください。

バージョン 3.11 で変更: "action='append_const'" や
"action='store_const'" の場合も含め、デフォルトでは "const=None" です
。


default
-------

すべてのオプション引数といくつかの位置引数はコマンドライン上で省略され
ることがあります。 "add_argument()" の "default" キーワード引数 (デフ
ォルト: "None") は、コマンドライン引数が存在しなかった場合に利用する値
を指定します。オプション引数では、オプション文字列がコマンドライン上に
存在しなかったときに "default" の値が利用されます:

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

対象となる namespace がすでにその属性を持っている場合、それは default
の値では上書きされません:

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

"default" の値が文字列の場合、パーサーは値をコマンドライン引数のように
解析します。具体的には、パーサーは返り値 "Namespace" の属性を設定する
前に、type 変換引数が与えられていればそれらを適用します。そうでない場
合、パーサーは値をそのまま使用します:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--length', default='10', type=int)
   >>> parser.add_argument('--width', default=10.5, type=int)
   >>> parser.parse_args()
   Namespace(length=10, width=10.5)

nargs が "?" か "*" である位置引数では、コマンドライン引数が指定されな
かった場合 "default" の値が使われます。例えば:

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

"default=argparse.SUPPRESS" を渡すと、コマンドライン引数が存在しないと
きに属性の追加をしなくなります:

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


type
----

デフォルトでは、パーサーはコマンドライン引数を単なる文字列として読み込
みます。しかし、それらの文字列を "float", "int" など別の型として扱うべ
き事がよくあります。"add_argument()" の "type" キーワード引数に指定す
る type converter により、必要な型チェックと型変換を行うことができます
。

もし type キーワードが default キーワードとともに使用された場合、
default  の値が文字列のときのみ、type converter による変換などが行われ
ます。

"type" キーワードの引数として、単一の文字列を受け取るような任意の呼び
出しオブジェクト (callable) が使用できます。もし呼び出しが
"ArgumentTypeError", "TypeError", または "ValueError" 型の例外を送出し
た場合は、parser がそれをキャッチして適切なエラーメッセージが表示され
ます。それ以外の型の例外は処理されません。

一般的なビルトインデータ型や関数を "type" 引数の値として直接指定できま
す:

   import argparse
   import pathlib

   parser = argparse.ArgumentParser()
   parser.add_argument('count', type=int)
   parser.add_argument('distance', type=float)
   parser.add_argument('street', type=ascii)
   parser.add_argument('code_point', type=ord)
   parser.add_argument('source_file', type=open)
   parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
   parser.add_argument('datapath', type=pathlib.Path)

ユーザが定義した関数も使用できます:

   >>> def hyphenated(string):
   ...     return '-'.join([word[:4] for word in string.casefold().split()])
   ...
   >>> parser = argparse.ArgumentParser()
   >>> _ = parser.add_argument('short_title', type=hyphenated)
   >>> parser.parse_args(['"The Tale of Two Cities"'])
   Namespace(short_title='"the-tale-of-two-citi')

Type converter として "bool()" 関数を使用することは推奨されません。な
ぜなら、これは空文字列を "False" に、それ以外の全てを "True" に変換し
ますが、これはおそらく望まれる動作ではないからです (訳注: 文字列
"'false'" を "False" に変換してくれたりはしません)。

一般論として、"type" キーワードに指定するものは、せいぜい上記の3種類の
例外を発生するくらいの、お手軽な変換に限るべきです。より複雑な
(interesting) エラー処理、またはリソース管理を伴うものは、引数を解析し
たあとに別個の処理として行うべきです。

たとえば、JSON または YAML からの変換は複雑なエラーケースを持つので、
"type" がサポートする以上のエラー表示を必要とするでしょう。(JSON デコ
ーダが発生しうる) "JSONDecodeError" は適切に整形されて表示されません。
また、"FileNotFoundError" が発生しても parser は何も処理しません。

また、"type" キーワードに "FileType" を指定した場合には制限があります
。ある引数に *FileType* を指定してファイルが開かれ、その後ろのどこかの
引数で処理が失敗した場合、エラーが表示されますが、開かれたファイルは自
動では close されません。これを好まない場合は、parser による引数の処理
が終わるまで待ち、その後に "with" 文などでファイルを開くのがよいでしょ
う。

なお、引数が、あらかじめ決められた値の候補のいずれかに一致するかをチェ
ックしたいだけの場合には、代わりに choices キーワードの使用を検討して
ください。


choices
-------

コマンドライン引数をいくつかの選択肢の中から選ばせたい場合があります。
これは "add_argument()" に シーケンスオブジェクトを *choices* キーワー
ド引数として渡すことで可能です。コマンドラインを解析するとき、引数の値
がチェックされ、その値が選択肢の中に含まれていない場合はエラーメッセー
ジを表示します:

   >>> parser = argparse.ArgumentParser(prog='game.py')
   >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
   >>> parser.parse_args(['rock'])
   Namespace(move='rock')
   >>> parser.parse_args(['fire'])
   usage: game.py [-h] {rock,paper,scissors}
   game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
   'paper', 'scissors')

*choices* シーケンスに含まれているかどうかのチェックは、type による型
変換が実行された後であることに注意してください。このため、*choices* シ
ーケンス中のオブジェクトの型は指定された type にマッチしている必要があ
ります:

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

任意のシーケンスを *choices* に渡すことができます。すなわち、"list" オ
ブジェクト、 "tuple" オブジェクト、カスタムシーケンスはすべてサポート
されています。

ただし、"enum.Enum" を渡すことは推奨されません。使用方法、ヘルプ、エラ
ーメッセージなどでどのように表示されるかを制御することが難いからです。

ヘルプテキストにおいて整形された choices の値は、通常 *dest* から生成
されるデフォルトの *metavar* に優先します。ユーザーは *dest* パラメー
タを目にすることがないため、この振る舞いは基本的には望ましいものです。
もしこの表示方法が望ましくない場合 (おそらく多くの選択肢がある場合など
) は、 metavar を明示的に指定してください。


required
--------

通常 "argparse" モジュールは、"-f" や "--bar" といったフラグは *任意*
の引数 (オプション引数) だと仮定し、コマンドライン上になくても良いもの
として扱います。フラグの指定を *必須* にするには、"add_argument()" の
"required=" キーワード引数に "True" を指定します:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', required=True)
   >>> parser.parse_args(['--foo', 'BAR'])
   Namespace(foo='BAR')
   >>> parser.parse_args([])
   usage: [-h] --foo FOO
   : error: the following arguments are required: --foo

上の例のように、引数が "required" と指定されると、"parse_args()" はそ
のフラグがコマンドラインに存在しないときにエラーを表示します。

注釈:

  ユーザーは、通常 *フラグ* の指定は *任意* であると認識しているため、
  必須にするのは一般的には悪いやり方で、できる限り避けるべきです。


help
----

"help" の値はその引数の簡潔な説明を含む文字列です。ユーザーが (コマン
ドライン上で "-h" か "--help" を指定するなどして) ヘルプを要求したとき
、この "help" の説明が各引数に表示されます:

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

   positional arguments:
    bar     one of the bars to be frobbled

   options:
    -h, --help  show this help message and exit
    --foo   foo the bars before frobbling

"help" 文字列には、プログラム名や引数の default などを繰り返し記述する
のを避けるためのフォーマット指定子を含めることができます。利用できる指
定子には、プログラム名 "%(prog)s" と、 "%(default)s" や "%(type)s" な
ど "add_argument()" のキーワード引数の多くが含まれます:

   >>> parser = argparse.ArgumentParser(prog='frobble')
   >>> parser.add_argument('bar', nargs='?', type=int, default=42,
   ...                     help='the bar to %(prog)s (default: %(default)s)')
   >>> parser.print_help()
   usage: frobble [-h] [bar]

   positional arguments:
    bar     the bar to frobble (default: 42)

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

ヘルプ文字列は %-フォーマットをサポートしているので、ヘルプ文字列内に
リテラル "%" を表示したい場合は "%%" のようにエスケープしなければなり
ません。

"argparse" は "help" に "argparse.SUPPRESS" を設定することで、特定のオ
プションをヘルプに表示させないことができます:

   >>> parser = argparse.ArgumentParser(prog='frobble')
   >>> parser.add_argument('--foo', help=argparse.SUPPRESS)
   >>> parser.print_help()
   usage: frobble [-h]

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


metavar
-------

"ArgumentParser" がヘルプメッセージを出力するとき、各引数に対してなん
らかの参照方法が必要です。デフォルトでは、 ArgumentParser オブジェクト
は各オブジェクトの "名前" として dest を利用します。デフォルトでは、位
置引数には dest の値をそのまま 利用し、オプション引数については dest
の値を大文字に変換して利用します。このため、1つの "dest='bar'" である
位置引数は "bar" として参照されます。 1つのオプション引数 "--foo" が1
つのコマンドライン引数を要求するときは、その引数は "FOO" として参照さ
れます。以下に例を示します:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('bar')
   >>> parser.parse_args('X --foo Y'.split())
   Namespace(bar='X', foo='Y')
   >>> parser.print_help()
   usage:  [-h] [--foo FOO] bar

   positional arguments:
    bar

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

代わりの名前を、"metavar" として指定できます:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', metavar='YYY')
   >>> parser.add_argument('bar', metavar='XXX')
   >>> parser.parse_args('X --foo Y'.split())
   Namespace(bar='X', foo='Y')
   >>> parser.print_help()
   usage:  [-h] [--foo YYY] XXX

   positional arguments:
    XXX

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

"metavar" は *表示される* 名前だけを変更することに注意してください。
"parse_args()" の返すオブジェクトの属性名は dest の値のままです。

"nargs" を指定した場合、metavar が複数回利用されるかもしれません。
"metavar" にタプルを渡すと、各引数に対して異なる名前を指定できます:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x', nargs=2)
   >>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
   >>> parser.print_help()
   usage: PROG [-h] [-x X X] [--foo bar baz]

   options:
    -h, --help     show this help message and exit
    -x X X
    --foo bar baz


dest
----

ほとんどの "ArgumentParser" のアクションは "parse_args()" が返すオブジ
ェクトに対する属性として値を追加します。この属性の名前は
"add_argument()" の "dest" キーワード引数によって決定されます。位置引
数のアクションについては、 "dest" は通常 "add_argument()" の第一引数と
して渡します:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('bar')
   >>> parser.parse_args(['XXX'])
   Namespace(bar='XXX')

オプション引数のアクションについては、 "dest" の値は通常オプション文字
列から生成されます。 "ArgumentParser" は最初の長いオプション文字列を選
択し、先頭の "--" を除去することで "dest" の値を生成します。長いオプシ
ョン文字列が指定されていない場合、最初の短いオプション文字列から先頭の
"-" 文字を除去することで "dest" を生成します。先頭以外のすべての "-"
文字は、妥当な属性名になるように "_" 文字へ変換されます。次の例はこの
動作を示しています:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('-f', '--foo-bar', '--foo')
   >>> parser.add_argument('-x', '-y')
   >>> parser.parse_args('-f 1 -x 2'.split())
   Namespace(foo_bar='1', x='2')
   >>> parser.parse_args('--foo 1 -y 2'.split())
   Namespace(foo_bar='1', x='2')

"dest" にカスタムの属性名を与えることも可能です:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', dest='bar')
   >>> parser.parse_args('--foo XXX'.split())
   Namespace(bar='XXX')


Action クラス
-------------

Acrtion クラスは Action API、すなわちコマンドラインからの引数を処理す
る呼び出し可能オブジェクトを返す呼び出し可能オブジェクトを実装します。
この API に従うあらゆるオブジェクトは "action" 引数として
"add_argument()" に渡すことができます。

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

Action オブジェクトは、コマンドラインからの一つ以上の文字列から単一の
引数を解析するのに必要とされる情報を表現するために ArgumentParser によ
って使われます。Action クラス 2 つの位置引数と、"action" それ自身を除
く "ArgumentParser.add_argument()" に渡されるすべてのキーワード引数を
受け付けなければなりません。

Action のインスタンス (あるいは "action" 引数に渡す任意の呼び出し可能
オブジェクトの返り値) は、属性 "dest", "option_strings", "default",
"type", "required", "help", などを定義しなければなりません。これらの属
性を定義するのを確実にするためにもっとも簡単な方法は、
"Action.__init__" を呼び出すことです。

Action インスタンスは呼び出し可能でなければならず、したがって、サブク
ラスは 4 つの引数を受け取る "__call__" メソッドをオーバライドしなけれ
ばなりません:

* "parser" - このアクションを持っている ArgumentParser オブジェクト。

* "namespace" - "parse_args()" が返す "Namespace" オブジェクト。ほとん
  どのアクションはこのオブジェクトに属性を "setattr()" を使って追加し
  ます。

* "values" - 型変換が適用された後の、関連付けられたコマンドライン引数
  。型変換は "add_argument()" メソッドの type キーワード引数で指定され
  ます。

* "option_string" - このアクションを実行したオプション文字列。
  "option_string" 引数はオプションで、アクションが位置引数に関連付けら
  れた場合は渡されません。

"__call__" メソッドでは任意のアクションを行えます。典型的には "dest"
および "values" に基いて "namespace" に属性をセットします。

Action のサブクラスを定義する際に "format_usage" メソッドを実装するこ
とができます。このメソッドは引数を受け取らず、プログラムの使用方法
(usage) を表示する際に使われる文字列を返すようにします。このメソッドが
実装されていない場合は、sensible default (訳注: システムにより上手く設
定されたデフォルト値) が使われます。


parse_args() メソッド
=====================

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

   引数の文字列をオブジェクトに変換し、namespace オブジェクトの属性に
   代入します。結果の namespace オブジェクトを返します。

   事前の "add_argument()" メソッドの呼び出しにより、どのオブジェクト
   が生成されてどう代入されるかが決定されます。詳細は "add_argument()"
   のドキュメントを参照してください。

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


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

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

   サブコマンドを扱う1つの便利な方法は "add_subparsers()" メソッドと
   "set_defaults()" を組み合わせて、各サブパーサーにどの Python 関数を
   実行するかを教えることです。例えば:

      >>> # sub-command functions
      >>> def foo(args):
      ...     print(args.x * args.y)
      ...
      >>> def bar(args):
      ...     print('((%s))' % args.z)
      ...
      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(required=True)
      >>>
      >>> # create the parser for the "foo" command
      >>> parser_foo = subparsers.add_parser('foo')
      >>> parser_foo.add_argument('-x', type=int, default=1)
      >>> parser_foo.add_argument('y', type=float)
      >>> parser_foo.set_defaults(func=foo)
      >>>
      >>> # create the parser for the "bar" command
      >>> parser_bar = subparsers.add_parser('bar')
      >>> parser_bar.add_argument('z')
      >>> parser_bar.set_defaults(func=bar)
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('foo 1 -x 2'.split())
      >>> args.func(args)
      2.0
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('bar XYZYX'.split())
      >>> args.func(args)
      ((XYZYX))

   こうすると、"parse_args()" が引数の解析が終わってから適切な関数を呼
   び出すようになります。このように関数をアクションに関連付けるのは一
   般的にサブパーサーごとに異なるアクションを扱うもっとも簡単な方法で
   す。ただし、実行されたサブパーサーの名前を確認する必要がある場合は
   、"add_subparsers()" を呼び出すときに "dest" キーワードを指定できま
   す:

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(dest='subparser_name')
      >>> subparser1 = subparsers.add_parser('1')
      >>> subparser1.add_argument('-x')
      >>> subparser2 = subparsers.add_parser('2')
      >>> subparser2.add_argument('y')
      >>> parser.parse_args(['2', 'frobble'])
      Namespace(subparser_name='2', y='frobble')

   バージョン 3.7 で変更: 新しい *required* キーワード引数。


FileType オブジェクト
---------------------

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

   "FileType" ファクトリは "ArgumentParser.add_argument()" の type 引
   数に渡すことができるオブジェクトを生成します。 type が "FileType"
   オブジェクトである引数はコマンドライン引数を、指定されたモード、バ
   ッファーサイズ、エンコーディング、エラー処理でファイルとして開きま
   す (詳細は "open()" 関数を参照してください。):

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
      >>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
      >>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
      Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

   FileType オブジェクトは擬似引数 "'-'" を識別し、読み込み用の
   "FileType" であれば "sys.stdin" を、書き込み用の "FileType" であれ
   ば "sys.stdout" に変換します:

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

   バージョン 3.4 で変更: *encodings* と *errors* がパラメータに追加さ
   れました。


引数グループ
------------

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

   デフォルトでは、 "ArgumentParser" はヘルプメッセージを表示するとき
   に、コマンドライン引数を "位置引数" と "オプション" にグループ化し
   ます。このデフォルトの動作よりも良い引数のグループ化方法がある場合
   、 "add_argument_group()" メソッドで適切なグループを作成できます:

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

      group:
        bar    bar help
        --foo FOO  foo help

   "add_argument_group()" メソッドは、通常の "ArgumentParser" と同じよ
   うな "add_argument()" メソッドを持つ引数グループオブジェクトを返し
   ます。引数がグループに追加された時、パーサーはその引数を通常の引数
   のように扱いますが、ヘルプメッセージではその引数を分離されたグルー
   プの中に表示します。 "add_argument_group()" メソッドには、この表示
   をカスタマイズするための *title* と *description* 引数があります:

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group1 = parser.add_argument_group('group1', 'group1 description')
      >>> group1.add_argument('foo', help='foo help')
      >>> group2 = parser.add_argument_group('group2', 'group2 description')
      >>> group2.add_argument('--bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--bar BAR] foo

      group1:
        group1 description

        foo    foo help

      group2:
        group2 description

        --bar BAR  bar help

   ユーザー定義グループにないすべての引数は通常の "位置引数" と "オプ
   ション引数" セクションに表示されます。

   バージョン 3.11 で変更: 引数グループについて "add_argument_group()"
   を呼び出すことは非推奨です。この機能はこれまでサポートされたことは
   なく、常に正しく動作するとは限りません。この関数は継承を通じて思い
   がけず API に存在することになったもので、将来削除される予定です。


相互排他
--------

ArgumentParser.add_mutually_exclusive_group(required=False)

   相互排他グループを作ります。"argparse" は相互排他グループの中でただ
   1つの引数のみが存在することを確認します:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group()
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args(['--foo'])
      Namespace(bar=True, foo=True)
      >>> parser.parse_args(['--bar'])
      Namespace(bar=False, foo=False)
      >>> parser.parse_args(['--foo', '--bar'])
      usage: PROG [-h] [--foo | --bar]
      PROG: error: argument --bar: not allowed with argument --foo

   "add_mutually_exclusive_group()" メソッドの引数 *required* に True
   値を指定すると、その相互排他引数のどれか1つを選ぶことが要求されます
   :

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group(required=True)
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args([])
      usage: PROG [-h] (--foo | --bar)
      PROG: error: one of the arguments --foo --bar is required

   Note that currently mutually exclusive argument groups do not
   support the *title* and *description* arguments of
   "add_argument_group()".

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


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

ArgumentParser.set_defaults(**kwargs)

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

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

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

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

   パーサーレベルの default は、複数のパーサーを扱うときに特に便利です
   。このタイプの例については "add_subparsers()" メソッドを参照してく
   ださい。

ArgumentParser.get_default(dest)

   "add_argument()" か "set_defaults()" によって指定された、 namespace
   の属性のデフォルト値を取得します:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='badger')
      >>> parser.get_default('foo')
      'badger'


ヘルプの表示
------------

ほとんどの典型的なアプリケーションでは、"parse_args()" が使用法やエラ
ーメッセージのフォーマットと表示について面倒を見ます。しかし、いくつか
のフォーマットメソッドが利用できます:

ArgumentParser.print_usage(file=None)

   "ArgumentParser" がコマンドラインからどう実行されるべきかの短い説明
   を表示します。 *file* が "None" の時は、 "sys.stdout" に出力されま
   す。

ArgumentParser.print_help(file=None)

   プログラムの使用法と "ArgumentParser" に登録された引数についての情
   報を含むヘルプメッセージを表示します。 *file* が "None" の時は、
   "sys.stdout" に出力されます。

これらのメソッドの、表示する代わりにシンプルに文字列を返すバージョンも
あります:

ArgumentParser.format_usage()

   "ArgumentParser" がコマンドラインからどう実行されるべきかの短い説明
   を格納した文字列を返します。

ArgumentParser.format_help()

   プログラムの使用法と "ArgumentParser" に登録された引数についての情
   報を含むヘルプメッセージを格納した文字列を返します。


部分解析
--------

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

ときどき、スクリプトがコマンドライン引数のいくつかだけを解析し、残りの
引数は別のスクリプトやプログラムに渡すことがあります。こういった場合、
"parse_known_args()" メソッドが便利です。これは "parse_args()" と同じ
ように動作しますが、余分な引数が存在してもエラーを生成しません。代わり
に、評価された namespace オブジェクトと、残りの引数文字列のリストから
なる2要素タプルを返します。

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', action='store_true')
   >>> parser.add_argument('bar')
   >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
   (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

警告:

  先頭文字でのマッチング ルールは "parse_known_args()" にも適用されま
  す。たとえ既知のオプションの先頭文字に過ぎない場合でも、パーサは引数
  リストに残さずに、オプションを受け取る場合があります。


ファイル解析のカスタマイズ
--------------------------

ArgumentParser.convert_arg_line_to_args(arg_line)

   ファイルから引数を読み込む場合 ("ArgumentParser" コンストラクターの
   *fromfile_prefix_chars* キーワード引数を参照)、1行につき1つの引数を
   読み込みます。 "convert_arg_line_to_args()" を変更することでこの動
   作をカスタマイズできます。

   このメソッドは、引数ファイルから読まれた文字列である1つの引数
   *arg_line* を受け取ります。そしてその文字列を解析した結果の引数のリ
   ストを返します。このメソッドはファイルから1行読みこむごとに、順番に
   呼ばれます。

   このメソッドをオーバーライドすると便利なこととして、スペースで区切
   られた行の単語1つ1つを別々の引数として扱えます。次の例でその方法を
   示します:

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


終了メソッド
------------

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

   このメソッドはプログラムを、*status* のステータスで終了させ、指定さ
   れた場合は *message* を終了前に表示します。ユーザは、この振る舞いを
   違うものにするために、メソッドをオーバーライドすることができます。

      class ErrorCatchingArgumentParser(argparse.ArgumentParser):
          def exit(self, status=0, message=None):
              if status:
                  raise Exception(f'Exiting because of an error: {message}')
              exit(status)

ArgumentParser.error(message)

   このメソッドは *message* を含む使用法メッセージを標準エラーに表示し
   て、終了ステータス 2 でプログラムを終了します。


混在した引数の解析
------------------

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

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

多くの Unix コマンドは、オプション引数と位置引数を混在させることを許し
ています。 "parse_intermixed_args()" と
"parse_known_intermixed_args()" メソッドは、このような方法での解析をサ
ポートしています。

このパーサーは、argparse のすべての機能をサポートしておらず、対応しな
い機能が使われた場合、例外を送出します。特に、サブパーサーや、位置引数
とオプション引数を両方含むような相互排他的なグループは、サポートされて
いません。

この例は、"parse_known_args()" と "parse_intermixed_args()" の違いを表
しています: 前者は "['2', '3']" を、解析されない引数として返し、後者は
全ての位置引数を "rest" に入れて返しています:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('cmd')
   >>> parser.add_argument('rest', nargs='*', type=int)
   >>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
   (Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
   >>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
   Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

"parse_known_intermixed_args()" は、解析した内容を含む名前空間と、残り
の引数を含んだリストの、2つの要素を持つタプルを返します。
"parse_intermixed_args()" は、解析されない引数が残された場合にはエラー
を送出します。

バージョン 3.7 で追加.


optparse からのアップグレード
=============================

もともと、"argparse" モジュールは "optparse" モジュールとの互換性を保
って開発しようと試みられました。しかし、特に新しい "nargs=" 指定子とよ
り良い使用法メッセージのために必要な変更のために、"optparse" を透過的
に拡張することは難しかったのです。"optparse" のほとんどすべてがコピー
アンドペーストされたりモンキーパッチを当てられたりしたとき、もはや後方
互換性を保とうとすることは現実的ではありませんでした。

"argparse" モジュールは標準ライブラリ "optparse" モジュールを、以下を
含むたくさんの方法で改善しています:

* 位置引数を扱う

* サブコマンドのサポート

* "+", "/" のような代替オプションプレフィクスを許容する

* zero-or-more スタイル、one-or-more スタイルの引数を扱う

* より有益な使用方法メッセージの生成

* カスタム "type", カスタム "action" のために遥かに簡単なインターフェ
  イスを提供する

"optparse" から "argparse" への現実的なアップグレードパス:

* すべての "optparse.OptionParser.add_option()" の呼び出しを、
  "ArgumentParser.add_argument()" の呼び出しに置き換える。

* "(options, args) = parser.parse_args()" を "args =
  parser.parse_args()" に置き換え、位置引数のために必要に応じて
  "ArgumentParser.add_argument()" の呼び出しを追加する。これまで
  "options" と呼ばれていたものが、"argparse" では "args" と呼ばれてい
  ることに留意してください。

* "optparse.OptionParser.disable_interspersed_args()" を、
  "parse_args()" ではなく "parse_intermixed_args()" で置き換える。

* コールバック・アクションと "callback_*" キーワード引数を "type" や
  "action" 引数に置き換える。

* "type" キーワード引数に渡していた文字列の名前を、それに応じたオブジ
  ェクト (例: int, float, complex, ...) に置き換える。

* "optparse.Values" を "Namespace" に置き換え、"optparse.OptionError"
  と "optparse.OptionValueError" を "ArgumentError" に置き換える。

* "%default" や "%prog" などの暗黙の引数を含む文字列を、"%(default)s"
  や "%(prog)s" などの、通常の Python で辞書を使う場合のフォーマット文
  字列に置き換える。

* OptionParser のコンストラクターの "version" 引数を、
  "parser.add_argument('--version', action='version', version='<the
  version>')" に置き換える


例外
====

exception argparse.ArgumentError

   引数 (オプション引数または位置引数) の生成時または利用時のエラーで
   す。

   この例外の文字列表現は、エラーの原因となった引数についての情報を補
   足するメッセージです。

exception argparse.ArgumentTypeError

   コマンドラインの文字列を、指定された型に変換するのに失敗した時に送
   出されます。
