萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

Python argparse 完整實戰:從入門到生產級命令列介面設計

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)

最佳實踐清單

  1. 使用 ArgumentDefaultsHelpFormatter 自動顯示預設值
  2. 位置參數用於必要輸入,可選參數用於修飾行為
  3. nargs='+' (至少一個) 優於 nargs='*' (零或多個)
  4. type=Path 直接回傳 pathlib.Path 物件
  5. choices 限制輸入範圍,自動產生錯誤訊息
  6. 互斥群組管理衝突選項
  7. 主函式回傳 int 狀態碼,sys.exit(main())
  8. 支援 @args.txt 解決命令列長度限制
  9. 整合 argcomplete 提供 Tab 自動完成
copyright © 萬盛學電腦網 all rights reserved