📝 はじめに
Python でコマンドラインツールを作るときに欠かせないのが argparse です。
標準ライブラリなので追加インストール不要、しかも -h で自動的にヘルプを生成してくれる便利な仕組みです。
この記事では 初心者向けに、argparseの使い方を基礎から応用まで 網羅的に解説します。
1. argparseの基本構造
import argparse
parser = argparse.ArgumentParser(description="サンプルプログラム")
parser.add_argument("filename", help="処理するファイル名")
args = parser.parse_args()
print(f"指定されたファイル: {args.filename}")実行：
python sample.py report.txt
# => 指定されたファイル: report.txt👉 ArgumentParser(description=...) は -h 実行時に冒頭に出る説明文です。
2. オプション引数の追加
parser.add_argument("--outdir", default="out", help="出力先ディレクトリ")実行：
python sample.py report.txt --outdir results出力：
指定されたファイル: report.txt
出力先ディレクトリ: results👉 --outdir を省略すると default="out" が使われます。
3. 型の指定とフラグ
parser.add_argument("--repeat", type=int, default=1, help="繰り返し回数")
parser.add_argument("--verbose", action="store_true", help="詳細表示を有効化")実行例：
python sample.py report.txt --repeat 3 --verbose👉 args.repeat は整数、args.verbose は True/False になります。
4. 複数の値を受け取る（nargs）
parser.add_argument("--nums", nargs="+", type=int, help="数値を1つ以上指定")実行：
python sample.py report.txt --nums 1 2 3
# args.nums = [1, 2, 3]nargs="+"→ 1個以上nargs="*"→ 0個以上nargs=2→ ちょうど2個
5. 必須オプション
parser.add_argument("--config", required=True, help="設定ファイル（必須）")実行：
python sample.py
# => error: the following arguments are required: --config👉 required=True を付けると、指定しなければエラーになります。
6. 短縮形と長い形を両立する
parser.add_argument("-f", "--files", nargs="+", help="入力ファイルを指定")実行：
python sample.py -f a.txt b.txt
python sample.py --files a.txt b.txt👉 両方同じ args.files に入ります。
7. choicesで入力を制限する
parser.add_argument(
"--mode",
choices=["fast", "normal", "slow"],
help="処理モードを選択"
)実行：
python sample.py --mode fast # OK
python sample.py --mode debug # エラー👉 ユーザーの入力ミスを防げます。
数値なら choices=range(1, 11) のように範囲で指定することも可能です。
8. サブコマンド形式（git風）
git add, git commit のように、サブコマンドごとに処理を分けることもできます。
import argparse
def cmd_hello(args):
print(f"Hello, {args.name}!")
def cmd_sum(args):
print(sum(args.nums))
parser = argparse.ArgumentParser(prog="foo", description="サブコマンド例")
subparsers = parser.add_subparsers(dest="command")
# foo hello --name Alice
p_hello = subparsers.add_parser("hello", help="あいさつする")
p_hello.add_argument("--name", required=True)
p_hello.set_defaults(func=cmd_hello)
# foo sum 1 2 3
p_sum = subparsers.add_parser("sum", help="合計する")
p_sum.add_argument("nums", nargs="+", type=int)
p_sum.set_defaults(func=cmd_sum)
args = parser.parse_args()
if not hasattr(args, "func"):
parser.print_help(); parser.exit(2)
args.func(args)実行例：
python foo.py hello --name Alice
# => Hello, Alice!
python foo.py sum 1 2 3
# => 69. -h オプションの自動生成
argparse は -h / --help を自動追加します。description と help="..." がここに反映されるので、必ず書きましょう。
例：
python sample.py -h
usage: sample.py [-h] [--outdir OUTDIR] [--repeat REPEAT] filename
サンプルプログラム
positional arguments:
filename 処理するファイル
optional arguments:
-h, --help show this help message and exit
--outdir OUTDIR 出力先ディレクトリ
--repeat REPEAT 繰り返し回数✅ まとめ
add_argument("name")→ 必須の位置引数add_argument("--option")→ オプション引数type=int,default=...,required=True,nargs="+"などで細かく指定可能-fと--filesのように短縮形と長い形を両立できるchoices=[...]で入力値を制限できるadd_subparsers()で git風のサブコマンドも実現できる-hで自動ヘルプが生成される
👉 argparse をマスターすれば、自分のスクリプトを 実用的なCLIツール に進化させられます！
