Python 命令列之旅:使用 argparse 實現 git 命令

語言: CN / TW / HK

:point_up_2:  Python貓 ” ,一個值得加星標的 公眾號

劇照 | 《仙劍奇俠傳》

在前面三篇介紹 argparse 的文章中,我們全面瞭解了 argparse 的能力,相信不少小夥伴們都已經摩拳擦掌,想要打造一個屬於自己的命令列工具。

本文將以我們日常工作中最常見的 git 命令為例,講解如何使用 argparse 庫來實現一個真正可用的命令列程式。

本系列文章預設使用 Python 3 作為直譯器進行講解。

若你仍在使用 Python 2,請注意兩者之間語法和庫的使用差異哦~

git 常用命令

大家不妨回憶一下,平時最常使用 git 子命令都有哪些?

當你寫好一段程式碼或增刪一些檔案後,會用如下命令檢視檔案狀態:

git status

確認檔案狀態後,會用如下命令將的一個或多個檔案(夾)新增到暫存區:

git add [pathspec [pathspec ...]]

然後使用如下命令提交資訊:

git commit -m "your commit message"

最後使用如下命令將提交推送到遠端倉庫:

git push

我們將使用 argparsegitpython 庫來實現這 4 個子命令。

關於 gitpython

gitpython [1] 是一個和 git 倉庫互動的 Python 第三方庫。我們將借用它的能力來實現真正的 git 邏輯。

安裝:

pip install gitpython

思考

在實現前,我們不妨先思考下會用到 argparse 的哪些功能?整個程式的結構是怎樣的?

argparse

  • 要實現子命令,那麼之前介紹到的 巢狀解析器 必不可少

  • 當用戶鍵入子命令時,子命令所對應的子解析器需要作出響應,那麼需要用到子解析器的 set_defaults 功能

  • 針對 git add [pathspec [pathspec ...]] ,我們需要實現位置引數,而且數量是任意個

  • 針對 git commit --message msggit commit -m msg ,我們需要實現選項引數,且即可長選項,又可短選項

程式結構

  • 命令列程式需要一個 cli 函式來作為統一的入口,它負責構建解析器,並解析命令列引數

  • 我們還需要四個 handle_xxx 函式響應對應的子命令

則基本結構如下:

import os

import argparse

from git.cmd import Git



def cli():

"""

git 命名程式入口

"""

pass



def handle_status(git, args):

"""

處理 status 命令

"""

pass


def handle_add(git, args):

"""

處理 add 命令

"""

pass



def handle_commit(git, args):

"""

處理 -m <msg> 命令

"""

pass



def handle_push(git, args):

"""

處理 push 命令

"""

pass



if __name__ == '__main__':

cli()

下面我們將一步步地實現我們的 git 程式。

實現

假定我們在 argparse-git.py [2] 檔案中實現我們的 git 程式。

構建解析器

我們需要構建一個父解析器,作為程式的根解析器,程式名稱指定為 git 。然後在上面新增子解析器,為後續的子命令的解析做準備:

def cli():

"""

git 命名程式入口

"""

parser = argparse.ArgumentParser(prog='git')

subparsers = parser.add_subparsers(

title='These are common Git commands used in various situations',

metavar='command')

add_subparsers 中的 titlemetavar 引數主要用於命令列幫助資訊,最終的效果如下:

usage: git [-h] command ...


optional arguments:

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


These are common Git commands used in various situations:

command

...

status 子命令

我們需要在 cli 函式中新增一個用於解析 status 命令的子解析器 status_parser ,並指定其對應的處理函式為 handle_status

def cli():

...

# status

status_parser = subparsers.add_parser(

'status',

help='Show the working tree status')

status_parser.set_defaults(handle=handle_status)

需要說明的是,在 status_parser.set_defaults 函式中,能接收任意名稱的關鍵字引數,這個引數值會存放於父解析器解析命令列引數後的變數中。

比如,在本文示例程式中,我們為每個子解析器定義了 handle ,那麼 args = parser.parse_args() 中的 args 將具有 handle 屬性,我們傳入不同的子命令,那麼這個 handle 就是不同的響應函式。

定義了 status 的子解析器後,我們再實現下 handle_status 即可實現 status 命令的響應:

def handle_status(git, args):

"""

處理 status 命令

"""

cmd = ['git', 'status']

output = git.execute(cmd)

print(output)

不難看出,我們最後呼叫了真正的 git status 來實現,並列印了輸出。

你可能會對 handle_status 的函式簽名感到困惑,這裡的 gitargs 是怎麼傳入的呢?這其實是由我們自己控制的,將在本文最後講解。

add 子命令

