Python 指令行之旅：使用 argparse 實作 git 指令

原文發表于

Prodesire 部落格

。

前言

在前面三篇介紹

argparse

的文章中，我們全面了解了

argparse

的能力，相信不少小夥伴們都已經摩拳擦掌，想要打造一個屬于自己的指令行工具。

本文将以我們日常工作中最常見的

git

指令為例，講解如何使用

argparse

庫來實作一個真正可用的指令行程式。

本系列文章預設使用 Python 3 作為解釋器進行講解。
若你仍在使用 Python 2，請注意兩者之間文法和庫的使用差異哦~           

git 常用指令

大家不妨回憶一下，平時最常使用

git

子指令都有哪些？

當你寫好一段代碼或增删一些檔案後，會用如下指令檢視檔案狀态：

git status           

确認檔案狀态後，會用如下指令将的一個或多個檔案（夾）添加到暫存區：

git add [pathspec [pathspec ...]]           

然後使用如下指令送出資訊：

git commit -m "your commit message"           

最後使用如下指令将送出推送到遠端倉庫：

git push           

我們将使用

argparse

和

gitpython

庫來實作這 4 個子指令。

關于 gitpython

gitpython

是一個和

git

倉庫互動的 Python 第三方庫。

我們将借用它的能力來實作真正的

git

邏輯。

安裝：

pip install gitpython           

思考

在實作前，我們不妨先思考下會用到

argparse

的哪些功能？整個程式的結構是怎樣的？

argparse

• 要實作子指令，那麼之前介紹到的

  嵌套解析器

  必不可少
• 當使用者鍵入子指令時，子指令所對應的子解析器需要作出響應，那麼需要用到子解析器的

  set_defaults

  功能
• 針對

  git add [pathspec [pathspec ...]]

  ，我們需要實作位置參數，而且數量是任意個

• git commit --message msg

  或

  git 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

檔案中實作我們的

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

中的

title

metavar

參數主要用于指令行幫助資訊，最終的效果如下：

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

的函數簽名感到困惑，這裡的

git

args

是怎麼傳入的呢？這其實是由我們自己控制的，将在本文最後講解。

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

    ，傳入

    git

    args

    對象，用以處理對應指令

至此，我們就實作了一個簡單的

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

程式啦！

想看整個源碼，請戳

小結

本文簡單介紹了日常工作中常用的

git

指令，然後提出實作它的思路，最終一步步地使用

argparse

gitpython

實作了

git

程式。是不是很有成就感呢？

關于

argparse

的講解将告一段落，回顧下

argparse

的四步曲，加上今天的内容，感覺它還是挺清晰、簡單的。

不過，這還隻是打開了指令行大門的一扇門。

你是否想過，

argparse

的四步曲雖然了解簡單，但略微麻煩。有沒有更簡單的方式？

如果我很熟悉指令行幫助文法，我能不能寫個幫助字元串就把所有的指令行元資訊給定義出來？然後就直接輕松愉快地擷取解析後的參數資訊呢？

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

docopt