ArgumentParser 核心參數
import argparse
parser = argparse.ArgumentParser(
description="專案描述 (顯示在 -h 頂部)",
epilog="結尾說明 (顯示在 -h 底部)",
prog="mytool", # 程式名 (預設 sys.argv[0])
formatter_class=argparse.ArgumentDefaultsHelpFormatter, # 顯示預設值
prefix_chars='-+', # 支援 - 和 + 作為選項前綴
fromfile_prefix_chars='@', # 支援 @args.txt 從檔案讀取參數
allow_abbrev=True, # 允許縮寫選項 (--ver 代替 --version)
)
add_argument 完整參數解析
parser.add_argument(
'-f', '--file', # 選項名稱 (短/長)
action='store', # 動作: store/store_true/append/count/version/help
nargs='+', # 參數個數: N/?/*/+/argparse.REMAINDER
const=42, # 配合 nargs='?' 或 action='store_const'
default='default.txt', # 預設值
type=Path, # 型別轉換器 (可呼叫物件)
choices=['a', 'b', 'c'], # 允許值列表
required=False, # 是否必填 (位置參數預設 True)
help='輸入檔案路徑', # 說明文字
metavar='FILE', # 使用說明中顯示的參數名
dest='input_file', # 命名空間屬性名 (預設由選項推導)
)
實戰範例:功能完整的 CLI 工具
#!/usr/bin/env python3
import argparse
import sys
from pathlib import Path
from typing import List
def create_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description="檔案處理工具示範",
formatter_class=argparse.ArgumentDefaultsHelpFormatter
)
# 位置參數 (必填,順序固定)
parser.add_argument(
'inputs', nargs='+', type=Path,
help='輸入檔案/目錄路徑'
)
# 可選參數
parser.add_argument(
'-o', '--output', type=Path, default=Path.cwd() / 'output',
help='輸出目錄'
)
parser.add_argument(
'-r', '--recursive', action='store_true',
help='遞迴處理子目錄'
)
parser.add_argument(
'-e', '--ext', nargs='+', default=['.txt', '.md'],
help='處理的副檔名列表'
)
parser.add_argument(
'-j', '--jobs', type=int, default=4, choices=range(1, 17),
metavar='[1-16]', help='平行處理程序數'
)
parser.add_argument(
'--dry-run', action='store_true',
help='僅顯示將執行操作,不實際執行'
)
parser.add_argument(
'-v', '--verbose', action='count', default=0,
help='詳細輸出 (-v, -vv, -vvv)'
)
parser.add_argument(
'--version', action='version', version='%(prog)s 2.1.0'
)
# 互斥群組
group = parser.add_mutually_exclusive_group()
group.add_argument('--upper', action='store_true', help='轉大寫')
group.add_argument('--lower', action='store_true', help='轉小寫')
return parser
def main(argv: List[str] = None) -> int:
parser = create_parser()
args = parser.parse_args(argv)
# 參數後處理/驗證
if args.verbose >= 2:
print(f"除錯模式: {args}")
# 實際業務邏輯...
print(f"處理 {len(args.inputs)} 個輸入 -> {args.output}")
return 0
if __name__ == '__main__':
sys.exit(main())
進階技巧
1. 子命令
subparsers = parser.add_subparsers(dest='command', required=True)
# 子命令: process
proc = subparsers.add_parser('process', help='處理檔案')
proc.add_argument('files', nargs='+')
# 子命令: config
cfg = subparsers.add_parser('config', help='設定管理')
cfg.add_argument('--set', nargs=2, metavar=('KEY', 'VALUE'))
# 使用: mytool process a.txt b.txt
# mytool config --set key value
2. 自訂型別驗證
def positive_int(value):
ivalue = int(value)
if ivalue <= 0:
raise argparse.ArgumentTypeError(f"{value} 必須為正整數")
return ivalue
parser.add_argument('--count', type=positive_int)
# 路徑驗證
def existing_file(path):
p = Path(path)
if not p.exists():
raise argparse.ArgumentTypeError(f"檔案不存在: {path}")
return p
3. 從檔案讀取參數 (@args.txt)
# args.txt 內容 (每行一參數,支援註釋)
# --output /tmp/out
--recursive
--ext .py .js
# 命令列
python tool.py @args.txt input_dir
4. 完整殼層自動完成 (bash/zsh/fish)
# 產生完成腳本
python -m argcomplete --generate-bash-completion mytool > /etc/bash_completion.d/mytool
# 在工具腳本開頭加入
import argcomplete
argcomplete.autocomplete(parser)
最佳實踐清單
- 使用
ArgumentDefaultsHelpFormatter 自動顯示預設值
- 位置參數用於必要輸入,可選參數用於修飾行為
nargs='+' (至少一個) 優於 nargs='*' (零或多個)
type=Path 直接回傳 pathlib.Path 物件
choices 限制輸入範圍,自動產生錯誤訊息
- 互斥群組管理衝突選項
- 主函式回傳
int 狀態碼,sys.exit(main())
- 支援
@args.txt 解決命令列長度限制
- 整合
argcomplete 提供 Tab 自動完成