同樣,我們需要在 cli 函式中新增一個用於解析 add 命令的子解析器 add_parser ,並指定其對應的處理函式為 handle_add

額外要做的是,要在子解析器 add_parser 上新增一個 pathspec 位置引數,且其數量是任意的:

def cli():

...

# add

add_parser = subparsers.add_parser(

'add',

help='Add file contents to the index')

add_parser.add_argument(

'pathspec',

help='Files to add content from',

nargs='*')

add_parser.set_defaults(handle=handle_add)

然後,就是實現 handle_add 函式,我們需要用到表示檔案路徑的 args.pathspec

def handle_add(git, args):

"""

處理 add 命令

"""

cmd = ['git', 'add'] + args.pathspec

output = git.execute(cmd)

print(output)

commit 子命令

同樣,我們需要在 cli 函式中新增一個用於解析 commit 命令的子解析器 commit_parser ,並指定其對應的處理函式為 handle_commit

額外要做的是,要在子解析器 commit_parser 上新增一個 -m / --message 選項引數,且要求必填:

def cli():

...

# commit

commit_parser = subparsers.add_parser(

'commit',

help='Record changes to the repository')

commit_parser.add_argument(

'--message', '-m',

help='Use the given <msg> as the commit message',

metavar='msg',

required=True)

commit_parser.set_defaults(handle=handle_commit)

然後,就是實現 handle_commit 函式,我們需要用到表示提交資訊的 args.message

def handle_commit(git, args):

"""

處理 -m <msg> 命令

"""

cmd = ['git', 'commit', '-m', args.message]

output = git.execute(cmd)

print(output)

push 子命令

同樣,我們需要在 cli 函式中新增一個用於解析 push 命令的子解析器 push_parser ,並指定其對應的處理函式為 handle_push

它同 status 子命令的實現方式一致:

def cli():

...

# push

push_parser = subparsers.add_parser(

'push',

help='Update remote refs along with associated objects')

push_parser.set_defaults(handle=handle_push)

然後,就是實現 handle_push 函式,和 handle_status 類似:

def handle_push(git, args):

cmd = ['git', 'push']

output = git.execute(cmd)

print(output)

解析引數

在定義完父子解析器,並新增引數後,我們就需要對引數做解析,這項工作也是實現在 cli 函式中:

def cli():

...

git = Git(os.getcwd())

args = parser.parse_args()

if hasattr(args, 'handle'):

args.handle(git, args)

else:

parser.print_help()

  • 通過 git.cmd.Git 例項化出 git 物件,用來和 git 倉庫互動

  • 通過 parser.parse_args() 解析命令列

  • 通過 hasattr(args, 'handle') 判斷是否輸入了子命令。

    • 由於每個子解析器都定義了 handle ,那麼如果當用戶在命令列不輸入任何命令時, args 就沒有 handle 屬性,那麼我們就輸出幫助資訊

    • 如果使用者輸入了子命令,那麼就呼叫 args.handle ,傳入 gitargs 物件,用以處理對應命令

至此,我們就實現了一個簡單的 git 命令列,使用 python argparse-git.py -h 檢視幫助如下:

usage: git [-h] command ...


optional arguments:

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


These are common Git commands used in various situations:

command

status Show the working tree status

add Add file contents to the index

commit Record changes to the repository

push Update remote refs along with associated objects

然後我們就可以愉快地使用親手打造的 git 程式啦!

想看整個原始碼,請戳 argparse-git.py [3]

小結

本文簡單介紹了日常工作中常用的 git 命令,然後提出實現它的思路,最終一步步地使用 argparsegitpython 實現了 git 程式。是不是很有成就感呢?

關於 argparse 的講解將告一段落,回顧下 argparse 的四步曲,加上今天的內容,感覺它還是挺清晰、簡單的。不過,這還只是打開了命令列大門的一扇門。

你是否想過, argparse 的四步曲雖然理解簡單,但略微麻煩。有沒有更簡單的方式?如果我很熟悉命令列幫助語法,我能不能寫個幫助字串就把所有的命令列元資訊給定義出來?然後就直接輕鬆愉快地獲取解析後的引數資訊呢?

在下篇文章中,將為大家講解另一個站在一個全新的思路,又無比強大的庫 docopt

References

[1] gitpython:  https://gitpython.readthedocs.io/en/stable/intro.html

[2] argparse-git.py:  https://github.com/HelloGitHub-Team/Article/blob/master/contents/Python/cmdline/argparse-git.py

[3] argparse-git.py:  https://github.com/HelloGitHub-Team/Article/blob/master/contents/Python/cmdline/argparse-git.py

分享到: