開発者ガイド¶

xonshデベロッパーガイドへようこそ！これは、開発者がユーザーズガイドや図書館のリファレンスにない情報を配置する場所ですが、xonshを開発する次の人には有用または必要です。

注意

すべてのコード変更はプルリクエストレビュー手順を経なければなりません。

あなたの最初の変更をする¶

まずソースからxonshをインストールして、好きなターミナルアプリケーションにxonshシェルを開きます。詳細については、インストール手順を参照してください。

次に、些細な変更を加える（例えばprint("hello!")、main.py）。

最後に、次のコマンドを実行します。あなたはあなたの変更の影響を見るべきです（例えばhello!）：

$ $XONSH_DEBUG=1
$ xonsh

xonshビルドプロセスは、すべてのPythonソースファイルを1つの__amalgam__.pyファイルにまとめます。$ XONSH_DEBUGの偽の値でxonshを開始すると、 Pythonモジュールがそのままインポート __amalgam__.pyされ、ランタイムインポートのコストを削減することで起動時間が短縮されます。しかし、設定は合併された輸入を抑制する。xonshシェル（）を再ロードするだけで、新しい変更が含まれていない古いファイルを単純にインポートするのではなく、変更を含むunamalgamatedソースコードをインポートします。xonshをリロードすることで、その後の変更をすべてロードできるようになりました。コードの変更が効果を持たないようなら、まずチェックしてください！$ $XONSH_DEBUG=1$ xonsh__amalgam__.py$XONSH_DEBUG

変更履歴¶

プルリクエストには、しばしばCHANGELOGエントリが関連付けられます。ただし、過剰なマージの競合を避けるため、次の手順に従ってください。

news/ディレクトリに移動し、
TEMPLATE.rstファイルをnews/ディレクトリ内の別のファイルにコピーします。分岐名を使用することをお勧めします。
```
$ cp TEMPLATE.rst branch.rst
```
branch.rst適切なカテゴリのファイルに箇条書きリストとしてエントリを追加します。None後で使用できるようにエントリを残してもかまいません。
あなたのことを約束してくださいbranch.rst。

あなたはいつでもこのファイルを更新することができます！他人のファイル名を使用しないでください。このnews/ディレクトリ内のすべてのファイルは、リリース時に自動的にマージされます。Noneエントリは自動的にあまりにも除外されます！

スタイルガイド¶

xonshは純粋なPythonプロジェクトであるため、コードベース全体の一貫性を保証するためにPEP8（いくつかの追加があります）を使用します。

書き込みルール¶

物と概念を最も具体的な名前で参照することが重要です。xonshコードまたは文書を書くときは、技術用語を適切に使用してください。次の規則は、必要な明確性を提供するのに役立ちます。

インターフェイス¶

ユーザ向けのAPIは、できるだけ汎用的で堅牢でなければなりません。
テストは最上位testsディレクトリに属します。
ドキュメントはトップレベルのdocsディレクトリに属します。

期待¶

コードには関連するテストと適切な文書が必要です。
ユーザーインタラクションコード（Shellクラスなど）はテストするのが難しいです。そのような構築物を試験するためのメカニズムは、時間の経過とともに開発されるべきである。
あなたのユーザーのための極端な共感を持っています。
利己的になりなさい。あなたがテストを書くので、あなたはあなたの最初のユーザーになります。

Pythonスタイルガイド¶

xonshは使用していますPEP8をすべてのPythonコードのために。PEP8 が解釈可能な場合、以下のルールが適用されます。

明示的な相対インポート（）ではなく、absolute imports（）を使用してください。暗黙の相対インポート（）は許可されません。import xonsh.toolsimport .toolsimport tools
文字列リテラルおよびドキュメントストリングに使用します。二重引用符は一重引用符のエスケープを防ぐために使用できます。'single quotes'"""triple double quotes""""Y'all c'mon o'er here!"
APIドキュメントを自動生成するために、numpydoc拡張子を持つsphinxを使用します。docstringの`numpydoc`_標準に従います。
シンプルな関数には簡単なドキュメントストリングが必要です。
行の長さは最大80文字です。PEP8の72文字と79文字の推奨はここでは必要ありません。
すべてのPythonコードはPython 3.4以降に準拠する必要があります。将来予想外の日にPython 2.7のサポートがサポートされる可能性があります。
テストは手続き型スタイルを使用してpytestで記述する必要があります。unittestを直接使用したり、オブジェクト指向のスタイルでテストを記述したりしないでください。
テストジェネレータはより多くのドットを作成し、ドットは流れなければなりません！

間違った変数名や、pylintを使ったいくつかの完全なバグなど、スタイルの問題を簡単にチェックできます。Anacondaを使用している場合は、「conda install pylint」を一度実行する必要があります。コミットされていないgitの変更で、編集したファイルに対して簡単にpylintを実行できます：

