"argparse" --- コマンドラインオプションや引数、サブコマンド向けのパーサー
*************************************************************************

Added in version 3.2.

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

注釈:

  "argparse" は基本的なコマンドラインアプリケーションの実装に推奨され
  る標準ライブラリのモジュールですが、動作を厳密に制御したい場合には、
  必要な制御ができないことがあります。 "argparse" が必要な動作をサポー
  トしていない場合、代替手段については 引数解析ライブラリの選択 を参照
  してください。 例えば、オプションと位置引数の混在を完全に禁止したり
  、"-" で始まる値が他の定義済みオプションと一致する場合でもオプション
  の値として受け付けたりしたい場合が該当します。

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


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

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

"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')           # 位置引数
   parser.add_argument('-c', '--count')      # 値を取るオプション
   parser.add_argument('-v', '--verbose',
                       action='store_true')  # オン／オフフラグ

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

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

注釈:

  "optparse" のコードを "argparse" に移行する方法は、Optparse のコード
  のアップグレード を参照してください。


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, *, suggest_on_error=True, color=True)

   新しい "ArgumentParser" オブジェクトを生成します。すべての引数はキ
   ーワード引数として渡すべきです。各引数についてはあとで詳しく説明し
   ますが、簡単に言うと:

   * prog - プログラム名 (デフォルト: "__main__" モジュールの属性と
     "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")

   * suggest_on_error - 引数の選択肢やサブパーサー名の入力ミスに対して
     候補を提示する (デフォルト: "True")

   * color - 色付きの出力を許可する (デフォルト: "True")

   バージョン 3.5 で変更: *allow_abbrev* 引数が追加されました。

   バージョン 3.8 で変更: 以前のバージョンでは、 *allow_abbrev* は、
   "-vv" が "-v -v" と等価になるような、短いフラグのグループ化を無効に
   していました。

   バージョン 3.9 で変更: *exit_on_error* 引数が追加されました。

   バージョン 3.14 で変更: "suggest_on_error" と "color" パラメーター
   が追加されました。

   バージョン 3.15 で変更: "suggest_on_error" のデフォルト値が "True"
   に変わりました。

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


"prog"
------

デフォルトでは、"ArgumentParser" は Python インタープリタの実行方法に
応じて、ヘルプに表示するプログラム名を求めます。

* ファイルを引数に渡した場合は、"sys.argv[0]" の "ベース名"。

* ディレクトリか ZIP ファイルを引数に渡した場合は、Python インタープリ
  タの名前に "sys.argv[0]" を続けたもの。

* "-m" オプションを使った場合は、Python インタープリタの名前に "-m"、
  モジュール名またはパッケージ名を続けたもの。

このデフォルトの動作では、コマンドラインでプログラムを実行した文字列と
ヘルプの表記が一致するので、ほとんどの場合に適しています。 変更したい
場合は、"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]"、"__main__" モジュールの属性、"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

バージョン 3.14 で変更: デフォルトの "prog" 値は、常に
"os.path.basename(sys.argv[0])" になるのではなく、"__main__" の実際の
実行方法を反映するようになりました。


"usage"
-------

デフォルトでは、"ArgumentParser" は登録された引数から使用法のメッセー
ジを生成します。 "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" フォーマット指定子を、使用法メッセージ内でプログラム名とし
て利用できます。

メインのパーサーに独自の使用法メッセージを指定する場合は、サブパーサー
間でコマンドの先頭部分や使用法の情報を揃えるため、"add_subparsers()"
に "prog" 引数を渡すか、"add_parser()" に "prog" と "usage" 引数を渡す
ことも検討してください。


"description"
-------------

"ArgumentParser" コンストラクターを呼ぶ際は、多くの場合 "description="
キーワード引数を使います。 この引数には、プログラムが何をどのように行
うかの簡潔な説明を指定します。 ヘルプでは、コマンドラインの使用法を示
す文字列と各引数のヘルプの間に表示されます。

デフォルトでは、説明は与えられたスペースに合わせて折り返されます。この
挙動を変更するには、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" は親と子に一つずつ、計二つの "-h/--help" オプションを
検出してエラーを発生させます。

注釈:

  "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 行に一つずつ記述します
("convert_arg_line_to_args()" も参照してください)。 読み込んだ引数は、
コマンドラインでそのファイルを指定した引数の位置にあるものとして扱われ
ます。 上の例では、"['-f', 'foo', '@args.txt']" は "['-f', 'foo',
'-f', 'bar']" と同じものとして扱われます。

注釈:

  各行が一つの引数として扱われるので、空行は空文字列 ("''") として読み
  込まれます。

"ArgumentParser" は、引数を記述したファイルを *filesystem encoding and
error handler* を使って読み込みます。

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

バージョン 3.12 で変更: "ArgumentParser" が引数ファイルの読み込みに使
うエンコーディングとエラーハンドラーを、デフォルト値
("locale.getpreferredencoding(False)" と ""strict"" など) から
*filesystem encoding and error handler* に変更しました。 Windows では
、引数ファイルを ANSI コードページではなく UTF-8 でエンコードしてくだ
さい。


"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

Added in version 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" オブジェクトに、パーサーのヘルプを表
示するオプションが追加されます。 コマンドラインで "-h" または "--help"
を指定すると、"ArgumentParser" のヘルプが表示されます。

必要に応じて、この 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()" メソッドに不正な引数リストを
渡すと、"sys.stderr" に *メッセージ* を表示し、終了ステータス 2 で終了
します。

もしエラーを例外としてプログラム内でキャッチしたい場合は、
"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

Added in version 3.9.


"suggest_on_error"
------------------

デフォルトでは、ユーザーが引数の選択肢やサブパーサー名として不正な値を
渡すと、"ArgumentParser" はエラー情報と入力ミスに対する候補を表示して
終了します。 エラーメッセージには、引数で指定できる選択肢 (定義されて
いる場合) またはサブパーサー名を列挙し、似たものが見つかれば "maybe
you meant" とともに候補を表示します。 引数の場合、この機能が適用される
のは選択肢が文字列のときだけです。

   >>> parser = argparse.ArgumentParser(suggest_on_error=True)
   >>> parser.add_argument('--action', choices=['debug', 'dryrun'])
   >>> parser.parse_args(['--action', 'debugg'])
   usage: tester.py [-h] [--action {debug,dryrun}]
   tester.py: error: argument --action: invalid choice: 'debugg', maybe you meant 'debug'? (choose from debug, dryrun)

"suggest_on_error" を "False" に設定すると、候補の提示を無効にできます
。

Added in version 3.14.

バージョン 3.15 で変更: "suggest_on_error" のデフォルト値が "False" か
ら "True" に変わりました。


"color"
-------

デフォルトでは、ヘルプは ANSI エスケープシーケンス を使って色付きで表
示されます。 プレーンテキストで表示したい場合は、ローカル環境の設定 で
色を無効にするか、引数パーサーの "color" を "False" に設定してください
。

   >>> parser = argparse.ArgumentParser(description='Process some integers.',
   ...                                  color=False)
   >>> parser.add_argument('--action', choices=['sum', 'max'])
   >>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
   ...                     help='an integer for the accumulator')
   >>> parser.parse_args(['--help'])

"color=True" の場合、色付きで表示されるかどうかは環境変数と端末の機能
によって決まります。 一方、"color=False" の場合は、"FORCE_COLOR" のよ
うな環境変数が設定されていても、色付きの出力は常に無効になります。

Added in version 3.14.

"description"、"epilog"、引数の "help" テキストでインラインのコードを
強調表示するには、シングルバッククォートまたはダブルバッククォートで囲
みます。

   >>> parser = argparse.ArgumentParser(
   ...     formatter_class=argparse.RawDescriptionHelpFormatter,
   ...     description='Run ``python -m myapp`` to start.',
   ...     epilog='''Examples:
   ...   `python -m myapp --verbose`
   ...   ``python -m myapp --config settings.json``
   ... ''')
   >>> parser.add_argument('--foo', help='set the `foo` value')

色が有効な場合、バッククォートで囲んだテキストは別の色で表示され、例が
目立つようになります。 色が無効な場合はバッククォートがそのまま残り、
プレーンテキストでも読める形になります。

Added in version 3.15.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

   * deprecated - この引数の使用が非推奨かどうか。

   このメソッドは、引数を表す "Action" オブジェクトを返します。

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


