4. ソースコード配布物を作成する

注釈

このドキュメントは、 https://setuptools.readthedocs.io/en/latest/setuptools.html にある setuptools のドキュメントが現時点でここにある関連情報を全て網羅するまで、単独でここに載せておかれます。

簡単な例 節で示したように、ソースコード配布物を作成するには sdist コマンドを使います。最も単純な例では、

python setup.py sdist

のようにします (ここでは、 sdist に関するオプションを setup スクリプトや設定ファイル中で行っていないものと仮定します)。 sdist は、現在のプラットフォームでのデフォルトのアーカイブ形式でアーカイブを生成します。デフォルトの形式は Unixでは gzip で圧縮された tar ファイル形式 (.tar.gz) で、Windows では ZIP 形式です。

--formats オプションを使えば、好きな数だけ圧縮形式を指定できます。例えば:

python setup.py sdist --formats=gztar,zip

は、gzip された tarball と zip ファイルを作成します。利用可能な形式は以下の通りです:

フォーマット

説明

注釈

zip

zip ファイル (.zip)

(1),(3)

gztar

gzip 圧縮された tar ファイル (.tar.gz)

(2)

bztar

bzip2 圧縮された tar ファイル (.tar.bz2)

xztar

xz 圧縮された tar ファイル (.tar.xz)

ztar

compress 圧縮された tar ファイル (.tar.Z)

(4)

tar

tar ファイル (.tar)

バージョン 3.5 で変更: xztar 形式のサポートが追加されました。

注釈:

  1. Windows でのデフォルト形式です

  2. Unixでのデフォルト形式です

  3. 外部ユーティリティの zip か、 zipfile モジュール (Python 1.6 からは標準 Python ライブラリの一部になっています) が必要です

  4. compress プログラムが必要です。このフォーマットは廃止が検討されていて、将来のバージョンの Python では削除されるであろうことに注意してください。

tar フォーマットのどれか (gztar, bztar, xztar, ztar, tar) を利用する時、 Unix ではアーカイブ内の各メンバに設定される owner と group 名を指定することができます。

例えば、アーカイブ内の全てのファイルの所有者を root にするには、次のようにします。

python setup.py sdist --owner=root --group=root

4.1. 配布するファイルを指定する

明確なファイルのリスト (またはファイルリストを生成する方法) を明示的に与えなかった場合、 sdist コマンドはソース配布物に以下のような最小のデフォルトのセットを含めます:

  • py_modules と packages オプションに指定された Python ソースファイル全て

  • ext_modules オプションと libraries オプションで挙げられている C ソースファイル全て

  • scripts オプションで指定されたスクリプト。 スクリプトをインストールする を参照してください。

  • テストスクリプトと思しきファイル全て: test/test*.py (現状では、Distutils はテストスクリプトをただソース配布物に含めるだけですが、将来は Python モジュール配布物に対するテスト標準ができるかもしれません)

  • 標準 README ファイル (README, README.txt, README.rst) のどれか、 setup.py (または setup スクリプトにしているもの) 、および setup.cfg 。

  • package_data メタデータにマッチする全てのファイル。 パッケージデータをインストールする を参照してください。

  • data_files メタデータにマッチする全てのファイル。 追加のファイルをインストールする を参照してください。

上記のセットで十分なこともありますが、大抵他のファイルを配布物に含めたいと思うでしょう。普通は、 MANIFEST.in と呼ばれる マニフェストテンプレート (manifest template) を使ってこれを行います。マニフェストテンプレートは、ソース配布物に含めるファイルの正確なリストであるマニフェストファイル MANIFEST をどうやって作成するか指示しているリストです。 sdist コマンドはこのテンプレートを処理し、書かれた指示とファイルシステム上に見つかったファイルに基づいてマニフェストファイルを作成します。

自分用のマニフェストファイルを書きたいなら、その形式は簡単です: 一行あたり一つの通常ファイル (または通常ファイルに対するシンボリックリンク) だけを書きます。自分で MANIFEST を提供する場合、全てを自分で指定しなければなりません: ただし、上で説明したデフォルトのファイルセットは、この中には含まれません。

