用 Plumbum 開發 Python 命令列工具

$ MY_LOG_FILE=this.log ./example.py
this.log

在命令列給定變數值會改寫相同環境變數的值。

Main

一旦當所有命令列引數被處理後 ，main() 方法會獲取程式的控制，並且可以有任意數量的位置引數，比如，在 cp -r /foo /bar 中, /foo 和 /bar 是位置引數。程式接受位置引數的數量依賴於 main() 函式的宣告：如果 main 方法有 5 個引數，2 個是有預設值的，那麼使用者最少需要提供 3 個位置引數並且總數量不能多於 5 個。如果 main 方法的宣告中使用的是可變引數（*args），那麼位置引數的個數是沒有限制的。

class MyApp(cli.Application):
    def main(self, src, dst, mode = "normal"):
        print(src, dst, mode)

$ ./example.py /foo /bar
/foo /bar normal
$ ./example.py /foo /bar spam
/foo /bar spam
$ ./example.py /foo
Expected at least 2 positional arguments, got ['/foo']
$ ./example.py /foo /bar spam bacon
Expected at most 3 positional arguments, got ['/foo', '/bar', 'spam', 'bacon']

註意 該方法的宣告也用於生成幫助資訊，例如：

Usage:  [SWITCHES] src dst [mode='normal']

使用可變引數：

class MyApp(cli.Application):
    def main(self, src, dst, *eggs):
        print(src, dst, eggs)

$ ./example.py a b c d
a b ('c', 'd')
$ ./example.py --help
Usage:  [SWITCHES] src dst eggs...
Meta-switches:
    -h, --help                 Prints this help message and quits
    -v, --version              Prints the program's version and quits

位置驗證

新版本 1.6

你可以使用 cli.positional 裝飾器提供的驗證器來驗證位置引數。只需在裝飾器中傳遞與 main 函式中的相匹配的驗證器即可。例如：

class MyApp(cli.Application):
    @cli.positional(cli.ExistingFile, cli.NonexistentPath)
    def main(self, infile, *outfiles):
        "infile is a path, outfiles are a list of paths, proper errors are given"

如果你的程式只在 Python 3 中執行，你可以使用註解來指定驗證器，例如：

class MyApp(cli.Application):
    def main(self, infile : cli.ExistingFile, *outfiles : cli.NonexistentPath):
    "Identical to above MyApp"

如果 positional 裝飾器存在，那麼註解會被忽略。

子命令

新版本 1.1

隨著 CLI 應用程式的擴充套件，功能變的越來越多，一個通常的做法是將其邏輯分成多個子應用（或者子命令）。一個典型的例子是版本控制系統，比如 git[6]，git 是根命令，在這之下的子命令比如 commit 或者 push 是巢狀的。git 甚至支援命令別名，這執行使用者自己建立一些子命令。Plumbum 寫類似這樣的程式是很輕鬆的。

在我們開始瞭解程式碼之前，先強調兩件事情：

這是一個模仿版本控制系統的例子 geet。我們有一個根應用 Geet ，它有兩個子命令 GeetCommit 和 GeetPush：這兩個子命令透過 subcommand 裝飾器來將其附加到根應用。

class Geet(cli.Application):
    """The l33t version control"""
    VERSION = "1.7.2"
    def main(self, *args):
        if args:
            print("Unknown command {0!r}".format(args[0]))
            return 1   # error exit code
        if not self.nested_command:           # will be ``None`` if no sub-command follows
            print("No command given")
            return 1   # error exit code
@Geet.subcommand("commit")                    # attach 'geet commit'
class GeetCommit(cli.Application):
    """creates a new commit in the current branch"""
    auto_add = cli.Flag("-a", help = "automatically add changed files")
    message = cli.SwitchAttr("-m", str, mandatory = True, help = "sets the commit message")
    def main(self):
        print("doing the commit...")
@Geet.subcommand("push")                      # attach 'geet push'
class GeetPush(cli.Application):
    """pushes the current local branch to the remote one"""
    def main(self, remote, branch = None):
        print("doing the push...")
if __name__ == "__main__":
    Geet.run()

$ python geet.py --help
geet v1.7.2
The l33t version control
Usage: geet.py [SWITCHES] [SUBCOMMAND [SWITCHES]] args...
Meta-switches:
    -h, --help                 Prints this help message and quits
    -v, --version              Prints the program's version and quits
Subcommands:
    commit                     creates a new commit in the current branch; see
                               'geet commit --help' for more info
    push                       pushes the current local branch to the remote
                               one; see 'geet push --help' for more info
$ python geet.py commit --help
geet commit v1.7.2
creates a new commit in the current branch
Usage: geet commit [SWITCHES]
Meta-switches:
    -h, --help                 Prints this help message and quits
    -v, --version              Prints the program's version and quits
Switches:
    -a                         automatically add changed files
    -m VALUE:str               sets the commit message; required
$ python geet.py commit -m "foo"
doing the commit...

from plumbum import cli
with cli.Config('~/.myapp_rc') as conf:
    one = conf.get('one', '1')
    two = conf.get('two', '2')

for i in Progress.range(10):
    time.sleep(1)

Image().show_pil(im)