- はじめに -
この記事はxonshのextension的立ち位置であるxontribを自作し、公開するまでの流れのメモです。
1年程前に現存していたxontribを紹介する記事を書きましたが、次は作成者側に回ってみようという旨です。
- - はじめに -
- - xontribとは -
- - cookiecutterによるtemplete利用 -
- - pypiで公開し使ってもらう -
- - xontrib作成において参考にできる所 -
- - おわりに -
- xontribとは -
xontribはxonshの拡張ライブラリ群である。
公開されているxontribを導入するには以下のようにライブラリをインストールしロードする。
pip install xontrib-hoge xontrib load hoge
xontrib loadをxonshrcに記述しておくことで、xonshセッション起動時にロードすることもできる。
1年程前に公開されていた各xontribの紹介は以下記事に記載している。
vaaaaaanquish.hatenablog.com
xontribはpythonスクリプトもしくはxshスクリプトによって記載されたmoduleで、xontrib以下のnamespaceに配置される。tabcomplete拡張や外部Pythonライブラリのサポート、xonshモジュールのoverride等が作成、公開されており、その作成方法については以下チュートリアルに概要が書かれている。
xon.sh
本記事はこちらを参考にし、xontribを作成していくものである。
- cookiecutterによるtemplete利用 -
xontribのテンプレートとしてcookiecutterを利用する事ができる。
https://github.com/laerus/cookiecutter-xontribgithub.com
以下コマンドで対話的にライブラリの雛形が作成できる。
pip install cookiecutter cookiecutter https://github.com/xonsh/xontrib-cookiecutter
対話の内容は以下のようになる
full_name [Your name]: vaaaaanquish email [Your address email]: sample@exm.com github_username [Your github username]: 6syun9 project_name [Name of the project]: xontrib-sample # setup.pyに記載されるproject project_slug [xontrib-samplelib]: sample # xontrib loadするモジュール名 project_short_description [A short description of the project]: This is test version [0.1.0]: 0.0.1
上記cookiecutterコマンドによってsampleディレクトリが作成される。
$ tree sample
.
├── LICENSE
├── README.rst
├── setup.py
└── xontrib
└── sample.xsh
作成した後は、sample.xshを編集するだけである。
作成された時点ではsample.xshには内容がないため、以下のように変更する。
import xonsh __all__ = () __version__ = '0.0.1' print('hello xontrib sample')
xontribを読み込んだ時点でstringをoutputするサンプルとなる。
こちらを手元にinstallし、xontrib loadで読み込んでみる。
sampleディレクトリ内にあるsetup.pyを利用する。
$ python setup.py install $ xontrib load sample hello xontrib sample
ここから中身を拡充していくだけ。
- pypiで公開し使ってもらう -
pip installで導入できるようにpypiに登録する。
(アカウント作成が必要なので事前に行なう)
PyPI · The Python Package Index
twinを利用したアップロード
distを作成し公開するためのツールを導入する
pip install wheel twine
先程の作成したパッケージのroot dirのsetup.pyを利用してパッケージを作成、アップロードする。
python setup.py sdist bdist_wheel
twine upload --repository-url https://upload.pypi.org/legacy/ dist/*
数分後くらいにちゃんと登録されて pip install xontrib-sample できるようになる(この記事は解説なので実際にはやってない)。
pypiのREADMEや必要な外部ライブラリを定義する
最低限以下のようにしておくとなんとかなる。
https://github.com/6syun9/xontrib-readable-traceback/blob/master/setup.py
rstじゃなくてmdじゃないとgithubがレンダリングしてくれない場合があるので、私はmdで管理している。
xonshのDocumentationに追加してもらう
公開されているxontribはxonshのドキュメント上に載せてもらう事ができる。
xon.sh
また xontrib list コマンドでも表示されるようになる。
こちらに載せてもらうには、本家xonshにpull requestsを送る必要がある。
例えば、以下のように「新しいxontrib作ったよ！」と xonsh/xontribs.json を編集した旨を伝えるpull requestsを作成する。
github.com
xonshにコントリビュートする時は news/TEMPLETE.rst をコピーして news/{{ブランチ名}}.rst なるファイルを作って、更新ログを書くルールになっているのでそちらも追加して終了。詳しくは以下Developer’s Guideを参照。
Developer’s Guide — xonsh 0.9.24 documentation
- xontrib作成において参考にできる所 -
「こういうの作ってみたいなあ…」と思った時に参考にできるよう私のメモとして記載しておく。
あるタイミングでコマンドを発火させたい
- Core Event Tutorial: Events — xonsh 0.9.24 documentation
- Core Eventをhookする事ができる
- xonshのCore Eventsまとめ - Stimulator
- 上記について私が日本語で書いただけ
- xonsh-direnv GitHub - 74th/xonsh-direnv: xonsh extension for using direnv
- cdした時に環境変数を読む構造をシンプルに実装してるので参考に
tab補完を拡張したい
- xonsh-docker-tabcomplete https://github.com/xsteadfastx/xonsh-docker-tabcomplete/blob/master
- 愚直にコマンドをif-elseで当てる実装になっており、簡単に作る時にはこれで十分だと感じる。
- apt_tabcomplete https://github.com/DangerOnTheRanger/xonsh-apt-tabcomplete/blob/master
- apt-getコマンドの補完をサポートしている。$(apt-cache --names-only search @(query))を利用して補完候補を出して返す関数を実装し__xonsh__.completersに追加している
- 補完用のコマンドが実装されているツールは大体同じような実装でいける
- scrapy_tabcomplete GitHub - Granitosaurus/xonsh-scrapy-tabcomplete: Scrapy tabcomplete support for Xonsh shell
- scrapyの補完候補をscrapy --helpから全部取得してきて、補完候補としている
- SCRAPY_CACHEなるキャッシュ機構を実装しているのが良い
- 更新が止まっているようで、廃止された__xonsh_completers__がある点に注意
- xonsh-click-tabcomplete GitHub - Granitosaurus/xonsh-click-tabcomplete: Xonsh shell tab completion for python applications based on click
- clickコマンドの補完をhelpから抜き取っている
- 上記同様廃止された__xonsh_completers__がある点に注意
promptの見た目を弄りたい
- xontrib-prompt-vi-mode GitHub - t184256/xontrib-prompt-vi-mode: vi-mode status formatter for xonsh prompt
- シンプルに右側にmodeを表示するだけ
- xonshの状態の取得やprompt表示の参考に
- xontrib-powerline GitHub - santagada/xontrib-powerline: Powerline for Xonsh shell
- xonshの基幹パッケージであるpython prompt toolkit(ptk)のPTK_STYLEを上書きしている
- ptkの表示に関しては学びが多い
- Updating and customizing xonsh — xonsh 0.9.24 documentation
- 公式のカスタマイズドキュメント
- 他にもxonsh promptで検索すると色んな記事が出てくるので参考に
コマンドの保存、読み込み、引数実装
- xontrib-z GitHub - AstraLuma/xontrib-z: Tracks your most used directories, based on 'frecency'.
- ディレクトリ名の一部を入力して移動するコマンドのxonsh版
- 実装が綺麗で、xonsh関数を作るときのargや入力したコマンドの保存読み込みが参考になる
- autojump-xonsh https://github.com/sagartewari01/autojump-xonsh
- xontrib-avox GitHub - AstraLuma/xontrib-avox: autovox policy based on project directories
- 仮想環境を自動でオン・オフする拡張
- 複雑なxontribではないが引数の書き方はやっぱりastronouth7303さん
コマンドの出力結果を使いたい
- xontrib-histcpy https://github.com/con-f-use/xontrib-histcpy/blob/master
- コマンド出力結果からURLを取得してコピペしたりブラウザで開いたりできるようにする
- 少々複雑だが_getoutsの実装が参考になる
xonsh自体の機能をoverrideしたい
- readable-traceback GitHub - vaaaaanquish/xontrib-readable-traceback: xonsh readable traceback
- xonshは一部I/Oを独自実装しているためそちらをoverrideする形で実装されたxontrib
- 解説: XonshのException発生時のtracebackを見やすくする - Stimulator
別threadの実装
- xontrib-schedule GitHub - AstraLuma/xontrib-schedule: Xonsh Task Scheduling
- 指定時間後にコマンドを実行する拡張
- 別スレッドで何かを動かして〜〜という実装をする時の参考に
画像やgraphを表示したい
- imgcatを使った実装
- xonshもといptkはmatplotlibをhookして描画する機能を持つ
- xontrib.mplhooks.show()なる独自実装 or iTerm2のAPIを利用した画像表示
- Xonshでmatplotlibグラフをコンソールにインライン描画してメモリ状況を観察する - Stimulator
- xonshの過去のコマンド履歴を可視化する - Stimulator
- 上記記事は一部古いので新しいptkに対応させる必要はあるかも
サブウインドウやalertを表示したい
- ptkはCLI操作やProgress barsモジュールだけでなくDialogの描画などにも対応している
- xonshもptkのfull screen appでありptkをimportして機能を利用する事ができる
- 以下sampleを拡張しウインドウ等が実装できるが、今の所情報が少なめ
ネタがない
- Wishlist & To-Dos — xonsh 0.9.24 documentation
- xonshとしてはfishライクなmanページ補完やMLによるコマンド予測がやりたいっぽい
- Issues · xonsh/xonsh · GitHub
- issueからfeatureタグがついたものを実装していくと良いらしい
- gitter xonsh/xonsh - Gitter
- 作者各位とチャットできる。メーリングリストもあるがはるかにカジュアルだと思うのでオススメ
- 筆者は各rcファイルを管理するRepository内にxonshのネタ帳を公開している
