概要と導入

Python の標準ライブラリに含まれる argparse モジュールは、スクリプトやアプリケーションに対するコマンドラインからの入力データを解析・処理するための主要な手段です。このツールを使用することで、開発者は手動でパラメータ検証を行うことなく、標準的なヘルプメッセージの自動生成やエラーハンドリング機能を統合できます。

基本的な実装フロー

基本的な利用手順は以下の 3 つのステップに集約されます：

• 解析対象となる ArgumentParser クラスのインスタンスを作成する
• 期待するコマンドライン引数を定義する
• 実行時の引数をパースし、結果オブジェクトを取得して利用する

import argparse

# パーサーの初期化
parser = argparse.ArgumentParser(description='ツール説明テキスト')

# 引数の定義
parser.add_argument('操作モード', choices=['計算', '分析'], help='実行モードを指定')
parser.add_argument('-x', type=int, help='入力値 x')
parser.add_argument('-y', type=int, help='入力値 y')

# パース実行
parsed_values = parser.parse_args()

# 結果の出力
if parsed_values.操作_mode == '計算':
    print(f'結果：{parsed_values.x} + {parsed_values.y} = ', parsed_values.x + parsed_values.y)
elif parsed_values.操作_mode == '分析':
    print(f'分析完了：値={parsed_values.x}, {parsed_values.y}')

add_argument() 設定オプション详解

引数登録時に指定可能な主要な設定項目は以下の通りです：

• dest: 解析後のデータが格納される属性名（第 1 位置引数として渡された名前と一致）
• action: 処理動作の種類。基本は store（値保持）。その他、store_const（定数保存）、store_true（真偽値）、append（リスト追加）、count（出現回数カウント）、version（バージョン表示）などがある
• type: 文字列以外の型への変換関数。int, float, ファイルパスなど指定可能
• choices: 受け付ける値の限定リスト。指定外が入力された場合エラーとなる
• required: ブーリアン。必須引数かどうかを指定（デフォルトは False）
• nargs: 必要な引数の個数。'?'（0 または 1）, '*'（任意の個数）などを指定可能
• default: 引数が指定されなかった時の代替値
• help: ヘルプ画面に表示される説明文
• metavar: ヘルプ表示用に使用される変数名（短縮形など）

注意：必須引数は通常、明示的に required=True を設定しなくても、位置引数として定義されていればデフォルトで必須扱いとなります。

位置引数の活用例

順序に基づいて値を受け取る位置引数（Positional Arguments）の使用例です。

import argparse

parser = argparse.ArgumentParser(description='足し算ツール')
parser.add_argument('数字 1', type=int, help='最初の整数')
parser.add_argument('数字 2', type=int, help='二番目の整数')

data = parser.parse_args()
total = data.数字 1 + data.数字 2
print(f'{data.数字 1} + {data.数字 2} = {total}')

上記スクリプトを実行し -h フラグを指定するとヘルプが表示されます：

$ python3 script.py -h
usage: script.py [-h] 数字 1 数字 2

足し算ツール

positional arguments:
  数字 1          最初の整数
  数字 2          二番目の整数

optional arguments:
  -h, --help      show this help message and exit

実際の引数を渡すと計算結果が得られます：

$ python3 script.py 10 20
10 + 20 = 30

バリエーション機能の実装

choices で許容範囲を制限し、nargs と default でオプショナルな振る舞いを実現する例です。

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('target', type=int, choices=[1, 2, 3, 4], metavar='ターゲット ID', help='処理対象 ID')
parser.add_argument('補正', nargs='?', type=float, default=0.0, help='オプション補正値')

values = parser.parse_args()
final_value = values.target + values.补正
print(f'計算済：{final_value}')

nargs='*' を用いることで、可変長引数を扱うことも可能です。

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('numbers', type=int, nargs='*', help='全ての数値')

items = parser.parse_args()
if items.numbers:
    print(f'合計：{sum(items.numbers)}')

オプションフラグの設計

短辞形式 (-f) と長辞形式 (--flag) を同時に定義できます。この際、格納先のキー名を明示的に指定できる dest 引数を活用します。

import argparse

parser = argparse.ArgumentParser()
parser.add_argument('-t', '--threshold', dest='limit', type=float, required=True, help='閾値')
parser.add_argument('-s', '--size', dest='scale', type=float, default=1.0, help='サイズ係数')

config = parser.parse_args()
output = config.limit * config.scale
print(f'出力値：{output}')

この構成では、--threshold や -t を指定しても、プログラム内部では config.limit にアクセスします。また、version アクションを使用してバージョン情報を直接出力させることも簡便です。

parser.add_argument('--v', action='version', version='ツール v1.2.0')

サブロゴラム（サブコマンド）の実装

複数の異なる機能を持つツールを作成する場合、add_subparsers を使用して階層的なコマンド構造を構築できます。

import argparse

main_parser = argparse.ArgumentParser()
subparsers = main_parser.add_subparsers(dest='act', help='操作選択')

# コマンド：展開
expand_cmd = subparsers.add_parser('expand', help='データ拡張')
expand_cmd.add_argument('input', help='入力ファイル')
expand_cmd.set_defaults(func=lambda a: print(f'Expanding {a.input}'))

# コマンド：圧縮
compress_cmd = subparsers.add_parser('compress', help='データ圧縮')
compress_cmd.add_argument('input', help='入力ファイル')
compress_cmd.set_defaults(func=lambda a: print(f'Compressing {a.input}'))

cmd_args = main_parser.parse_args()
cmd_args.func(cmd_args)

この方式により、ユーザーは script expand file.txt のように直感的な操作が可能になります。メインループ内で分岐処理を行う代わりに、各サブコマンドに対して関数をバインド（set_defaults）することで、コードの整理整頓を図ることができます。