バージョン 3.1 で変更: sdist は MANIFEST.in もしくは setup.py と更新時刻を比較せずに、生成されて既に存在している MANIFEST を再生成します。

バージョン 3.1.3 で変更: MANIFEST ファイルの先頭に、生成されたものであることを示すコメントが付きます。このコメントが無いファイルは上書きや削除はされません。

バージョン 3.2.2 で変更: 以前そうであったように、 MANIFEST.in が無い場合、 sdist は MANIFEST を読みに行きます。

バージョン 3.7 で変更: README.rst が distutils の標準 README のリストに含まれるようになりました。

マニフェストテンプレートには 1 行ごとに 1 つのコマンドがあり、それぞれのコマンドはソース配布物に含む、もしくは含まないファイルの集合を指定します。例として、再度 Distutils 自身のマニフェストテンプレートに戻りましょう:

include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build

その意味はかなり明白です: 配布物ルートの *.txt のパターンに当て嵌まる全てのファイルと、 examples ディレクトリ以下の *.txt または *.py のパターンに当て嵌まる全てのファイルを含み、 examples/sample?/build のパターンに当て嵌まる全てのディレクトリを除外します。これらの処理は、標準で含むファイル一式が定まった 後に 行われ、マニフェストテンプレートに明示的に指示を書くことで、標準のファイル一式からファイルを除外することができます。 (もしくは、 --no-defaults オプションを使って、標準のファイル一式の定義を全て無効にすることもできます。) マニフェストテンプレートの小言語では、他にもいくつかのコマンドが利用できます; ソース配布物を生成する: sdist コマンド を参照してください。

マニフェストテンプレート中のコマンドの順番には意味があります; 初期状態では、上で述べたようなデフォルトのファイルがあり、テンプレート中の各コマンドによって、逐次ファイルを追加したり除去したりしていいます。マニフェストテンプレートを完全に処理し終えたら、ソース配布物中に含めるべきでない以下のファイルをリストから除去します:

  • Distutls の "build" (デフォルトの名前は build/) ツリー下にある全てのファイル

  • RCS, CVS, .svn, .hg, .git, .bzr, _darcs といった名前のディレクトリ下にある全てのファイル

こうして完全なファイルのリストができ、後で参照するためにマニフェストに書き込まれます。この内容は、ソース配布物のアーカイブを作成する際に使われます。

含めるファイルのデフォルトセットは --no-defaults で無効化でき、標準で除外するセットは --no-prune で無効化できます。

Distutils 自体のマニフェストテンプレートから、 sdist コマンドがどのようにして Distutils ソース配布物に含めるファイルのリストを作成するか見てみましょう:

  1. distutils ディレクトリ、および distutils/command サブディレクトリの下にある全ての Python ソースファイルを含めます (これらの二つのディレクトリが、setup スクリプト下の packages オプションに記載されているからです --- setup スクリプトを書く を参照してください)

  2. README.txt, setup.py, および setup.cfg (標準のファイルセット) を含めます

  3. test/test*.py (標準のファイルセット) を含めます

  4. 配布物ルート下の *.txt を含めます (この処理で、 README.txt がもう一度見つかりますが、こうした冗長性は後で刈り取られます)

  5. examples 下にあるサブツリー内で *.txt または *.py にマッチする全てのファイルを含めます

  6. ディレクトリ名が examples/sample?/build にマッチするディレクトリ以下のサブツリー内にあるファイル全てを除外します--- この操作によって、上の二つのステップでリストに含められたファイルが除外されることがあるので、マニフェストテンプレート内では recursive-include コマンドの後に prune コマンドを持ってくることが重要です

  7. build ツリー全体、および RCS, CVS, .svn, .hg, .git, .bzr, _darcs ディレクトリ全てを除外します。

setup スクリプトと同様、マニフェストテンプレート中のディレクトリ名は常にスラッシュ区切りで表記します; Distutils は、こうしたディレクトリ名を注意深くプラットフォームでの標準的な表現に変換します。このため、マニフェストテンプレートは複数のオペレーティングシステムにわたって可搬性を持ちます。