用 Click、Docopt 和 Fire 庫寫你自己的命令行應(yīng)用。

有時對于某項工作來說一個命令行工具就足以勝任。命令行工具是一種從你的 shell 或者終端之類的地方交互或運行的程序。Git 和 Curl 就是兩個你也許已經(jīng)很熟悉的命令行工具。

當(dāng)你有一小段代碼需要在一行中執(zhí)行多次或者經(jīng)常性地被執(zhí)行，命令行工具就會很有用。Django 開發(fā)者執(zhí)行 ./manage.py runserver 命令來啟動他們的網(wǎng)絡(luò)服務(wù)器；Docker 開發(fā)者執(zhí)行 docker-compose up 來啟動他們的容器。你想要寫一個命令行工具的原因可能和你一開始想寫代碼的原因有很大不同。

對于這個月的 Python 專欄，我們有 3 個庫想介紹給希望為自己編寫命令行工具的 Python 使用者。

Click

Click 是我們***的用來開發(fā)命令行工具的 Python 包。其：

• 有一個富含例子的出色文檔
• 包含說明如何將命令行工具打包成一個更加易于執(zhí)行的 Python 應(yīng)用程序
• 自動生成實用的幫助文本
• 使你能夠疊加使用可選和必要參數(shù)，甚至是 多個命令
• 有一個 Django 版本（ django-click ）用來編寫管理命令

Click 使用 @click.command() 去聲明一個函數(shù)作為命令，同時可以指定必要和可選參數(shù)。

# hello.py
import click 
 
@click.command()
@click.option('--name', default='', help='Your name')
def say_hello(name):
    click.echo("Hello {}!".format(name))
 
if __name__ == '__main__':
    say_hello()

@click.option() 修飾器聲明了一個 可選參數(shù) ，而 @click.argument() 修飾器聲明了一個 必要參數(shù)。你可以通過疊加修飾器來組合可選和必要參數(shù)。echo() 方法將結(jié)果打印到控制臺。

$ python hello.py --name='Lacey'
Hello Lacey!

Docopt

Docopt 是一個命令行工具的解析器，類似于命令行工具的 Markdown。如果你喜歡流暢地編寫應(yīng)用文檔，在本文推薦的庫中 Docopt 有著***的格式化幫助文本。它不是我們***的命令行工具開發(fā)包的原因是它的文檔猶如把人扔進(jìn)深淵，使你開始使用時會有一些小困難。然而，它仍是一個輕量級的、廣受歡迎的庫，特別是當(dāng)一個漂亮的說明文檔對你來說很重要的時候。

Docopt 對于如何格式化文章開頭的 docstring 是很特別的。在工具名稱后面的 docsring 中，頂部元素必須是 Usage: 并且需要列出你希望命令被調(diào)用的方式（比如：自身調(diào)用，使用參數(shù)等等）。Usage: 需要包含 help 和 version 參數(shù)。

docstring 中的第二個元素是 Options:，對于在 Usages: 中提及的可選項和參數(shù)，它應(yīng)當(dāng)提供更多的信息。你的 docstring 的內(nèi)容變成了你幫助文本的內(nèi)容。

"""HELLO CLI
 
Usage:
    hello.py
    hello.py <name>
    hello.py -h|--help
    hello.py -v|--version
 
Options:
    <name>  Optional name argument.
    -h --help  Show this screen.
    -v --version  Show version.
"""
 
from docopt import docopt
 
def say_hello(name):
    return("Hello {}!".format(name))
 
 
if __name__ == '__main__':
    arguments = docopt(__doc__, version='DEMO 1.0')
    if arguments['<name>']:
        print(say_hello(arguments['<name>']))
    else:
        print(arguments)

在最基本的層面，Docopt 被設(shè)計用來返回你的參數(shù)鍵值對。如果我不指定上述的 name 調(diào)用上面的命令，我會得到一個字典的返回值：

$ python hello.py
{'--help': False,
 '--version': False,
 '<name>': None}

這里可看到我沒有輸入 help 和 version 標(biāo)記并且 name 參數(shù)是 None。

但是如果我?guī)е粋€ name 參數(shù)調(diào)用，say_hello 函數(shù)就會執(zhí)行了。

$ python hello.py Jeff
Hello Jeff!

Docopt 允許同時指定必要和可選參數(shù)，且各自有著不同的語法約定。必要參數(shù)需要在 ALLCAPS 和 <carets> 中展示，而可選參數(shù)需要單雙橫杠顯示，就像 --like。更多內(nèi)容可以閱讀 Docopt 有關(guān) patterns 的文檔。

Fire

Fire 是谷歌的一個命令行工具開發(fā)庫。尤其令人喜歡的是當(dāng)你的命令需要更多復(fù)雜參數(shù)或者處理 Python 對象時，它會聰明地嘗試解析你的參數(shù)類型。

Fire 的 文檔 包括了海量的樣例，但是我希望這些文檔能被更好地組織。Fire 能夠處理 同一個文件中的多條命令、使用 對象 的方法作為命令和 分組 命令。

它的弱點在于輸出到控制臺的文檔。命令行中的 docstring 不會出現(xiàn)在幫助文本中，并且?guī)椭谋疽膊灰欢?biāo)識出參數(shù)。

import fire
 
 
def say_hello(name=''):
    return 'Hello {}!'.format(name)
 
 
if __name__ == '__main__':
    fire.Fire()

參數(shù)是必要還是可選取決于你是否在函數(shù)或者方法定義中為其指定了一個默認(rèn)值。要調(diào)用命令，你必須指定文件名和函數(shù)名，比較類似 Click 的語法：

$ python hello.py say_hello Rikki
Hello Rikki!

你還可以像標(biāo)記一樣傳參，比如 --name=Rikki。

額外贈送：打包！

Click 包含了使用 setuptools 打包 命令行工具的使用說明（強烈推薦按照說明操作）。

要打包我們***個例子中的命令行工具，將以下內(nèi)容加到你的 setup.py 文件里：

from setuptools import setup
 
setup(
    name='hello',
    version='0.1',
    py_modules=['hello'],
    install_requires=[
        'Click',
    ],
    entry_points='''
        [console_scripts]
        hello=hello:say_hello
    ''',
)

任何你看見 hello 的地方，使用你自己的模塊名稱替換掉，但是要記得忽略 .py 后綴名。將 say_hello 替換成你的函數(shù)名稱。

然后，執(zhí)行 pip install --editable 來使你的命令在命令行中可用。

現(xiàn)在你可以調(diào)用你的命令，就像這樣：

$ hello --name='Jeff'
Hello Jeff!

通過打包你的命令，你可以省掉在控制臺鍵入 python hello.py --name='Jeff' 這種額外的步驟以減少鍵盤敲擊。這些指令也很可能可在我們提到的其他庫中使用。