Python 命令列之旅:深入 argparse(二)
作者:HelloGitHub-Prodesire
HelloGitHub 的《講解開源專案》系列,專案地址:https://github.com/HelloGitHub-Team/Article
前言
在上一篇“深入 argparse(一)”的文章中,我們深入瞭解了 argparse
的包括引數動作和引數類別在內的基本功能,具備了編寫一個簡單命令列程式的能力。本文將繼續深入瞭解 argparse
的進階玩法,一窺探其全貌,助力我們擁有實現複雜命令列程式的能力。
本系列文章預設使用 Python 3 作為直譯器進行講解。 若你仍在使用 Python 2,請注意兩者之間語法和庫的使用差異哦~
幫助
自動生成幫助
當你在命令列程式中指定 -h
或 --help
引數時,都會輸出幫助資訊。而 argparse
可通過指定 add_help
入參為 True
或不指定,以達到自動輸出幫助資訊的目的。
>>> import argparse >>> parser = argparse.ArgumentParser(add_help=True) >>> parser.add_argument('--foo') >>> parser.parse_args(['-h']) usage: [-h] [--foo FOO] optional arguments: -h, --help show this help message and exit --foo FOO
如果 add_help=False
,那麼在命令列中指定 -h
則會報錯:
>>> import argparse
>>> parser = argparse.ArgumentParser(add_help=False)
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-h'])
usage: [--foo FOO]
: error: unrecognized arguments: -h
自定義幫助
ArgumentParser
使用 formatter_class
比如,通過指定
formatter_class=argparse.RawTextHelpFormatter
,我們可以讓幫助內容遵循原始格式:
>>> import argparse
>>> parser = argparse.ArgumentParser(
... add_help=True,
... formatter_class=argparse.RawTextHelpFormatter,
... description="""
... description
... raw
... formatted"""
... )
>>> parser.add_argument(
... '-a', action="store_true",
... help="""argument
... raw
... formatted
... """
... )
>>>
>>> parser.parse_args(['-h'])
usage: [-h] [-a]
description
raw
formatted
optional arguments:
-h, --help show this help message and exit
-a argument
raw
formatted
對比下不指定 formatter_class
的幫助輸出,就可以發現 descirption 和 -a 兩個幫助內容上的差異:
>>> import argparse
>>> parser = argparse.ArgumentParser(
... add_help=True,
... description="""
... description
... notraw
... formatted"""
... )
>>> parser.add_argument(
... '-a', action="store_true",
... help="""argument
... notraw
... formatted
... """
... )
>>> parser.parse_args(['-h'])
usage: [-h] [-a]
description notraw formatted
optional arguments:
-h, --help show this help message and exit
-a argument notraw formatted
引數組
有時候,我們需要給引數分組,以使得在顯示幫助資訊時能夠顯示到一起。
比如某命令列支援三個引數選項 --user
、--password
和--push
,前兩者需要放在一個名為 authentication
的分組中以表示它們是身份認證資訊。那麼我們可以用 ArgumentParser.add_argument_group
來滿足:
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> group = parser.add_argument_group('authentication')
>>> group.add_argument('--user', action="store")
>>> group.add_argument('--password', action="store")
>>> parser.add_argument('--push', action='store')
>>> parser.parse_args(['-h'])
usage: [-h] [--user USER] [--password PASSWORD] [--push PUSH]
optional arguments:
-h, --help show this help message and exit
--push PUSH
authentication:
--user USER
--password PASSWORD
可以看到,當我們輸出幫助資訊時,--user
和 --password
選項都出現在 authentication
分組中。
選項引數字首
不知你是否注意到,在不同平臺上命令列程式的選項引數字首可能是不同的。比如在 Unix 上,其字首是 -
;而在 Windows 上,大多數命令列程式(比如 findstr
)的選項引數字首是 /
。
在 argparse
中,選項引數字首預設採用 Unix 命令列約定,也就是 -
。但它也支援自定義字首,下面是一個例子:
>>> import argparse
>>>
>>> parser = argparse.ArgumentParser(
... description='Option prefix',
... prefix_chars='-+/',
... )
>>>
>>> parser.add_argument('-power', action="store_false",
... default=None,
... help='Set power off',
... )
>>> parser.add_argument('+power', action="store_true",
... default=None,
... help='Set power on',
... )
>>> parser.add_argument('/win',
... action="store_true",
... default=False)
>>> parser.parse_args(['-power'])
Namespace(power=False, win=False)
>>> parser.parse_args(['+power', '/win'])
Namespace(power=True, win=True)
在這個例子中,我們指定了三個選項引數字首 -
、+
和/
,從而:
- 通過指定選項引數
-power
,使得power=False
- 通過指定選項引數
+power
,使得power=True
- 通過指定選項引數
/win
,使得win=True
共享解析器
有些時候我們需要共享解析器,以共享裡面的引數配置。比如,我們的命令列工具需要支援對阿里雲和 AWS 進行操作,兩類操作都需要指定 AccessKeyId
和 AccessKeySecret
來表明使用者身份和許可權。那麼共享解析器就顯得尤為必要,這樣就可以少去重複程式碼。
我們可以這樣做,在 base.py
中定義一個父解析器,存放 AccessKey
相關引數配置,作為公用的解析器。由於後續的子解析器會自動生成幫助資訊,這裡的父解析器指定 add_help=False
以不自動生成幫助資訊:
# bash.py
import argparse
parser = argparse.ArgumentParser(add_help=False)
parser.add_argument('--ak-id', action="store")
parser.add_argument('--ak-secret', action="store")
然後就可以分別在 ali.py
和 aws.py
中分別定義子解析器,通過 parents
入參指定上述父解析器,從而繼承公共的引數,並實現各自的引數:
# ali.py
import argparse
import base
parser = argparse.ArgumentParser(
parents=[base.parser],
)
parser.add_argument('--ros',
action="store_true",
default=False,
help='Using ROS service to orchestrate cloud resources')
print(parser.parse_args())
# aws.py
import argparse
import base
parser = argparse.ArgumentParser(
parents=[base.parser],
)
parser.add_argument('--cloudformation',
action="store_true",
default=False,
help='Using CloudFormation service to orchestrate cloud resources')
print(parser.parse_args())
最終通過 -h
引數分別看 ali.py
和 aws.py
所支援的引數,其中共同引數為 --ak-id
和 --ak-secret
,特定引數分別為 --ros
和 --cloudformation
:
$ python3 ali.py -h
usage: ali.py [-h] [--ak-id AK_ID] [--ak-secret AK_SECRET] [--ros]
optional arguments:
-h, --help show this help message and exit
--ak-id AK_ID
--ak-secret AK_SECRET
--ros Using ROS service to orchestrate cloud resources
$ python3 aws.py -h
usage: aws.py [-h] [--ak-id AK_ID] [--ak-secret AK_SECRET] [--cloudformation]
optional arguments:
-h, --help show this help message and exit
--ak-id AK_ID
--ak-secret AK_SECRET
--cloudformation Using CloudFormation service to orchestrate cloud
resources
巢狀解析器
我們之前介紹的命令列中,使用形式通常是 cli --a --b xxx
。但還有一種極為常見的命令列使用方式是 cli subcmd --a --b xxx
。比如當我們要通過 git
推送標籤時,會用到 git push --tags
。
通過實現巢狀解析器,我們可以很容易地對這種子命令的形式進行解析。
在巢狀解析器中,我們定義一個父解析器來作為整個命令列的入口,再分別定義N個子解析器來對應N個子命令,由此即可實現整個功能。
在下面這個例子中,我們支援 create
和 delete
兩個子命令,用來建立或刪除指定路徑。而 delete
命令支援 --recursive
引數來表明是否遞迴刪除指定路徑:
# cli.py
import argparse
parser = argparse.ArgumentParser()
subparsers = parser.add_subparsers(help='commands')
# Create
create_parser = subparsers.add_parser(
'create', help='Create a directory')
create_parser.add_argument(
'dirname', action='store',
help='New directory to create')
# Delete
delete_parser = subparsers.add_parser(
'delete', help='Remove a directory')
delete_parser.add_argument(
'dirname', action='store', help='The directory to remove')
delete_parser.add_argument(
'--recursive', '-r', default=False, action='store_true',
help='Recursively remove the directory',
)
print(parser.parse_args())
直接指定 -h
來檢視所支援的子命令和引數選項:
$ python3 cli.py -h
usage: cli.py [-h] {create,delete} ...
positional arguments:
{create,delete} commands
create Create a directory
delete Remove a directory
optional arguments:
-h, --help show this help message and exit
直接指定 delete -h
來檢視 delete
子命令支援的引數選項:
$ python3 cli.py delete -h
usage: cli.py delete [-h] [--recursive] dirname
positional arguments:
dirname The directory to remove
optional arguments:
-h, --help show this help message and exit
--recursive, -r Recursively remove the directory
自定義動作
在上一篇“深入 argparse (一)”的文章中介紹過8種引數動作,可以說是覆蓋了絕大部分場景。但是也會有一些特定需求無法被滿足,比如希望獲取到的引數值都是大寫。在這種情況下,自定義動作就派上了用場。
實現一個自定義動作類,需繼承自 argparse.Action
,這個自定義動作類要傳入到 ArgumentParser.add_argument
的 action
入參。當解析器解析引數時,會呼叫該類的 __call__
方法,該方法的簽名為 __call__(self, parser, namespace, values, option_string=None)
,其中:
- parser 為解析器例項
- namespace 存放解析結果
- values 即命令列中傳入的引數值
- option_string 為引數選項
在下面的例子中,我們通過 --words
傳入單詞,並在自定義動作類中將其值轉換為大寫:
# cli.py
import argparse
class WordsAction(argparse.Action):
def __call__(self, parser, namespace, values,
option_string=None):
print(f'parser = {parser}')
print(f'values = {values!r}')
print(f'option_string = {option_string!r}')
values = [v.upper() for v in values]
setattr(namespace, self.dest, values)
parser = argparse.ArgumentParser()
parser.add_argument('--words', nargs='*', action=WordsAction)
results = parser.parse_args()
print(results)
$ python3 cli.py --words foo bar
parser = ArgumentParser(prog='cli.py', usage=None, description=None, formatter_class=<class 'argparse.HelpFormatter'>, conflict_handler='error', add_help=True)
values = ['foo', 'bar']
option_string = '--words'
Namespace(words=['FOO', 'BAR'])
小節
通過對 argparse
由淺入深的介紹,相信你已經全面瞭解了 argparse
的威力,也具備了開發命令列工具的能力。但“紙上得來終覺淺,絕知此事要躬行”。
在下篇文章中,將帶大家一起用 argparse
實現日常工作中常見的 git
命令,想想是不是有些興奮呢