作者：HelloGitHub- Prodesire

HelloGitHub 的《講解開(kāi)源項(xiàng)目》系列，項(xiàng)目地址：https://github.com/HelloGitHub-Team/Article

前言

在前面三篇介紹 argparse 的文章中，我們?nèi)媪私饬? argparse 的能力，相信不少小伙伴們都已經(jīng)摩拳擦掌，想要打造一個(gè)屬于自己的命令行工具。

本文將以我們?nèi)粘９ぷ髦凶畛Ｒ?jiàn)的 git 命令為例，講解如何使用 argparse 庫(kù)來(lái)實(shí)現(xiàn)一個(gè)真正可用的命令行程序。

              
                本系列文章默認(rèn)使用 Python 3 作為解釋器進(jìn)行講解。
若你仍在使用 Python 2，請(qǐng)注意兩者之間語(yǔ)法和庫(kù)的使用差異哦~
              
            

git 常用命令

大家不妨回憶一下，平時(shí)最常使用 git 子命令都有哪些？

當(dāng)你寫(xiě)好一段代碼或增刪一些文件后，會(huì)用如下命令查看文件狀態(tài)：

              
                git status
              
            

確認(rèn)文件狀態(tài)后，會(huì)用如下命令將的一個(gè)或多個(gè)文件（夾）添加到暫存區(qū)：

              
                git add [pathspec [pathspec ...]]
              
            

然后使用如下命令提交信息：

              
                git commit -m "your commit message"
              
            

最后使用如下命令將提交推送到遠(yuǎn)程倉(cāng)庫(kù)：

              
                git push
              
            

我們將使用 argparse 和 gitpython 庫(kù)來(lái)實(shí)現(xiàn)這 4 個(gè)子命令。

關(guān)于 gitpython

gitpython 是一個(gè)和 git 倉(cāng)庫(kù)交互的 Python 第三方庫(kù)。
我們將借用它的能力來(lái)實(shí)現(xiàn)真正的 git 邏輯。

安裝：

              
                pip install gitpython
              
            

思考

在實(shí)現(xiàn)前，我們不妨先思考下會(huì)用到 argparse 的哪些功能？整個(gè)程序的結(jié)構(gòu)是怎樣的？

argparse

• 要實(shí)現(xiàn)子命令，那么之前介紹到的 嵌套解析器 必不可少
• 當(dāng)用戶鍵入子命令時(shí)，子命令所對(duì)應(yīng)的子解析器需要作出響應(yīng)，那么需要用到子解析器的 set_defaults 功能
• 針對(duì) git add [pathspec [pathspec ...]] ，我們需要實(shí)現(xiàn)位置參數(shù)，而且數(shù)量是任意個(gè)
• 針對(duì) git commit --message msg 或 git commit -m msg ，我們需要實(shí)現(xiàn)選項(xiàng)參數(shù)，且即可長(zhǎng)選項(xiàng)，又可短選項(xiàng)

程序結(jié)構(gòu)

• 命令行程序需要一個(gè) cli 函數(shù)來(lái)作為統(tǒng)一的入口，它負(fù)責(zé)構(gòu)建解析器，并解析命令行參數(shù)
• 我們還需要四個(gè) handle_xxx 函數(shù)響應(yīng)對(duì)應(yīng)的子命令

