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

簡単な例 節で示したように、ソースコード配布物を作成するには 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)
ztar	compress 圧縮された tar ファイル (.tar.Z)	(4)
tar	tar ファイル (.tar)

注釈:

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

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

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

4. compress プログラムが必要です。

tar フォーマットのどれか (gztar, bztar, 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.txt (または README)、 setup.py (または setup スクリプトにしているもの) 、および setup.cfg

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

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

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

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

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

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

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

シンタックスリファレンスは MANIFEST.in テンプレート を参照してください。

4.2. マニフェスト (manifest) 関連のオプション

sdist コマンドが通常行う処理の流れは、以下のようになっています:

• マニフェストファイル (デフォルトでは MANIFEST) が存在し、1行目に MANIFEST.in から生成されたことを示すコメントが無い場合は、変更を加えずにそのまま使用します

• マニフェストファイルが存在しないか、前回自動生成されていた場合は、 MANIFEST.in を読み込み、マニフェストを作成します

• MANIFEST も MANIFEST.in もなければ、デフォルトのファイルセットだけでできたマニフェストファイルを作成します

• (生成されたか、読み出された) MANIFEST 内にあるファイルのリストを使ってソース配布物アーカイブを作成します

上の動作は二種類のオプションを使って変更できます。まず、標準の "include" および "exclude" セットを無効化するには --no-defaults および --no-prune を使います。

第2に、単にマニフェストを (再)生成したいだけで、ソース配布物は作成したくない場合があるかもしれません:

python setup.py sdist --manifest-only

-o は --manifest-only のショートカットです。

4.3. MANIFEST.in テンプレート

sdist コマンドがビルドする配布物に含めるファイルのリストを定義するために、プロジェクトに MANIFEST.in ファイルを追加することができます。

sdist が実行された時、 MANIFEST.in ファイルを探して、それを解釈して、パッケージに含めるファイルのリストを含んだ MANIFEST ファイルを生成します。

この機構は、デフォルトのファイルリストが十分でないときに利用できます。 (配布するファイルを指定する を参照)

4.3.1. 原則

マニフェストテンプレートには一行あたり一つのコマンドがあります。各コマンドはソース配布物に入れたり配布物から除外したりするファイルのセットを指定します。例えば、Distutils 自体のマニフェストテンプレートを見てみましょう:

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

各行はかなり明確に意味を取れるはずです: 上の指定では、 *.txt にマッチする配布物ルート下の全てのファイル、 examples ディレクトリ下にある *.txt か *.py にマッチする全てのファイルを含め、 examples/sample?/build にマッチする全てのファイルを除外します。これらの処理はすべて、標準的に含められるファイルセットの評価よりも 後に 行われるので、マニフェストテンプレートに明示的に指示をしておけば、標準セット中のファイルも除外できます。 (--no-defaults オプションを設定して、標準セット自体を無効にもできます。)

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

• 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 は、こうしたディレクトリ名を注意深くプラットフォームでの標準的な表現に変換します。このため、マニフェストテンプレートは複数のオペレーティングシステムにわたって可搬性を持ちます。

4.3.2. コマンド

マニフェストテンプレートコマンド一覧:

コマンド	説明
include pat1 pat2 ...	リストされたパターンのどれかにマッチする全てのファイルを含める
exclude pat1 pat2 ...	リストされたパターンのどれかにマッチする全てのファイルを除外する
recursive-include dir pat1 pat2 ...	dir 配下の、リストされたパターンのどれかにマッチする全てのファイルを含める
recursive-exclude dir pat1 pat2 ...	dir 配下の、リストされたパターンのどれかにマッチする全てのファイルを除外する
global-include pat1 pat2 ...	ソースツリー内にある、リストされたパターンのどれかにマッチする全てのファイルを含める
global-exclude pat1 pat2 ...	ソースツリー内にある、リストされたパターンのどれかにマッチする全てのファイルを除外する
prune dir	dir 配下の全てのファイルを除外する
graft dir	dir 配下の全てのファイルを含める

ここで使うパターンは、 Unix スタイルの "glob" パターンです。 * は通常のファイル名文字の任意のシーケンスにマッチします。 ? は通常のファイル名文字の1文字にマッチします。 [range] は range に含まれる全ての文字にマッチします (例: a-z, a-zA-Z, a-f0-9_.) 通常のファイル名文字は、プラットフォーム依存になります。 Unix ではスラッシュ以外の全ての文字で、 Windows ではコロンとバックスラッシュ以外の全ての文字です。