$ pylint $(git status -s | awk '/\.py$$/ { print $$2 }' | sort)

コードベース全体を実行するには：

$ pylint $(find tests xonsh -name \*.py | sort)

輸入¶

Xonshのソースコードは、__amalgam__.pyインポートを高速化するために単一のファイル（）に合併することがあります。コードの組み合わせが動作する方法は、同じパッケージに入っている他のモジュール（および融合されたもの）を次のものとともにインポートすることです。

from pkg.x import a, c, d

これは、アマルガマートがすべてのモジュールを同じグローバルに配置するためです。例えば、xonsh.astand xonsh.execerは両方とも同じpackage（xonsh）にあります。したがって、インポートからの構文から上記を使用する必要があります。

あるいは、現在のパッケージ（又はアマルガムないモジュール）の外部モジュールのインポートステートメントのいずれかでなければなりませんか、。これは、アマルガマテーターが安全であることが保証された方法で自動的に遅延読み込みを挿入できる唯一のケースであるためです。これは、遅れて構築できない、またはモジュールをインポートする可能性のある変数をインポートする可能性があるあいまいさが原因です。それに続く単純なルールは次のとおりです。import pkg.ximport pkg.x as namefrom pkg.x import name

from-importを使用して同じパッケージ内のモジュールからオブジェクトを直接インポートし、
直接インポートまたはimport-asステートメントを使用して、パッケージの外部のモジュールからオブジェクトをインポートします。

テスト方法¶

ドッカー¶

あなたがインストールせずにあなたの "進行中の仕事のバージョン"を実行したい場合は、新鮮な環境でDockerを使用することができます。Dockerがインストールされている場合、これを実行するだけです：

$ python xonsh-in-docker.py

これにより、独立したコンテナ内のリポジトリの現在の状態が構築され、実行されます（初めて実行すると時間がかかることがあります）。このスクリプトを渡すことができる2つの追加の引数があります。

Pythonのバージョン
のバージョン prompt_toolkit

例：

$ python docker.py 3.4 0.57

cwdがプロジェクトのルートディレクトリ（つまり.gitディレクトリを含むディレクトリ）であることを確認します。

依存関係¶

テストを実行するための環境を準備します。

$ pip install -r requirements-tests.txt

テストの実行 - 基本¶

pytestを使用してすべてのテストを実行します。

$ py.test -q

"-q"を使用すると、pytestはすべてのテストの情報をまとめて出力しません。

テストの実行 - 詳細¶

すべての単体テストを実行するには：

$ py.test

特定のテストを実行する場合は、実行するテスト名を指定できます。たとえば、test_aliasesを実行するには：

$ py.test test_aliases.py

上記の例では、複数のテスト名を渡すことができます。

$ py.test test_aliases.py test_environ.py

テストの作成 - 上級¶

（pytestのドキュメントを参照）

Pytestフレームワークでは、テストしようとしているものに対して素人のアサート文を使うことができます。テスト関数の名前には、test_という接頭辞を付ける必要があります。

def test_whatever():
    assert is_true_or_false

テストディレクトリのconftest.pyは、より多くのテスト分離のためにxonshのさまざまな部分を嘲笑するためのフィクスチャを定義します。さまざまな設備のリストについては：

$ py.test --fixtures

テストを書くときには、pytestの機能、つまりパラメータ化を使うのが一番です：

@pytest.mark.parametrize('env', [test_env1, test_env2])
def test_one(env, xonsh_builtins):
    xonsh_builtins.__xonsh__.env = env
    ...

これはそれぞれのtest_envで毎回2回テストを実行します。これはforループでも行うことができますが、テストは異なるテストケースに対して1回だけ実行され、分離は少なくなります。

それを念頭に置いて、各テストは少なくとも1つ、好ましくは1つのアサート文を持つべきです。

現時点では、xonshはpytestプラグインをサポートしていません。

ハッピーテスト！

文書化する方法¶

ドキュメンテーションには多くの形があります。これは、成功した文書化の手順を案内します。

ドキュメンテーション文字列¶

あなたが書いている言語にかかわらず、あなたは常にあなたのコードと一緒に文書の文字列を持っているべきです。これはとても重要なので、スタイルガイドの一部です。Pythonで書くとき、docstringは`numpydoc`_形式を使って再構造化テキストになければなりません。

自動ドキュメントフック¶

適切なフックが設定されると、作成したドキュメンテーションは自動的にウェブサイトに接続されます。この段階では、すべてのドキュメントはxonshの最上位docsディレクトリにあります。私たちは、sphinxツールを使ってドキュメンテーションを管理し、生成します。あなたは、sphinxのウェブサイトから学ぶことができます。ドキュメンテーションを生成したい場合は、最初にxonshをインストールし、docsdir から次のコマンドを実行する必要があります。

