サブコマンドをincludeで自由に追加できるようにした

サブコマンドをincludeで自由に追加できるようにした。

デフォルトで利用できるサブコマンド

例えば egoist init clikit で生成されるdefinitions.pyは以下の様なサブコマンドを持っている。

describe
generate
scan

usage: definitions.py [-h]
                      [--logging {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}]
                      {describe,generate,scan} ...

optional arguments:
  -h, --help            show this help message and exit
  --logging {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}

subcommands:
  {describe,generate,scan}
    describe
    generate
    scan

このときのdefinitions.pyは以下の様なコード。大切なのはcreate_app()とapp.include()の部分だけ。

from egoist.app import create_app, SettingsDict, parse_args

settings: SettingsDict = {"rootdir": "cmd/", "here": __file__}
app = create_app(settings)

app.include("egoist.directives.define_cli")


# hello/main.goの生成用の定義。ただし今回の記事では使われていない。
@app.define_cli("egoist.generators.clikit:walk")
def hello(*, name: str) -> None:
    """hello message"""
    from egoist.generators.clikit import runtime, clikit

    with runtime.generate(clikit):
        runtime.printf("hello %s\n", name)


if __name__ == "__main__":
    for argv in parse_args(sep="-"):
        app.run(argv)

create_app()の中身

最近の変更でサブコマンドの追加も自由に行えるようになった。デフォルトのサブコマンドはcreate_app()の中で行われている。定義はこのような感じ。

def create_app(settings: SettingsDict) -> App:
    app = App(t.cast(t.Dict[str, t.Any], settings))
    app.include("egoist.commands.describe")
    app.include("egoist.commands.generate")
    app.include("egoist.commands.scan")
    return app

そう。実際のところはAppを作って先程の3つのコマンドをincludeしているだけ。

欲しいコマンドを絞ってincludeする

そんなわけで、欲しいコマンドを絞ってincludeすることで余分なサブコマンドをない形にできる。あるいは、自分の好みのサブコマンドを追加する事ができる。

例えばgenerateだけを持つようにするには以下の様にする。

--- ../00hello/definitions.py    2020-05-19 00:28:02.000000000 +0900
+++ definitions.py    2020-05-19 07:44:27.000000000 +0900
@@ -1,8 +1,9 @@
-from egoist.app import create_app, SettingsDict, parse_args
+from egoist.app import App, SettingsDict, parse_args
 
 settings: SettingsDict = {"rootdir": "cmd/", "here": __file__}
-app = create_app(settings)
+app = App(settings)
 
+app.include("egoist.commands.generate")
 app.include("egoist.directives.define_cli")

直接自分でAppを作って、"egoist.commands.generate"だけをinclude。実際このときのhelpを見ると以下のようにgenerateだけが使える様になる。

$ python definitions.py -h
usage: definitions.py [-h]
                      [--logging {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}]
                      {generate} ...

optional arguments:
  -h, --help            show this help message and exit
  --logging {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}

subcommands:
  {generate}
    generate

どうしてこのようにサブコマンドを自由に追加できるような機能が欲しくなったかというと、オプショナルなコマンドを追加したくなったため。具体的には依存関係をMakefileに落とし込むようなコマンドが欲しくなったが、それはさすがに全ての人に公開する必須のコマンドというほどでもなく、利用したい状況は絞られるかなーと思ったので。

せっかくなので、そのサブコマンドの追加という方法自体、をユーザーに公開してしまおうという流れでこのような形になった。

自作のサブコマンド

自分でサブコマンドを追加してみることにする。argparseのparserの設定と選択されたときに実行されるコマンドがあれば十分。

以下の様な感じで書けば良い。テキトーに現在時刻を表示するようなnowコマンドを作ってみる。

実行例。

$ python definitions.py now -h
usage: definitions.py now [-h] [--format FORMAT]

optional arguments:
  -h, --help       show this help message and exit
  --format FORMAT

$ python definitions.py now
2020-05-19T07:58:47

$ python definitions.py now --format="%Y-%m-%d"
2020-05-19

commands/now.py に定義してみることにする。

$ tree
.
├── commands
│   ├── __pycache__
│   │   └── now.cpython-38.pyc
│   └── now.py
└── definitions.py

2 directories, 3 files

TYPE_CHECKINGのif文で囲っているのは、mypyのときだけ読み込みたいから。

commands/now.py

from __future__ import annotations
import typing as t
from functools import partial
from egoist.app import App
from egoist.types import AnyFunction

if t.TYPE_CHECKING:
    from argparse import ArgumentParser


def now(app: App, *, format: str,) -> None:
    from datetime import datetime

    now = datetime.now()
    print(now.strftime(format))


def setup(app: App, sub_parser: ArgumentParser, fn: AnyFunction) -> None:
    sub_parser.add_argument("--format", default="%Y-%m-%dT%H:%M:%S%z")
    # ここのpartialは後で不要にするかもしれない
    sub_parser.set_defaults(subcommand=partial(fn, app))


def includeme(app: App) -> None:
    app.include("egoist.directives.add_subcommand")
    app.add_subcommand(setup, fn=now)

本体がnow()で、それをサブコマンドとして設定するのがsetup()。includemeはapp.include()から読まれたときに自動で実行されるコールバック関数。このあたりはpyramidのconfiguratorの振る舞いを参考にしている。

definitions.pyは以下の様に書き換える。

--- ../01exclude/definitions.py  2020-05-19 07:44:27.000000000 +0900
+++ definitions.py    2020-05-19 07:55:34.000000000 +0900
@@ -4,6 +4,7 @@
 app = App(settings)
 
 app.include("egoist.commands.generate")
+app.include("commands.now")
 app.include("egoist.directives.define_cli")

このようにするとnowというサブコマンドが実行できるようになる。

$ python definitions.py now
2020-05-19T07:58:47

実際サブコマンドの一覧に登録したnowが存在している。

$ python definitions.py
usage: definitions.py [-h] [--logging {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}]
                      {generate,now} ...

optional arguments:
  -h, --help            show this help message and exit
  --logging {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}

subcommands:
  {generate,now}
    generate
    now
definitions.py: error: the following arguments are required: subcommand

特にcwdにdefinitions.pyがなければダメというわけではないので。１つ階層を登ったところからでも実行できる(config.include()に渡すモジュールのパスををdefintions.pyからの相対位置として記述できる)。

$ cd ../
$ python 02*/definitions.py now
2020-05-19T08:02:09

はい。

まとめ

egoistでサブコマンドを自由に選り好みできるようになった
自作のサブコマンドを登録する事もできる
例えば、特定の環境だけで便利なサブコマンドは特別にincludeして使いたい

ただ、全部を明示的に扱うということを考えると、create_app()でwrapするのはきれいではないかもしれない（素直にinitのタイミングで全部includeするコードを吐くような形の方が綺麗かもしれない）。

ちなみに、このようなことはgoではやりづらいが、なぜ不要なのかというとタスクランナーやMakefileあるいはちょっとしたシェルスクリプトでwrapするからというのがgoのユーザーから見た立場の意見。

gist

https://gist.github.com/podhmo/6dcae762e4eb09f310b1a27786517382