"name" or "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

デフォルトでは、"argparse" が引数の内部的な名前と表示名を自動的に決め
るため、追加の設定は必要ありません。 そのため、dest と metavar パラメ
ーターを指定する必要はありません。 オプション引数の場合、dest のデフォ
ルトは、引数名のハイフン "-" をアンダースコア "_" に置き換えたものです
。 metavar のデフォルトは、この名前を大文字にしたものです。 例えば次の
ようになります。

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('--foo-bar')
   >>> parser.parse_args(['--foo-bar', 'FOO-BAR'])
   Namespace(foo_bar='FOO-BAR')
   >>> parser.print_help()
   usage:  [-h] [--foo-bar FOO-BAR]

   optional arguments:
    -h, --help  show this help message and exit
    --foo-bar FOO-BAR


"action"
--------

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

* "'store'" - 引数の値を格納します。 これがデフォルトのアクションです
  。

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

  これらのデフォルト値は、オプションが指定されなかったときに使われます
  。 default または argument_default で変更できます。

* "'append'" - 引数の値をリストに追加します。 同じオプションを複数回指
  定できるようにする場合に便利です。 デフォルト値が空でないリストの場
  合、解析結果のリストはそのデフォルト値の要素から始まり、コマンドライ
  ンから取得した値はその後ろに追加されます。 使用例です。

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='append', default=['0'])
     >>> parser.parse_args('--foo 1 --foo 2'.split())
     Namespace(foo=['0', '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'>])

* "'extend'" - 複数の値を持つ引数の各要素をリストに追加します。
  "'extend'" アクションは通常、nargs キーワード引数に "'+'" または
  "'*'" を指定して使います。 nargs が "None" (デフォルト) または "'?'"
  の場合は、引数文字列の各文字がリストに追加されることに注意してくださ
  い。 使用例です。

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

  Added in version 3.8.

* "'count'" - 引数が指定された回数を数えます。 例えば、出力の詳細度を
  上げるために使えます。

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

  明示的に設定しなければ、*default* は "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

"Action" のサブクラス ("BooleanOptionalAction" など) や、同じインター
フェースを実装する別のオブジェクトを渡して、任意のアクションを指定する
こともできます。 位置引数に使えるのは、コマンドライン引数を消費するア
クション ("'store'"、"'append'"、"'extend'"、"nargs" がゼロ以外のカス
タムアクションなど) だけです。

カスタムアクションを作るには、"Action" を継承して "__call__()" メソッ
ドをオーバーライドし、必要に応じて "__init__()" と "format_usage()" メ
ソッドもオーバーライドする方法を推奨します。 "register()" メソッドでカ
スタムアクションを登録し、その登録名で参照することもできます。

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

   >>> 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" オブジェクトは通常、一つのコマンドライン引数に対して
一つのアクションを実行します。 "nargs" キーワード引数を使うと、一つの
アクションに別の個数のコマンドライン引数を対応させられます。 多義性の
ある引数の指定 も参照してください。 指定できる値は次のとおりです。

* "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='?')
     >>> parser.add_argument('outfile', nargs='?')
     >>> parser.parse_args(['input.txt', 'output.txt'])
     Namespace(infile='input.txt', outfile='output.txt')
     >>> parser.parse_args(['input.txt'])
     Namespace(infile='input.txt', outfile=None)
     >>> parser.parse_args([])
     Namespace(infile=None, outfile=None)

* "'*'" -- すべてのコマンドライン引数がリストに集められます。複数の位
  置引数が "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'])

* "'+'" - "'*'" と同様に、コマンドラインで指定された引数をすべてリスト
  に集めます。 ただし、コマンドライン引数が一つもなければエラーメッセ
  ージを表示します。 例えば次のようになります。

     >>> 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
によって決まります。 通常は、一つのコマンドライン引数を消費して、リス
トではなく単一の値を生成します。 コマンドライン引数を消費しないアクシ
ョン ("'store_const'" など) では、"nargs=0" が設定されます。


"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" の値が使わ
  れます。 例は nargs の説明を参照してください。

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


"default"
---------

