Python 命令行之旅：使用 argparse 实现 git 命令

做者：HelloGitHub- 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 程序啦！

想看整个源码，请戳 argparse-git.py 。

小结

本文简单介绍了平常工做中经常使用的 git 命令，而后提出实现它的思路，最终一步步地使用 argparse 和 gitpython 实现了 git 程序。是否是颇有成就感呢？

关于 argparse 的讲解将告一段落，回顾下 argparse 的四步曲，加上今天的内容，感受它仍是挺清晰、简单的。 不过，这还只是打开了命令行大门的一扇门。

你是否想过，argparse 的四步曲虽然理解简单，但略微麻烦。有没有更简单的方式？ 若是我很熟悉命令行帮助语法，我能不能写个帮助字符串就把全部的命令行元信息给定义出来？而后就直接轻松愉快地获取解析后的参数信息呢？

在下篇文章中，将为你们讲解另外一个站在一个全新的思路，又无比强大的库 docopt。

欢迎关注 HelloGitHub 公众号，获取更多开源项目的资料和内容

『讲解开源项目系列』 启动——让对开源项目感兴趣的人再也不畏惧、让开源项目的发起者再也不孤单。跟着咱们的文章，你会发现编程的乐趣、使用和发现参与开源项目如此简单。欢迎联系咱们给咱们投稿，让更多人爱上开源、贡献开源～