yukke::note

technical note

関数をコマンドラインツールとして実行するpythonライブラリcommandrのご紹介

commandrのご紹介

 最近みつけた便利なpythonライブラリ "commandr"というライブラリがあります。インストールはpip install commandrで入ります。このライブラリは、適当につくったpythonの関数に、@commandでデコレートすると、定義した関数がコマンドラインとして実行できる、という大変便利なものとなっております。tellapart/commandr · GitHub に詳しい使い方がのっていますが、基本は非常にシンプルなデコレータです。

使い方あれこれ

from commandr import command, Run
@command
def say(name=""):
    """
    Arguments:
    name - your name
    """
    print "Hi! {}".format(name)
if __name__ == "__main__":
    Run()

上記のファイルをcmd.pyと保存して、python cmd.pyを実行してみます。sayは引数として受け取った文字列を表示するだけの関数です。

A command must be specified.

General Commands:
  help - Prints the global help message listing all commands.
  say -

sayというコマンドが追加されていることがわかります。 python cmd.py say --name yukkeと実行すると、

Hi! yukke

pythno cmd.py say --helpは関数に書いたdocstringを表示してくれます。

Documentation for command 'say':
----------------------------------------

    Arguments:
    name - your name

----------------------------------------

Usage: hoge.py say [options]
Options without default values MUST be specified

Use: hoge.py help [command]
  to see other commands available.

Options:
  -h, --help
  -n NAME, --name=NAME  [default: ""]

docstringも見やすいですね。また、@command(category="analysis")などと書くと、コマンド群をカテゴリに分類しておけます。

なぜ便利か?どんなときに使えるか?

 commandrは、データ解析をしている人には大変便利なツールとなり得ます。あるプロジェクトや仕事で、込み入った解析をするとなると、自作のクラスや関数を沢山書いて、それをライブラリとしてロードして、分析・解析をすることになります。このとき、pythonの標準的なディレクトリ構成は、

App/src/{プロジェクトのライブラリ}
App/scripts/{分析を実行するコード}
App/tests/{ライブラリのテストコード}

となっているかと思います。僕の場合ですが、自作のライブラリは、src以下にあり、それをscripts以下に設置した分析用のコードから呼び出す、という構成を取っています。
 ところが、パーサーやアルゴリズムの実装に比べて、解析用のコードはtry-and-errorで進めていくものなので、開発中のコードは特に、実行コマンドは同じでも出力が異なることは日常茶飯事です。シェルのヒストリに残った昨日の./scripts/run.pyと今日のそれは、出力が同じであることのほうが稀です。
 こういった状況において、入出力ファイルの名前やアルゴリズムのパラメータなどを出来る限りパラメータ化し、コマンドライン引数として実行することで、シェルのヒストリに記録しておく、というのは非常に有用なアプローチだと考えています。紹介したcommandrは、まさにそれを助けるためのライブラリで、研究活動における分析を出来る限り関数として定義し(冗長な名前でもよい)、@commandでデコレートすれば、コマンドラインとして実行可能となり、実行結果はシェルのヒストリに残るため、分析の再現性や分析のログとなるでしょう。
 pythonコマンドラインツールを書くことはさほど難しくはありませんが、やはり引数の処理などはめんどくさく、分析においてはあまり本質的ではありません。commandrは、pythonコードとdocstringからコマンドラインツールのインターフェースを自動生成しますので、あとから見返したときにも、実行方法が分からないというような悩みもある程度軽減されるはずです。ぜひお試しください。