則基本結(jié)構(gòu)如下：

              
                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 
                
                   命令
    """
    pass


def handle_push(git, args):
    """
    處理 push 命令
    """
    pass


if __name__ == '__main__':
    cli()
                
              
            

下面我們將一步步地實(shí)現(xiàn)我們的 git 程序。

實(shí)現(xiàn)

假定我們?cè)?argparse-git.py 文件中實(shí)現(xiàn)我們的 git 程序。

構(gòu)建解析器

我們需要構(gòu)建一個(gè)父解析器，作為程序的根解析器，程序名稱指定為 git 。然后在上面添加子解析器，為后續(xù)的子命令的解析做準(zhǔn)備：

              
                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 中的 title 和 metavar 參數(shù)主要用于命令行幫助信息，最終的效果如下：

              
                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 函數(shù)中添加一個(gè)用于解析 status 命令的子解析器 status_parser ，并指定其對(duì)應(yīng)的處理函數(shù)為 handle_status 。

              
                def cli():
    ...
    # status
    status_parser = subparsers.add_parser(
        'status',
        help='Show the working tree status')
    status_parser.set_defaults(handle=handle_status)
              
            

需要說(shuō)明的是，在 status_parser.set_defaults 函數(shù)中，能接收任意名稱的關(guān)鍵字參數(shù)，這個(gè)參數(shù)值會(huì)存放于父解析器解析命令行參數(shù)后的變量中。

比如，在本文示例程序中，我們?yōu)槊總€(gè)子解析器定義了 handle ，那么 args = parser.parse_args() 中的 args 將具有 handle 屬性，我們傳入不同的子命令，那么這個(gè) handle 就是不同的響應(yīng)函數(shù)。

定義了 status 的子解析器后，我們?cè)賹?shí)現(xiàn)下 handle_status 即可實(shí)現(xiàn) status 命令的響應(yīng)：

              
                def handle_status(git, args):
    """
    處理 status 命令
    """
    cmd = ['git', 'status']
    output = git.execute(cmd)
    print(output)
              
            

不難看出，我們最后調(diào)用了真正的 git status 來(lái)實(shí)現(xiàn)，并打印了輸出。

你可能會(huì)對(duì) handle_status 的函數(shù)簽名感到困惑，這里的 git 和 args 是怎么傳入的呢？這其實(shí)是由我們自己控制的，將在本文最后講解。

add 子命令

同樣，我們需要在 cli 函數(shù)中添加一個(gè)用于解析 add 命令的子解析器 add_parser ，并指定其對(duì)應(yīng)的處理函數(shù)為 handle_add 。

額外要做的是，要在子解析器 add_parser 上添加一個(gè) pathspec 位置參數(shù)，且其數(shù)量是任意的：

              
                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)
              
            

然后，就是實(shí)現(xiàn) handle_add 函數(shù)，我們需要用到表示文件路徑的 args.pathspec ：

              
                def handle_add(git, args):
    """
    處理 add 命令
    """
    cmd = ['git', 'add'] + args.pathspec
    output = git.execute(cmd)
    print(output)
              
            

commit 子命令

同樣，我們需要在 cli 函數(shù)中添加一個(gè)用于解析 commit 命令的子解析器 commit_parser ，并指定其對(duì)應(yīng)的處理函數(shù)為 handle_commit 。

額外要做的是，要在子解析器 commit_parser 上添加一個(gè) -m / --message 選項(xiàng)參數(shù)，且要求必填：

              
                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 
                
                   as the commit message',
        metavar='msg',
        required=True)
    commit_parser.set_defaults(handle=handle_commit)
                
              
            

然后，就是實(shí)現(xiàn) handle_commit 函數(shù)，我們需要用到表示提交信息的 args.message ：

              
                def handle_commit(git, args):
    """
    處理 -m 
                
                   命令
    """
    cmd = ['git', 'commit', '-m', args.message]
    output = git.execute(cmd)
    print(output)
                
              
            

push 子命令

同樣，我們需要在 cli 函數(shù)中添加一個(gè)用于解析 push 命令的子解析器 push_parser ，并指定其對(duì)應(yīng)的處理函數(shù)為 handle_push 。

它同 status 子命令的實(shí)現(xiàn)方式一致：

              
                def cli():
    ...
    # push
    push_parser = subparsers.add_parser(
      'push',
      help='Update remote refs along with associated objects')
    push_parser.set_defaults(handle=handle_push)
              
            

然后，就是實(shí)現(xiàn) handle_push 函數(shù)，和 handle_status 類似：

              
                def handle_push(git, args):
    cmd = ['git', 'push']
    output = git.execute(cmd)
    print(output)
              
            

解析參數(shù)

在定義完父子解析器，并添加參數(shù)后，我們就需要對(duì)參數(shù)做解析，這項(xiàng)工作也是實(shí)現(xiàn)在 cli 函數(shù)中：

              
                def cli():
    ...
    git = Git(os.getcwd())
    args = parser.parse_args()
    if hasattr(args, 'handle'):
        args.handle(git, args)
    else:
        parser.print_help()
              
            

• 通過(guò) git.cmd.Git 實(shí)例化出 git 對(duì)象，用來(lái)和 git 倉(cāng)庫(kù)交互
• 通過(guò) parser.parse_args() 解析命令行
• 通過(guò) hasattr(args, 'handle') 判斷是否輸入了子命令。
  • 由于每個(gè)子解析器都定義了 handle ，那么如果當(dāng)用戶在命令行不輸入任何命令時(shí)， args 就沒(méi)有 handle 屬性，那么我們就輸出幫助信息
  • 如果用戶輸入了子命令，那么就調(diào)用 args.handle ，傳入 git 和 args 對(duì)象，用以處理對(duì)應(yīng)命令

至此，我們就實(shí)現(xiàn)了一個(gè)簡(jiǎn)單的 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 程序啦！

想看整個(gè)源碼，請(qǐng)戳 argparse-git.py 。

小結(jié)

本文簡(jiǎn)單介紹了日常工作中常用的 git 命令，然后提出實(shí)現(xiàn)它的思路，最終一步步地使用 argparse 和 gitpython 實(shí)現(xiàn)了 git 程序。是不是很有成就感呢？

關(guān)于 argparse 的講解將告一段落，回顧下 argparse 的四步曲，加上今天的內(nèi)容，感覺(jué)它還是挺清晰、簡(jiǎn)單的。
不過(guò)，這還只是打開(kāi)了命令行大門(mén)的一扇門(mén)。

你是否想過(guò)， argparse 的四步曲雖然理解簡(jiǎn)單，但略微麻煩。有沒(méi)有更簡(jiǎn)單的方式？
如果我很熟悉命令行幫助語(yǔ)法，我能不能寫(xiě)個(gè)幫助字符串就把所有的命令行元信息給定義出來(lái)？然后就直接輕松愉快地獲取解析后的參數(shù)信息呢？

在下篇文章中，將為大家講解另一個(gè)站在一個(gè)全新的思路，又無(wú)比強(qiáng)大的庫(kù) docopt 。