Pythonの `sys` をCLI処理で使う基本を整理します

結論から言うと、sys はPythonの実行環境に関係する情報や、コマンドライン引数、終了処理を扱うための標準ライブラリです。

Pythonで小さな自動化ツールを作ると、コマンドラインからファイル名や設定値を渡したくなることがあります。
その入口として使えるのが sys.argv です。
この記事では、名前を受け取って簡単なメッセージを表示するCLIツールを例に、sys の基本を整理します。

この記事でわかること

完成コード

完成コードは次の通りです。

import sys


def build_message(name: str, count_text: str) -> str:
    try:
        count = int(count_text)
    except ValueError as error:
        raise ValueError("回数は整数で指定してください") from error

    if count <= 0:
        raise ValueError("回数は1以上で指定してください")

    return "\n".join(f"{name}さん、こんにちは" for _ in range(count))


def main(argv: list[str]) -> int:
    if len(argv) != 3:
        print("使い方: python greet.py 名前 回数", file=sys.stderr)
        return 1

    try:
        message = build_message(argv[1], argv[2])
    except ValueError as error:
        print(f"エラー: {error}", file=sys.stderr)
        return 1

    print(message)
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

このコードを greet.py として保存した場合、次のように実行できます。

python greet.py 田中 2

コードのポイント

このコードでは、コマンドライン引数を受け取り、問題があればエラーとして終了する流れを作っています。

• sys.argv でコマンドライン引数を受け取っています
• 引数の数が合わない場合は使い方を表示しています
• エラーメッセージは sys.stderr に出しています
• main() は終了コードとして 0 または 1 を返しています
• sys.exit() で終了コードをPythonの外側へ返しています

CLI処理では、正常終了と異常終了を区別できることが大切です。
終了コードを返す形にしておくと、他のスクリプトや自動実行からも扱いやすくなります。

コードを順番に説明します

主要な処理を分けて説明します。

1. sys.argvで引数を受け取ります

def main(argv: list[str]) -> int:
    if len(argv) != 3:
        print("使い方: python greet.py 名前 回数", file=sys.stderr)
        return 1

sys.argv には、コマンドラインで渡された値がリストとして入ります。
最初の要素 argv[0] には、実行したスクリプト名が入ります。
そのため、python greet.py 田中 2 と実行した場合、名前は argv[1]、回数は argv[2] になります。

引数が足りない場合や多すぎる場合は、処理を続けずに使い方を表示しています。
CLIツールでは、入力が想定と違うときに早めに止めると原因を見つけやすくなります。

2. 文字列の引数を必要な型に変換します

try:
    count = int(count_text)
except ValueError as error:
    raise ValueError("回数は整数で指定してください") from error

コマンドライン引数は、基本的に文字列として渡されます。
数字として使いたい場合は、int() などで変換する必要があります。

ここでは、回数を整数に変換しています。
変換できない文字列が渡された場合は ValueError になるため、分かりやすいメッセージに変えて呼び出し元へ伝えています。

3. エラーを標準エラー出力に出します

print(f"エラー: {error}", file=sys.stderr)
return 1

print() は通常、標準出力に文字を出します。
file=sys.stderr を指定すると、エラーメッセージとして標準エラー出力に出せます。

実務では、正常な出力とエラー出力を分けたい場面があります。
たとえば、正常な処理結果をファイルへリダイレクトし、エラーだけを画面に出したい場合です。

4. sys.exitで終了コードを返します

if __name__ == "__main__":
    sys.exit(main(sys.argv))

sys.exit() は、Pythonプログラムを終了するために使います。
0 を渡すと正常終了、1 などの0以外を渡すと異常終了として扱われます。

main() が終了コードを返し、最後に sys.exit() へ渡す形にしておくと、処理の見通しがよくなります。
テストを書く場合も、main() を直接呼び出して戻り値を確認しやすくなります。

実務で使うときのポイント

実務で少し本格的なCLIツールを作る場合は、引数が増えすぎる前に argparse の利用も検討します。
sys.argv は仕組みを理解する入口として分かりやすく、少数の引数だけを扱う小さなツールに向いています。

CLI処理では、正常な結果を標準出力へ、エラーや使い方を標準エラー出力へ出すと扱いやすくなります。
また、成功なら 0、失敗なら 1 のように終了コードを分けると、自動実行やバッチ処理から結果を判断できます。

第6章で扱った pathlib や datetime と組み合わせると、コマンドラインから入力ファイルや日付を受け取る小さなツールを作れます。
最初は sys.argv で流れを理解し、引数が複雑になったら専用ライブラリへ進むと無理がありません。

よくある勘違い・注意点

まとめ