チュートリアル：拡張（Xontribs）¶
深呼吸をして、深刻なショー＆テルを準備しましょう。それはxonshの拡張について学ぶ時間です！
概要¶
Xontributionsは、xonsh xontribsの機能をデフォルトで提供されるものよりも拡張するための一連のツールと慣習です。これにより、サードパーティの開発者とユーザーは、xonshの開発とリリースのサイクルを経ることなく、xonshの経験を向上させることができます。
多くのツールとライブラリには拡張機能があります。xonshからインスピレーションを得たものがいくつかあります：
構造¶
Xontribは、xonsh（*.xsh）またはPython（*.py）で書かれたモジュールです。通常、これらは暗黙の名前空間パッケージに格納さ
れていxontribます。しかし、xontribは、パッケージまたはディレクトリにある任意のパッケージまたはディレクトリに置くことができます$PYTHONPATH。
モジュールがxontrib名前空間パッケージに含まれている場合、そのモジュール名だけで参照することができます。あるモジュールが他のパッケージに含まれている場合は、そのモジュールを完全なパッケージパスで参照する必要があります.。もちろん、モジュールxontribはフルで参照されるかもしれませんxontrib.myext。しかし、それを呼び出すだけmyextで、xontrib
名前空間パッケージに拡張を置くことの主な利点のほうがずっと短くなります。
サンプルファイルシステムのレイアウトとxontrib名は次のようになります。
|- xontrib/
|- javert.xsh # "javert", because in xontrib
|- your.py # "your",
|- eyes/
|- __init__.py
|- scream.xsh # "eyes.scream", because eyes is in xontrib
|- mypkg/
|- __init__.py # a regular package with an init file
|- other.py # not a xontrib
|- show.py # "mypkg.show", full module name
|- tell.xsh # "mypkg.tell", full module name
|- subpkg/
|- __init__.py
|- done.py # "mypkg.subpkg.done", full module name
また、xontribテンプレートにcookiecutterを使用して、xontribパッケージのレイアウトを簡単に作成することもできます。
Xontribのロード¶
Xontribは、いくつかの異なる方法でロードすることができます：設定ファイルから、実行時にxontribコマンドで動的に、またはモジュールを普通にインポートすることによって。これらの拡張モジュールはPythonモジュールなので、デフォルトではアンロードできません（簡単に）。
注意
xontribがロードされると、パブリック変数は__all__、通常のPythonモジュールと同様に、定義されていない限り、現在の実行コンテキストに配置されます。
拡張機能はxontribxonshのデフォルトエイリアスであるコマンドによってロードされます。このコマンドは、xonshrcファイル内のどこからでも、またはxonshが起動した後でも実行できます。読み込みは、xontrib
コマンドのデフォルト動作です。したがって、このコマンドでロードする次のメソッドは同等です。
xontrib myext mpl mypkg.show
xontrib load myext mpl mypkg.show
同じxontribを複数回読み込むことは、最初のxontribの後に何の効果もありません。Xontribは単にPythonモジュールであるため、同じキャッシングルールに従います。したがって、同じトークンによって、それらを正常にインポートすることもできます。もちろん、完全なモジュール名を使ってxontribをインポートする必要があります：
import xontrib.mpl
from xontrib import myext
from mypkg.show import *
既知のXontribのリスト¶
拡張機能の読み込みに加えてxontrib、既知のxontribをリストすることもできます。このコマンドは、既知のxontribがインストールされているかどうか、およびそれらが現在のセッションにロードされているかどうかを報告します。この情報を表示するには、listアクションをxontribコマンドに渡します。
>>> xontrib list
mpl installed not-loaded
myext not-installed not-loaded
デフォルトでは、これはすべての既知のxontribに関する情報を表示します。ただし、これをコマンドラインで渡される一連の名前に制限することができます。
>>> xontrib list mpl
mpl installed not-loaded
プログラムによるアクセスの場合は、次のコマンドでJSON形式の文字列を出力することもできます。
>>> xontrib list --json mpl
{"mpl": {"loaded": false, "installed": true}}
Xontribの作成¶
xontribを書くことは、xonshまたはPythonファイルを作成し、それをnamedというディレクトリに貼り付けるのと同じくらい簡単xontrib/です。しかし、置かないでください
__init__.pyにxontrib/ディレクトリ。これは暗黙の名前空間パッケージであり、それを持つ
べきではありません。詳細は、
PEP 420を参照してください。
警告
置かないでください__init__.pyにxontrib/ディレクトリ！
*.xshxontribでファイルを使用する予定の場合は、これらのファイルをインストールするためにdistutils、setuptools、pipなどにいくつかのフックを追加する必要があります。あなたのsetup()電話に以下のようなエントリを追加してみてくださいsetup.py：
try:
from setuptools import setup
except ImportError:
from distutils.core import setup
setup(...,
packages=[..., 'xontrib'],
package_dir={..., 'xontrib': 'xontrib'},
package_data={..., 'xontrib': ['*.xsh']},
...)
*.xshファイルを配布する必要のあるxontrib以外のパッケージやサブパッケージに対しても同様のことができます。
あなたのXontribについて教えてください！¶
私たちはxontribを私たちに登録することを要請します。これは一般的には良いアイデアだと思う：
- あなたのxontribは、xonshウェブサイトの拡張子として表示されます。
- これはコマンドに表示されます
xontrib list - それはに表示されます。
xonfig wizard
これらのすべては、あなたのxontribが利用可能であることをユーザーに知らせます。もちろん、xontribを登録する義務はありません。xontribがインストールされている限り、ユーザーはxontribを読み込むことができます。
xontribを登録するに
は、メインのxonshリポジトリのxontribs.jsonファイルにエントリを追加し
ます。プルリクエストがおそらく最善ですが、問題を解明できない場合は、xonsh開発者に関連情報を問い合わせてください。これは2つの最上位のキーを持つJSONファイルです："xontribs"と"packages"。
"xontribs"キーはxontribモジュール自体を記述する辞書のリストです。このようなエントリの構造は次のとおりです。
{"xontribs": [
{"name": "xontrib-name",
"package": "package-name",
"url": "http://example.com/api/xontrib",
"description": ["Textual description as string or list or strings ",
"enabling long content to be split over many lines."]
}
]
}
"packages"キーは、他の一方で、（xontribエントリに関連付けられている）のdictマッピングパッケージ名は、パッケージに関するメタデータです。パッケージエントリの構造は次のとおりです。
{"packages": {
"package-name": {
"license": "WTFPL v1.1",
"url": "http://example",
"install": {
"conda": "conda install package-name",
"pip": "xpip install package-name"}
}
}
}
"install"dictには必要な数のエントリを置くことができます。また、キーは任意のラベルなので、自由に自由に選んでください。
行く！