コマンドラインでは、すべてのオプション引数と一部の位置引数を省略できま
す。 "add_argument()" の "default" キーワード引数には、コマンドライン
引数が指定されなかった場合に使う値を指定します。 例えば次のようになり
ます。

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

"default" を省略すると、"add_argument()" は、その dest に対して
"set_defaults()" で設定済みの値を使います。 設定されていなければ、
argument_default が "None" 以外の場合にその値を使います。 どちらも設定
されていなければ、アクション自身のデフォルト値を使います。

対象の名前空間にすでに属性が設定されている場合、アクションの *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)

"nargs='*'" は指定された値をリストに集めるため、位置引数が指定されなけ
れば空リスト ("[]") になります。 この動作を変更できるのは *default* が
"None" 以外の場合だけです ("default=None" でも "[]" になります)。

required の引数では "default" の値は無視されます。 例えば、nargs が
"?" や "*" 以外の位置引数や、"required=True" を指定したオプション引数
が該当します。

"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" には、一つの文字列を受け取る呼び出し可能オブジェクト、または登
録済みの型の名前 ("register()" を参照) を渡せます。 この関数が
"ArgumentTypeError"、"TypeError"、"ValueError" を送出すると、その例外
を捕捉して読みやすい形式のエラーメッセージを表示します。 それ以外の例
外は処理しません。

一般的なビルトインデータ型や関数を "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('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')

"bool()" 関数を型変換に使うことは推奨しません。 空文字列を "False" に
、空でない文字列を "True" に変換するだけなので、通常は意図した結果にな
りません。

   >>> parser = argparse.ArgumentParser()
   >>> _ = parser.add_argument('--verbose', type=bool)
   >>> parser.parse_args(['--verbose', 'False'])
   Namespace(verbose=True)

よく使われる代替手段については、"BooleanOptionalAction" または
"action='store_true'" を参照してください。

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

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

"FileType" でさえ、"type" キーワードでの使用には制限があります。 ある
引数で "FileType" を使い、その後の引数でエラーが起きると、エラーは報告
されますが、ファイルは自動的には閉じられません。 この場合は、引数の解
析が終わってから "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* に渡すことができます。すなわち、"list" オ
ブジェクト、 "tuple" オブジェクト、カスタムシーケンスはすべてサポート
されています。

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

*choices* の検査は type による変換の後に行われるので、*choices* のオブ
ジェクトは指定した type に合うものにしてください。 そのため、使用法、
ヘルプ、エラーメッセージに表示される *choices* が、ユーザーにとってな
じみのない表記になることがあります。

*choices* をユーザーにわかりやすく表示するには、値の変換と書式化を行う
独自の型ラッパーを使うか、type を指定せず、アプリケーションのコードで
変換することを検討してください。

ヘルプテキストにおいて整形された 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" の説明が表示されます。

"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 の値を大文字にして
使います。 そのため、"dest='bar'" の位置引数は "bar" と表示されます。
コマンドライン引数を一つ受け取るオプション "--foo" では、その値が
"FOO" と表示されます。 例えば次のようになります。

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

   positional arguments:
    bar

   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" の値にします。 二つの
ダッシュで始まる長いオプション文字列がなければ、一つのダッシュで始まる
最初の長いオプション文字列から、先頭の "-" を取り除きます。 長いオプシ
ョン文字列がなければ、最初の短いオプション文字列から先頭の "-" を取り
除きます。 属性名として使える文字列にするため、内部の "-" はすべて "_"
に変換します。 以下の例でこの動作を示します。

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

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

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

複数の引数で同じ "dest" を使えます。 デフォルトでは、それらのうちコマ
ンドラインで最後に指定された引数の値が使われます。 すべての値をリスト
に集めるには、"action='append'" を使ってください。 "dest" の名前ではな
く *オプション文字列* が重複する場合は、conflict_handler を参照してく
ださい。

バージョン 3.15 で変更: 一つのダッシュで始まる長いオプションが、短いオ
プションより優先されるようになりました。


"deprecated"
------------

プロジェクトの開発を続けるうちに、コマンドライン引数を削除する必要が生
じることがあります。 削除する前に、その引数が非推奨となり、削除される
予定であることをユーザーに知らせてください。 "add_argument()" の
"deprecated" キーワード引数は、その引数が非推奨で将来削除されるかどう
かを指定し、デフォルトは "False" です。 "deprecated" が "True" の引数
を使うと、"sys.stderr" に警告が表示されます。

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

