Pythonで高機能なコマンドラインツールを作る：argparseモジュールの使い方

単純にコマンドライン引数をリストとして受け取る sys.argv とは異なり、Pythonの標準ライブラリ argparse を使用すると、「ヘルプメッセージの自動生成」「引数の型チェック」「オプション引数の処理」といった高度な機能を簡単に実装できます。

本格的なコマンドラインツールを作成する場合、このモジュールの利用が推奨されます。

この記事では、argparse を使って、2つの数値と演算子を受け取る計算ツールを作成する方法を解説します。

argparse の基本的な流れ

argparse を使う手順は、大きく分けて以下の3ステップです。

1. パーサーの作成: ArgumentParser オブジェクトを作成します。
2. 引数の設定: add_argument() メソッドで、どのような引数を受け取るか（名前、型、ヘルプなど）を定義します。
3. 引数の解析: parse_args() メソッドを実行し、コマンドラインから渡された値を解析して取得します。

実践的なコード例：簡易計算ツール

ユーザーから「2つの数値（必須）」と「演算子（任意）」を受け取って計算するツール calc_tool.py を作成します。

import argparse

def main():
    # 1. パーサーの作成
    # description引数に指定した文字列は、ヘルプ表示時にツールの説明として表示されます
    parser = argparse.ArgumentParser(description="2つの数値を指定した演算子で計算します")

    # 2. 引数の設定
    
    # 位置引数（必須）: 名前だけで定義する
    # type=float を指定すると、受け取った文字列を自動的に数値に変換します
    parser.add_argument("num1", type=float, help="1番目の数値")
    parser.add_argument("num2", type=float, help="2番目の数値")

    # オプション引数（任意）: 先頭に -- や - を付ける
    # default: 指定されなかった場合に使用される値
    # choices: 受け取る値を特定のリストに制限する（これ以外はエラーになる）
    parser.add_argument("--operator", "-o", type=str, default="+",
                        choices=["+", "-", "*", "/"],
                        help="演算子 (+, -, *, /) を指定。デフォルトは足し算")

    # 3. 引数の解析
    # コマンドライン引数が解析され、結果が args オブジェクトに格納される
    args = parser.parse_args()

    # --- メイン処理 ---
    # args.引数名 で値にアクセスできる
    n1 = args.num1
    n2 = args.num2
    op = args.operator
    result = 0

    # 演算子に応じた計算処理
    if op == "+":
        result = n1 + n2
    elif op == "-":
        result = n1 - n2
    elif op == "*":
        result = n1 * n2
    elif op == "/":
        if n2 == 0:
            print("エラー: ゼロ除算はできません")
            return
        result = n1 / n2

    print(f"計算結果: {n1} {op} {n2} = {result}")

if __name__ == "__main__":
    main()

add_argument の主要なパラメータ

• 位置引数 ("name"): コマンドラインで必ず指定しなければならない引数です。定義した順番通りに解釈されます。
• オプション引数 ("--name", "-n"): 指定しなくてもよい引数です。名前の前にハイフンを付けます。
• type: 受け取る値の型を指定します。int や float を指定すると、自動的に型変換と入力値の検証が行われます。
• default: オプション引数がコマンドラインで指定されなかった場合に使用されるデフォルト値です。
• choices: 入力可能な値をリストで指定します。リストに含まれない値が入力されると、自動的にエラーメッセージを表示して終了します。
• help: ヘルプメッセージ（-h）を表示した際に、その引数の説明として表示される文字列です。

実行方法と結果

ターミナル（コマンドプロンプト）でスクリプトを実行し、動作を確認します。

1. ヘルプを表示する (-h または --help)

argparse は、定義に基づいてヘルプメッセージを自動生成します。

python calc_tool.py -h

実行結果:

usage: calc_tool.py [-h] [--operator {+,-,*,/}] num1 num2

2つの数値を指定した演算子で計算します

positional arguments:
  num1                  1番目の数値
  num2                  2番目の数値

options:
  -h, --help            show this help message and exit
  --operator {+,-,*,/}, -o {+,-,*,/}
                        演算子 (+, -, *, /) を指定。デフォルトは足し算

2. 基本的な実行（必須引数のみ）

位置引数のみを指定して実行します。オプション引数は省略されているため、デフォルト値（+）が適用されます。

python calc_tool.py 10 5

実行結果:

計算結果: 10.0 + 5.0 = 15.0

3. オプションを指定して実行

オプション引数 --operator（またはショートオプション -o）を使って演算子を指定します。

python calc_tool.py 10 5 --operator "*"

または

python calc_tool.py 10 5 -o "*"

（* はシェルによってワイルドカードとして展開される可能性があるため、クォートで囲むことを推奨します。）

実行結果:

計算結果: 10.0 * 5.0 = 50.0

4. エラー処理（型違いや選択肢外）

数字ではない値を渡したり、choices に含まれない演算子を渡したりすると、自動的にエラーになります。

python calc_tool.py 10 abc

実行結果:

usage: calc_tool.py [-h] [--operator {+,-,*,/}] num1 num2
calc_tool.py: error: argument num2: invalid float value: 'abc'

まとめ

• コマンドライン引数を扱うには、標準ライブラリの argparse が非常に便利です。
• ArgumentParser を作成し、add_argument で引数を定義するだけで、型変換、入力値チェック、ヘルプ生成を自動化できます。
• 必須の「位置引数」と任意の「オプション引数」を適切に使い分けることで、ユーザーフレンドリーなツールを作成できます。