`argparse` --- 命令列選項、引數和子命令的剖析器¶

在 3.2 版被加入.

備註

雖然 argparse 是實作基本命令列應用程式時預設推薦的標準函式庫模組，但如果開發者對命令列應用程式的行為有更精確的要求，可能會發現它無法提供足夠的控制程度。當 argparse 不支援應用程式所需的行為時（例如完全停用交錯選項與位置引數的支援，或是允許以 - 開頭但可能與其他已定義選項相同的選項參數值），請參閱選擇一個命令列參數剖析函式庫以了解替代方案。

argparse 模組使得撰寫使用者友善的命令列介面變得容易。程式定義它需要什麼引數，而 argparse 會找出如何從 sys.argv 中剖析這些引數。argparse 模組也會自動產生說明和用法訊息。當使用者向程式提供無效引數時，此模組也會發出錯誤。

argparse 模組對命令列介面的支援是圍繞 argparse.ArgumentParser 的實例建構的。它是引數規格的容器，並具有適用於整個剖析器的選項：

parser = argparse.ArgumentParser(
                    prog='ProgramName',
                    description='What the program does',
                    epilog='Text at the bottom of help')

ArgumentParser.add_argument() 方法會將個別的引數規格附加到剖析器。它支援位置引數、接受值的選項以及開關旗標：:

parser.add_argument('filename')           # 位置引數
parser.add_argument('-c', '--count')      # 接收一個值的選項
parser.add_argument('-v', '--verbose',
                    action='store_true')  # 開關旗標

ArgumentParser.parse_args() 方法會執行剖析器，並將擷取的資料放入一個 argparse.Namespace 物件中：:

args = parser.parse_args()
print(args.filename, args.count, args.verbose)

備註

如果你在尋找如何將 optparse 程式碼升級到 argparse 的指南，請參閱升級 Optparse 程式碼。

ArgumentParser 物件¶

class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True, *, suggest_on_error=False, color=True)¶

建立一個新的 ArgumentParser 物件。所有參數都應該作為關鍵字引數傳入。每個參數在下面都有更詳細的描述，簡而言之它們是：

prog - 程式的名稱（預設值：從 __main__ 模組屬性和 sys.argv[0] 產生）
usage - 描述程式用法的字串（預設值：從新增到剖析器的引數產生）
description - 引數說明之前要顯示的文字（預設值：無文字）
epilog - 引數說明之後要顯示的文字（預設值：無文字）
parents - 一個 ArgumentParser 物件的串列，其引數也應該被包含
formatter_class - 用於自訂幫助說明輸出的類別
prefix_chars - 前綴可選引數的字元集合（預設值：'-'）
fromfile_prefix_chars - 前綴檔案的字元集合，額外引數將從這些檔案中讀取（預設值：None）
argument_default - 引數的全域預設值（預設值：None）
conflict_handler - 解決衝突可選引數的策略（通常不需要）
add_help - 加入一個 -h/--help 選項到剖析器（預設值：True）
allow_abbrev - 允許長選項被縮寫，只要縮寫是無歧義的（預設值：True）
exit_on_error - 決定 ArgumentParser 在發生錯誤時是否帶著錯誤資訊退出。（預設值：True）
suggest_on_error - 啟用對拼錯的引數選擇和子剖析器名稱的建議（預設值：False）
color - 允許彩色輸出（預設值：True）

在 3.5 版的變更: 新增 allow_abbrev 參數。

在 3.8 版的變更: 在之前的版本中，allow_abbrev 也會停用短旗標的分組，例如以 -vv 表示 -v -v。

在 3.9 版的變更: 新增 exit_on_error 參數。

在 3.14 版的變更: 新增 suggest_on_error 和 color 參數。

以下各節描述了這些參數的使用方式。

prog¶

預設情況下，ArgumentParser 會根據 Python 直譯器的執行方式計算要在說明訊息中顯示的程式名稱：

如果傳入的引數是一個檔案，則使用 sys.argv[0] 的基底名稱。
如果傳入的引數是一個目錄或 zip 檔案，則使用 Python 直譯器名稱加上 sys.argv[0]。
如果使用了 -m 選項，則使用 Python 直譯器名稱加上 -m 再加上模組或套件名稱。

這個預設值幾乎都不會錯，因為它會使說明訊息與命令列上呼叫程式時所用的字串一致。然而，若要更改此預設行為，可以使用 ArgumentParser 的 prog= 引數提供另一個值：

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]

options:
 -h, --help  show this help message and exit

請注意，無論程式名稱是從 sys.argv[0]、從 __main__ 模組屬性還是從 prog= 引數決定的，都可以在說明訊息中透過 %(prog)s 格式說明符號使用。

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo of the myprogram program

在 3.14 版的變更: 預設的 prog 值現在會反映 __main__ 實際的執行方式，而非總是使用 os.path.basename(sys.argv[0])。

usage¶

預設情況下，ArgumentParser 會根據它包含的引數計算出用法訊息。可以使用 usage= 關鍵字引數覆寫預設訊息：

>>> parser = argparse.ArgumentParser(

argparse --- 命令列選項、引數和子命令的剖析器¶

ArgumentParser 物件¶

prog¶

usage¶

`argparse` --- 命令列選項、引數和子命令的剖析器¶