Added in version 3.13.


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

"Action" クラスは Action API を実装します。 この API は、呼び出される
と、コマンドライン引数を処理する呼び出し可能オブジェクトを返します。
この API に従うオブジェクトであれば、"add_argument()" の "action" パラ
メーターに渡せます。

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

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

   "Action" のインスタンス (または "action" パラメーターに渡した呼び出
   し可能オブジェクトの返り値) には、"dest"、"option_strings"、
   "default"、"type"、"required"、"help" などの属性を定義してください
   。 これらの属性を確実に定義する最も簡単な方法は、
   "Action.__init__()" を呼び出すことです。

   __call__(parser, namespace, values, option_string=None)

      "Action" のインスタンスは呼び出し可能でなければなりません。 その
      ため、サブクラスでは "__call__()" メソッドをオーバーライドし、次
      の四つの引数を受け付けるようにしてください。

      * *parser* - このアクションを含む "ArgumentParser" オブジェクト
        。

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

      * *values* - 対応するコマンドライン引数に型変換を適用した値。 型
        変換は "add_argument()" の type キーワード引数で指定します。

      * *option_string* - このアクションの呼び出しに使われたオプション
        文字列。 "option_string" 引数は省略可能で、位置引数に対応する
        アクションでは指定されません。

      "__call__()" メソッドは任意の処理を行えますが、通常は "dest" と
      "values" に基づいて "namespace" の属性を設定します。

   format_usage()

      "Action" のサブクラスでは、引数を取らず、プログラムの使用法の表
      示に使う文字列を返す "format_usage()" メソッドを定義できます。
      このメソッドを定義しなければ、適切なデフォルトの表示が使われます
      。

