Python argparse 命令列參數解析

如果你想開發專業的命令列工具 (CLI)，單靠 sys.argv 手動解析參數會非常痛苦。Python 內建的 argparse 模組能自動生成說明手冊 (Help Menu)、解析參數類型，並在使用者輸入錯誤時給予提示。

基本範例

讓我們建立一個能接收名字並列印問候語的腳本。

import argparse

# 1. 建立解析器物件
parser = argparse.ArgumentParser(description="這是一個簡單的問候工具")

# 2. 定義位置參數 (Positional Argument)
# 位置參數是必填的，且順序固定
parser.add_argument("name", help="你的名字")

# 3. 解析參數
args = parser.parse_args()

# 4. 使用參數
print(f"你好, {args.name}!")

執行方式：

python main.py 小明
# 輸出: 你好, 小明!

python main.py --help
# 輸出: 顯示詳細的使用手冊

常見參數類型

選項參數 (Optional Arguments)

選項參數通常以 -- 開頭，不限制位置，且可以給予預設值。

import argparse

parser = argparse.ArgumentParser()

# 必填位置參數
parser.add_argument("x", type=int, help="數字 X")

# 選項參數
parser.add_argument("--y", type=int, default=10, help="數字 Y (預設 10)")

# 布林開關 (Flag)
# 使用 action="store_true"，輸入該參數時會變為 True，否則為 False
parser.add_argument("-v", "--verbose", action="store_true", help="顯示詳細資訊")

args = parser.parse_args()

result = args.x * args.y
print(f"計算結果: {result}")

if args.verbose:
    print(f"計算過程: {args.x} 乘以 {args.y}")

多選一選擇 (Choices)

限制使用者只能輸入特定的值。

parser.add_argument("--mode", choices=['easy', 'hard'], default='easy')

實務案例：簡易檔案計算器

假設我們要寫一個工具，可以計算傳入檔案的行數或字數：

import argparse
import os

def main():
    parser = argparse.ArgumentParser(description="檔案分析工具")

    parser.add_argument("path", help="檔案路徑")
    parser.add_argument("-l", "--lines", action="store_true", help="計算行數")
    parser.add_argument("-w", "--words", action="store_true", help="計算字數")

    args = parser.parse_args()

    if not os.path.exists(args.path):
        print(f"錯誤: 找不到檔案 {args.path}")
        return

    with open(args.path, 'r', encoding='utf-8') as f:
        content = f.read()

        if args.lines:
            print(f"行數: {len(content.splitlines())}")
        if args.words:
            print(f"字數: {len(content.split())}")

        if not args.lines and not args.words:
            print(f"檔案大小: {len(content)} bytes")

if __name__ == "__main__":
    main()

總結

argparse 讓你的腳本具備專業 CLI 的風範：

• 自動生成 -h 或 --help 文件。
• 強制檢查參數類型 (type=int) 與合法值 (choices)。
• 處理長短參數名（例如 -v 與 --verbose）。

即便你只是寫給自己用的小工具，使用 argparse 也能讓你在幾個月後重新打開腳本時，依然知道該如何使用它。