~/xonsh/docs $ make html

新しいモジュールごとに、適切なフックを指定する必要があります。これは、モジュールがプル要求で最初に表示されるときに実行する必要があります。ここから、新しいモジュールを呼び出しますmymod。フックを追加する方法は次のとおりです。

Pythonフック¶

Pythonのドキュメントはdocs/apiディレクトリにあります。最初に、呼び出された新しいモジュールを表すファイルをこのディレクトリに作成します mymod.rst。docs/apiディレクトリは、構造と一致するxonsh/ディレクトリを。モジュールがサブパッケージに含まれている場合、作成する前にサブパッケージのディレクトリに移動する必要がありますmymod.rst。このファイルの内容は次のとおりです。

mymod.rst：

.. _xonsh_mymod:

=======================================
My Awesome Module -- :mod:`xonsh.mymod`
=======================================

.. currentmodule:: xonsh.mymod

.. automodule:: xonsh.mymod
    :members:

これにより、すべてのドキュメンテーションが検索されmymod、適切なWebページが作成されます。今、このページをウェブサイトの残りの部分にフックする必要があります。

または他のサブディレクトリ内のindex.rstファイルに移動し、適切な（これは目次ツリーの略）にdocs/xonsh追加 mymodしtoctreeます。すべてのサブパッケージには独自のindex.rstファイルがあることに注意してください。

ウェブサイトの構築¶

ウェブサイト/ドキュメンテーションを構築するには、以下の依存関係が必要です。

xonsh自体もインストールする必要があることに注意してください。

ウェブサイトを変更する手順¶

xonshウェブサイトのソースファイルは、docsディレクトリにあります。開発者はまず必要な変更を行い、次にコマンドを実行してWebサイトをローカルに再構築します。

$ make html

これは、_build/html/フォルダ内のWebサイトのhtmlファイルを生成します。開発者は、お気に入りのブラウザでこれらのファイルを開くことによって、ローカルの変更を表示することができます。

$ google-chrome _build/html/index.html

開発者が変更に満足したら、変更をコミットして通常どおりに引き出す必要があります。プルリクエストが承認されると、開発者は以下の方法でウェブサイトにローカル変更を直接プッシュできます。

$ make push-root

支店とリリース¶

Mainline xonshの開発はmasterブランチで行われます。他のブランチは、機能の開発（トピックブランチ）や過去および今後のリリースの表現に使用できます。

すべてのリリースには、リリース予定日の2〜5日前にリリース候補（ '-rc1'）が必要です。この間、特別なリリースブランチ（ 'vX.XX-release'）に変更はありません。

リリースブランチはそこにありますので、リリース候補（rc）が公開されレビュー中に開発ブランチで開発を続けることができます。これは、そうしなければ、新しい開発は、誤って早期にリリースされるのを防ぐために、リリース後のリリースが統合されるまで待たなければならないからです。

したがって、 'vX.XX-release'ブランチは、リリース候補がある間だけ存在する必要があります。それらはステージングの一時的な第2レベルに類似しているので、このブランチにあるすべてのものもマスターの一部でなければなりません。

新しいリリース候補が出るたびに、vX.XX-releaseには「XXX-rcX」という名前のタグが付けられます。リリース候補の間に2〜5日間の期間が必要です。完全リリースと最終リリースが行われると、「vX.XX-release」ブランチがマスターにマージされてから削除されます。

次のリリース候補に含める必要のある新しい修正プログラムがある場合は、トピックブランチを作成し、それをリリースブランチにプルする必要があります。これが受け入れられた後、局所的な枝はマスターと併合されるべきである。

リリースブランチは、フルリリース前の2〜5日間静かで、手を触れないでください。

ここでのリリース候補の手順は、メジャーおよびマイナーリリースにのみ適用されます。マイクロリリースは、リリース候補を持たずに直接プッシュしてリリースすることができます。

メンテナンスタスク¶

ユニットテストで作成された* .pycファイルなどの一時ファイルのローカルリポジトリを次のコマンドを実行してクリーンアップすることができます。

$ rm -f xonsh/parser_table.py
$ rm -f xonsh/*.pyc tests/*.pyc
$ rm -fr build

リリースの実行¶

これはrelease.xshスクリプトを通して行われます。有効なオプションのリストを取得するには、次のようにします。

$ xonsh release.xsh --help

フルリリースを実行することができます：

$ xonsh release.xsh

または特定のもののみ：

$ xonsh release.xsh --only-pip

リリースを除外することもできます：

$ xonsh release.xsh --no-conda