class argparse.BooleanOptionalAction

   有効にするオプションと無効にするオプションを持つ真偽値のフラグを扱
   う、"Action" のサブクラスです。 "--foo" のような引数を一つ追加する
   と、"--foo" と "--no-foo" の両方が自動的に作られ、それぞれ "True"
   と "False" を格納します。

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

   一つのダッシュで始まる長いオプションもサポートしています。 例えば、
   有効にするオプション "-foo" に対して、無効にするオプション "-nofoo"
   が自動的に追加されます。 ただし、"-f" のような短いオプションに対し
   ては、追加のオプションは作られません。

   Added in version 3.9.

   バージョン 3.15 で変更: 一つのダッシュで始まるオプションのサポート
   が追加されました。別の prefix_chars を使う場合のサポートが追加され
   ました。


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='?')

   >>> # 不正な型
   >>> parser.parse_args(['--foo', 'spam'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: argument --foo: invalid int value: 'spam'

   >>> # 不正なオプション
   >>> parser.parse_args(['--bar'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: unrecognized arguments: --bar

   >>> # 引数の数が不正
   >>> parser.parse_args(['spam', 'badger'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: unrecognized arguments: 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: unrecognized arguments: -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)

詳細は argparse の HOWTO の曖昧な引数についての説明 も参照してください
。

バージョン 3.14 で変更: 負数として認識する形式を拡張し、指数表記の数値
("-2.5e-6")、アンダースコアを含む数値 ("-1_234.5")、複素数 ("-1.2e-
3j") も認識するようになりました。


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

"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][, dest][, required][, help][, metavar])

   多くのプログラムは、機能をいくつかのサブコマンドに分けています。 例
   えば "svn" プログラムでは、"svn checkout"、"svn update"、"svn
   commit" などのサブコマンドを呼び出せます。 それぞれ異なる種類のコマ
   ンドライン引数を必要とする複数の機能を持つプログラムでは、このよう
   に分ける方法が特に適しています。 "ArgumentParser" では
   "add_subparsers()" メソッドでサブコマンドを作成できます。 通常、
   "add_subparsers()" は引数なしで呼び出し、専用のアクションオブジェク
   トを返します。 このオブジェクトの "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, ..} の形式で表示されます。

   いくつかの使用例:

      >>> # 最上位のパーサーを作成する
      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('--foo', action='store_true', help='foo help')
      >>> subparsers = parser.add_subparsers(help='subcommand help')
      >>>
      >>> # "a" コマンド用のパーサーを作成する
      >>> parser_a = subparsers.add_parser('a', help='a help')
      >>> parser_a.add_argument('bar', type=int, help='bar help')
      >>>
      >>> # "b" コマンド用のパーサーを作成する
      >>> parser_b = subparsers.add_parser('b', help='b help')
      >>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz help')
      >>>
      >>> # 引数リストを解析する
      >>> 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" 属性だけが存在します。

   サブパーサーが親パーサーと同じ "dest" の引数を定義すると、両者は同
   じ名前空間の属性を共有するため、親の値は保持されません。 両方の値を
   保持するには、異なる "dest" を指定してください。

   同じように、サブパーサーにヘルプメッセージが要求された場合は、その
   パーサーに対するヘルプだけが表示されます。ヘルプメッセージには親パ
   ーサーや兄弟パーサーのヘルプメッセージを表示しません。 (ただし、各
   サブパーサーコマンドのヘルプメッセージは、上の例にもあるように
   "add_parser()" の "help=" 引数によって指定できます)

      >>> parser.parse_args(['--help'])
      usage: PROG [-h] [--foo] {a,b} ...

      positional arguments:
        {a,b}   subcommand 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

   サブコマンドを扱う特に効果的な方法は、"add_subparsers()" と
   "set_defaults()" を組み合わせて、各サブパーサーに実行すべき Python
   関数を設定することです。 例えば次のようになります。

      >>> # サブコマンドの関数
      >>> def foo(args):
      ...     print(args.x * args.y)
      ...
      >>> def bar(args):
      ...     print('((%s))' % args.z)
      ...
      >>> # 最上位のパーサーを作成する
      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(required=True)
      >>>
      >>> # "foo" コマンド用のパーサーを作成する
      >>> 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)
      >>>
      >>> # "bar" コマンド用のパーサーを作成する
      >>> parser_bar = subparsers.add_parser('bar')
      >>> parser_bar.add_argument('z')
      >>> parser_bar.set_defaults(func=bar)
      >>>
      >>> # 引数を解析し、選ばれた関数を呼び出す
      >>> args = parser.parse_args('foo 1 -x 2'.split())
      >>> args.func(args)
      2.0
      >>>
      >>> # 引数を解析し、選ばれた関数を呼び出す
      >>> args = parser.parse_args('bar XYZYX'.split())
      >>> args.func(args)
      ((XYZYX))

   This way, you can let "parse_args()" do the job of calling the
   appropriate function after argument parsing is complete.
   Associating functions with actions like this is typically the
   easiest way to handle the different actions for each of your
   subparsers.  However, if it is necessary to check the name of the
   subparser that was invoked, the "dest" keyword argument to the
   "add_subparsers()" call will work:

      >>> 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* パラメーターが追
   加されました。

   バージョン 3.14 で変更: メインパーサーに指定した独自の使用法メッセ
   ージが、サブパーサーの *prog* に影響しなくなりました。

_SubParsersAction.add_parser(name, *, help=None, aliases=None, deprecated=False, **kwargs)

   サブコマンド *name* 用の新しい "ArgumentParser" オブジェクトを作成
   して返します。

   *name* 引数はサブコマンドの名前です。

   *help* 引数は、このサブコマンドの簡潔な説明を指定します。

   *aliases* 引数では、このサブコマンドの別名を指定できます。 例えば次
   のようになります。

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

   *deprecated* 引数を "True" にすると、そのサブコマンドを非推奨とし、
   使用時に警告を表示します。 例えば次のようになります。

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

   それ以外のキーワード引数はすべて、"ArgumentParser" コンストラクター
   に直接渡されます。

   Added in version 3.13: *deprecated* パラメーターが追加されました。


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

   注釈:

     ある引数で *FileType* を使い、その後の引数でエラーが起きると、エ
     ラーは報告されますが、ファイルは自動的には閉じられません。 出力フ
     ァイルの内容を失うこともあります。 この場合は、引数の解析が終わっ
     てから "with" 文でファイルを管理する方が適切です。

   バージョン 3.4 で変更: *encoding* と *errors* が引数に追加されまし
   た。

   バージョン 3.14 で非推奨.


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

ArgumentParser.add_argument_group(title=None, description=None, *[, argument_default][, conflict_handler])

   デフォルトでは、"ArgumentParser" はヘルプを表示する際に、コマンドラ
   イン引数を "positional arguments" と "options" に分けます。 引数の
   意味に応じた別の分け方が適している場合は、"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

   省略可能なキーワード専用パラメーター argument_default と
   conflict_handler を使うと、引数グループの動作をより細かく制御できま
   す。 これらの意味は "ArgumentParser" コンストラクターと同じですが、
   パーサー全体ではなく、その引数グループだけに適用されます。

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

   各引数グループ内の引数は、追加した順にヘルプに表示されます。

   バージョン 3.11 で非推奨、バージョン 3.14 で削除: 引数グループに対
   して "add_argument_group()" を呼び出すと、例外が送出されるようにな
   りました。 この入れ子構造はもともとサポートされておらず、正しく動作
   しないことも多くありました。 継承によって意図せず利用可能になってい
   たものです。

   バージョン 3.14 で非推奨: "add_argument_group()" に prefix_chars を
   渡すことは非推奨になりました。


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

ArgumentParser.add_mutually_exclusive_group(required=False)

   相互排他グループを作成します。 "argparse" は、そのグループに含まれ
   る複数の引数がコマンドラインで同時に指定されないことを確認します。

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

   現在、相互排他引数グループでは "add_argument_group()" の *title* と
   *description* 引数はサポートされていません。 ただし、タイトルと説明
   を持つ引数グループに、相互排他グループを追加することはできます。 例
   えば次のようになります。

      >>> 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 で非推奨、バージョン 3.14 で削除: 相互排他グループ
   に対して "add_argument_group()" または
   "add_mutually_exclusive_group()" を呼び出すと、例外が送出されるよう
   になりました。 この入れ子構造はもともとサポートされておらず、正しく
   動作しないことも多くありました。 継承によって意図せず利用可能になっ
   ていたものです。


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

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)

   デフォルト値は、"set_defaults()" でパーサーに設定することも、
   "add_argument()" で個々の引数に設定することもできます。 同じ引数に
   ついて両方を呼び出した場合は、最後に設定したデフォルト値が使われま
   す。

      >>> 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()" と同様に動作しますが、認識できない余
   分な引数があってもエラーにはなりません。 認識できる引数を解析し、値
   を設定した名前空間と、認識できなかった引数のリストからなる 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* が指定されていれば、終了前に "sys.stderr" に表示します。
   このメソッドをオーバーライドして、これらの処理を変更できます。

      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* を含む使用法メッセージを "sys.stderr" に
   表示し、ステータスコード 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()" は、解析されない引数が残された場合にはエ
   ラーを送出します。

   Added in version 3.7.


独自の型やアクションの登録
--------------------------

ArgumentParser.register(registry_name, value, object)

   エラーメッセージに独自の文字列を使って、出力をユーザーにわかりやす
   くしたい場合があります。 その場合は、"register()" で独自のアクショ
   ンや型をパーサーに登録すると、呼び出し可能オブジェクトの名前の代わ
   りに登録名で型を参照できます。

   "register()" メソッドは三つの引数を受け取ります。 *registry_name*
   はオブジェクトを格納する内部レジストリ ("action"、"type" など)、
   *value* は登録に使うキー、"object" は登録する呼び出し可能オブジェク
   トです。

   次の例は、パーサーに独自の型を登録する方法を示します。

      >>> import argparse
      >>> parser = argparse.ArgumentParser()
      >>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))
      >>> parser.add_argument('--foo', type='hexadecimal integer')
      _StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default=None, type='hexadecimal integer', choices=None, required=False, help=None, metavar=None, deprecated=False)
      >>> parser.parse_args(['--foo', '0xFA'])
      Namespace(foo=250)
      >>> parser.parse_args(['--foo', '1.2'])
      usage: PROG [-h] [--foo FOO]
      PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'


例外
====

exception argparse.ArgumentError

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

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

exception argparse.ArgumentTypeError

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

-[ ガイドとチュートリアル ]-

* Argparse チュートリアル

* "optparse" を使うコードを "argparse" に移行する
