[Python] setuptools

この記事について

この記事は、id:SumiTomohiko:20070622:1182537643の続きです。

setuptoolsに基づいたプロジェクトを配布する

setuptoolsを使用する...バンドルせずに!

あなたのユーザは自分のマシンにsetuptoolsをインストールしていないでしょうし、あるいはもししていたとしても、正しいバージョンであるとは限りません。これを正すのは簡単です; 単にez_setup.pyをダウンロードして、これをあなたのsetup.pyスクリプトと同じディレクトリに置けばいいです（ez_setup.pyをバージョン管理システムに追加するのを忘れないでください）。そうしたら以下の2行を、セットアップスクリプトがsetuptoolsから何かをインポートする前に、あなたのセットアップスクリプトの先頭に追加します。

import ez_setup
ez_setup.use_setuptools()

これで全部です。ez_setupモジュールは、setuptoolsが対象のシステムになければ、自動的にPyPIから適切なバージョンのsetuptoolsをダウンロードします。setuptoolsの新しいバージョンをインストールしたら常に、プロジェクトのez_setup.pyファイルも更新しなければなりません。これにより対象のマシンで適切なバージョンがインストールされるようになります。

ところで、setuptoolsは新しいPyPIの"upload"コマンドに対応しており、setup.py sdist uploadかsetup.py bdist_egg uploadを実行して、それぞれソースかeggの配布物をアップロードできます。もちろん最初に、プロジェクトの現在のバージョンがPyPIに登録されていなければなりません; setup.py registerで、登録することができます。あるいは、すべてを1ステップでこなすこともできます。例えば、setup.py register sdist bdist_egg uploadは、パッケージを登録し、ソースとeggの配布物をビルドし、それからそれらを両方ともPyPIにアップロードします。PyPIでは、プロジェクトに依存する他のプロジェクトが、簡単にアップロードしたものを探し出すことができます（ところで、setuptoolsの特定のバージョンを配布する必要があるとき、use_setuptools()関数のパラメータに、正確なバージョンとダウンロードするURLを指定できます。詳細は、この関数のdocstringを参照して下さい）。

あなたのユーザが知らなければならないこと

一般的には、setuptoolsを使っているプロジェクトは、ちょうどdistutilsを使っているプロジェクトに似ています -- あなたのユーザがインターネットに接続できて、site-packagesにインストールしている限りは。しかしユーザの中には、これらの条件が適用できない人もいて、setuptoolsを使っているプロジェクトに最初に遭遇したとき、彼らはいらいらします。彼らをいい気分にさせておくために、彼らがあなたのプロジェクトに関連していて、あなたが対象とするユーザがsetuptoolsとeasy_installにまだ詳しくなかったら、あなたのプロジェクトのインストール方法について、以下の点を検討する必要があります。

  • ネットワーク接続

もしあなたのプロジェクトがez_setupを使っていたら、ネットワーク接続か、EasyInstall installation instructionsが使うsetuptoolsの正しいバージョンがすでにインストールされている必要があることを、あなたはユーザに教える必要があります。これらの指示には、どうやって手動でsetuptoolsをダウンロードしてインストールするかの他に、ファイアウォールをどうするかという指示もついています。

  • 非標準なインストールの場所

もしあなたのユーザがメインのsite-packagesディレクトリ以外のどこかにプロジェクトをインストールしようとしていたら、あなたのプロジェクトをインストールする前に、Custom Installation Locationで指示されている方法で、setuptoolsを最初にインストールしなければならないことを、ユーザに教える必要があります。

  • あなたのプロジェクトが依存しているもの

あなたのプロジェクトがPyPIか他の場所からダウンロードされる必要がある他のプロジェクトに依存していたら、あなたはインストールの方法にそれらの一覧を記述するか、依存しているものを探し出す方法をユーザに教えなければいけません。ほとんどのユーザはこの情報を必要としていませんが、無制限のインターネット接続を持っていないすべてのユーザは他のプロジェクトを手動で探し、ダウンロードし、インストールしなければなりません（次の点にも注意してください。しかし、彼らはいまだにeasy_installを使ってそれらのプロジェクトをインストールする必要があり、そうしなければあなたのプロジェクトはそれらがインストールされていないことを知ることができず、あなたのセットアップスクリプトはそれらを再びダウンロードしようと試みることでしょう）。

もしネットワーク接続に制限があるユーザに特に友好的であろうとしたら、あなたのプロジェクトと依存しているもののeggをビルドして、あなたのサイトからそれらすべてがダウンロードできるようにし、あるいは少なくとも必要なすべてのeggへのリンクがあるページを作ろうと願うかもしれません。この方法だと、ネットワーク接続に制限があるユーザは、ひとつのディレクトリにすべてのeggを手動でダウンロードし、eggを探すディレクトリを指定するためにeasy_installの-fオプションを使えます。完全にネットワークに接続できるユーザは、あなたのダウンロードページのURLを指定するために-fオプションを使うだけでよく、そうすればeasy_installはあなたのリンクから直接必要なeggをすべて探します。これは、あなたのユーザがパッケージをコンパイルできない（例えば、ほとんどのWindowsユーザたち）うえ、あなたのパッケージが依存しているもののいくつかがC言語のコードを含んでいるときにも有効です。

CVSかSubversion, あるいは他のバージョン管理システムを使っている開発中のコードを追いかけているユーザと共同開発者は、おそらくこのマニュアルのこのような開発に関連している節を読む必要があります。あるいはあなたは、特定の状況に適用するこのマニュアルからの情報が書かれているクイックリファレンスガイドを作ろうと思うかもしれません。例えば、開発中のコードを追いかけているときはsetup.py developを使うように推奨するなら、更新するかコミットしたあとに毎回、setup.py developを実行する必要があることをユーザに教えなければなりません。

同じように、もしあなたがプロジェクトからモジュールかデータファイルを削除したら、setup.py clean --allを実行し、すべての必要なくなった.pycや.pyoを削除することを、彼らに思い出させる必要があります（この情報は、一般的にはsetuptoolsだけではなくdistutilsに適用されますが、すべての人がこれを知っているわけではありません; ユーザに推測させたままにしておくのではなく、あなたのプロジェクトの最良のプラクティスを記して、ユーザに親切にしましょう）。

  • システムパッケージを作成する

ユーザの何人かは、単一のパッケージ管理システムを使って、すべてのPythonのパッケージをを管理しようとし、ときとしてそのパッケージ管理システムはeasy_installではありません! setuptoolsは現在、システムのパッケージングにおいてbdist_rpmとbdist_wininst, bdist_dump形式に対応しています。もしユーザが、distutilsのinstallコマンドを内部で使っている、"bdist"パッケージツールをローカルにインストールしていたら、これはsetuptoolsとともに動作すべきです。setuptoolsと一緒に動作する"bdist"形式の例は、Windows用のbdist_nsi形式とbdist_msi形式を含みます。

しかし、コマンドラインでsetup.py installを実行するか、サブプロセスとして、バイナリの配布物をビルドするパッケージツールは、setuptoolsと一緒に動作するように修正をほどこす必要があります。それらは--single-version-externally-managedオプションを、標準の--rootオプションか--recordオプションと組み合わせて、installコマンドに使わなければなりません。詳細は、下のinstallコマンドの文書を参照して下さい。bdist_debコマンドは、現在のところsetuptoolsと一緒に使うためにはこの種のパッチをあてる必要があるコマンドの一例です。

もしあなたかあなたのユーザが、あなたのプロジェクトにおいて、使い易いシステムのパッケージをビルドするときに問題があったら、メーリングリストを通じて、その問題を報告し、質問の"bdist"ツールかsetuptoolsがその問題を解決するように修正できるようにして下さい。

複数プロジェクトを管理する

ez_setupが必要な複数のプロジェクトを管理していて、バージョン管理システムにSubversionを使用していた場合、"svn:externals"プロパティを使って、プロジェクト間でひとつのez_setupのコピーを共有することができます。これにより、個々のプロジェクトをチェックアウトしたり更新したりしたとき毎回、ez_setupは常に最新の状態になります。新しいバージョンを使うために各プロジェクトを手動で更新する必要はありません。

しかし、Subversionだけが外部のディレクトリを使うことに対応しているので、これをするためにはez_setup.pyをez_setup/__init__.pyに変更し、それから各プロジェクトでez_setupディレクトリを指す"externals"の定義を作成します。また、もしプロジェクトのどれかがセットアップディレクトリでfind_packages()を使っていたら、ez_setupパッケージを除外し、配布物に含まれないようにする必要があります。例えば: 

setup(
    ...
    packages = find_packages(exclude=['ez_setup']),
)

もちろん、ez_setupパッケージはまだあなたのパッケージのソースの配布物に含まれており、これは必要です。

以下のexternalsの定義を使用すると、便利です。これはsetuptoolsの最新バージョンを追いかけます: 

ez_setup svn://svn.eby-sarna.com/svnroot/ez_setup

プロジェクトのディレクトリで以下のコマンドを実行して、設定できます: 

svn propedit svn:externals .

それから、上の行を編集するファイルに追加します。

zip_safeフラグを設定する

性能を最大化するため、Pythonパッケージはzipファイルとしてインストールされるのがもっともよいです。しかし、すべてのパッケージが圧縮された形式で実行できるわけではありません。なぜならば、それらは通常のOSのファイルとしてソースコードやデータファイルにアクセスできることを期待するからです。このため、setuptoolsはプロジェクトをzipファイルとしても、ディレクトリとしてもインストールでき、デフォルトはプロジェクトのzip_safeフラグによって決定されます。

setup()関数のzip_safe引数にTrueかFalseを渡すか、省略できます。省略した場合、bdist_eggコマンドはプロジェクトを解析して、zipファイルとして動作するのに妨げとなる条件が検出されるかどうか、調査します。bdist_eggコマンドは、そのように見つけた条件について、コンソールに注意を出力します。

現在は、この解析は非常に不正確です: bdist_eggコマンドは、プロジェクトがC言語の拡張かデータファイルなどを含んでいたら、そのプロジェクトは安全ではないと判断します。これは、プロジェクトがzipファイルとして動作できないことを意味しません! これは単に、プロジェクトが動作することを断言するのに、bdist_eggの作者が気楽ではないことを意味します。もしプロジェクトがC言語もデータファイルも含んでおらず、__file__や__path__といったイントロスペクションやソースコードの操作をしないなら、zipファイルとしてインストールされたときにプロジェクトが動作するとても手堅い機会です（そしてプロジェクトがすべてのデータファイルのアクセスにpkg_resourcesを使っていたら、C言語の拡張と他のデータファイルはまったく問題になりません。より詳しいことは、上の「実行時にデータファイルにアクセスする」の節を読んでください）。

しかし、bdist_eggはあなたのパッケージが動作するか保証できないときは、それが出したすべての警告を調べて、それが動作することに満足し（あるいは自分でそれを試したい場合）、setup()を呼び出すときにzip_safeをTrueに設定できます。もし動作しないことが判明したら、あなたはいつもそれをFalseに変更できます。これにより、setuptoolsはプロジェクトをzipファイルではなくディレクトリとしてインストールします。

もちろん、エンドユーザがパッケージをインストールするのにEasyInstallを使っていたら、エンドユーザはまだこの決定を上書きできます。もしテストのためにこれを上書きしたいなら、あなた単にsetup.py easy_install --zip-ok .か、setup.py easy_install --always-unzip .をプロジェクトのディレクトリで実行すればよいです。これにより、パッケージはそれぞれ、zipファイルとして、あるいはディレクトリとしてインストールされます。

将来は、私たちが別のパッケージでもっと経験を積んだら、pkg_resourcesの実行の信頼性に満足でき、「zipとしても安全か」の解析はより正確になるでしょう。しかし、我々は、あなたが自分自身で、プロジェクトがzipファイルとしてインストールされたときに正常に機能するかどうか決め、できれば問題を集め、zip_safeフラグにTrueかFalseか明示的に与えることを強く推奨します。これにより、bdist_eggやEasyInstallがzipファイルとして動作するか推測するように試みる必要はなくなります。

名前空間パッケージ

ときとして、巨大なパッケージはより小さいeggの集まりとして配布したらより使い易いことがあります。しかし、Pythonは通常、ひとつのパッケージの内容を、ふたつ以上の場所から集めることはできません。「名前空間パッケージ」は、この問題に対する解決策です。あなたがあるパッケージを名前空間パッケージとして宣言したとき、そのパッケージは__init__.pyに意味のある内容を持たず、単にモジュールやサブパッケージのコンテナになります。

pkg_resourcesのランタイムは、それから自動的に、複数のeggやディレクトリに分かれている名前空間パッケージの内容を、単一の「仮想」パッケージにまとめます。

setup()のnamespace_packages引数により、プロジェクトが名前空間パッケージであることを宣言でき、これによりそれらのパッケージはプロジェクトのメタデータを含むようになります。この引数は、eggに加わるする名前空間パッケージの一覧です。例えば、ZopeInterfaceプロジェクトは以下のようになります: 

setup(
    # ...
    namespace_packages = ['zope']
)

なぜならば、これはzope名前空間パッケージの下にあるzope.interfaceパッケージを持つからです。同じように、標準のzope.publisherもまた、zope名前空間パッケージを宣言します。これらのプロジェクトがインストールされて使用されるとき、Pythonはこれらを両方共「仮想的な」zopeパッケージの一部であるとみなします。たとえこれらが別々の場所にインストールされたとしても。

名前空間パッケージは、トップレベルパッケージである必要はありません。例えば、Zope 3のzope.appパッケージは名前空間パッケージであり、将来のPEAKのpeak.utilパッケージも同様です。

ところで、次の点に注意してください。プロジェクトのソースツリーは、Pythonのパッケージレイアウトに沿って、名前空間パッケージの__init__.pyファイル（とすべての親パッケージの__init__.py）を含んでいなければなりません。これらの__init__.pyファイルは、次の行を含んでいなければなりません: 

__import__('pkg_resources').declare_namespace(__name__)

このコードにより、名前空間パッケージの機構が動作し、現在のパッケージが名前空間パッケージに登録されることが保証されます。

あなたは、名前空間パッケージの__init__.pyに、他のコードやデータをふくめてはいけません。開発中に、あるいはプロジェクトが.eggファイルとしてインストールされたときに、動作しているように見えても、「システムの」パッケージツールを使ってインストールされたとき、そのパッケージが動作しなくなります -- そのような場合、__init__.pyファイルをインストールせず、単独で実行させます。

問題となっている名前空間パッケージの内容物を持つすべてのプロジェクトの__init__.pyに、declare_namespace()の行を含めなければなりません。これにより、どのプロジェクトの__init__.pyのコピーが最初に読み込まれても、名前空間が宣言されることが保証されます。もし最初に読み込まれた__init__.pyがこれを宣言していなかったら、他のコピーはひとつも読み込まれないため、名前空間は絶対に宣言されません!

  • 移行時の注意

setuptools 0.6aは実行時に自動的にdeclare_namespace()を呼び出しますが、0.7aは呼び出しません。なぜならば、自動的な宣言の機能にはいくつか問題があるからです。例えば、pkg_resourcesの実行時の初期化中に、すべての名前空間パッケージをインポートする必要があり、またいずれかの名前空間パッケージが動作する前にpkg_resourcesを正確にインポートする必要もあるからです。0.7aのリリースから、あなたは自分自身の宣言行を含める責任があり、自動的な宣言の機能は問題を除去するために削除されます。

0.6の残りの開発サイクルの間は、それゆえ、setuptoolsは__init__.pyファイルにdeclare_namespace()の呼び出しがないことを警告します。あなたは、setuptools 0.7a1がリリースされる前に、できるだけ早くこれを修正しなければなりません。宣言行がない名前空間パッケージは、いったんユーザがsetuptools 0.7a1に更新したら動作しなくなり、そのため、現場であなたのコードが壊れるのを回避するために、いまこの変更をすることが重要です。我々は不便をかけたことを謝罪し、あなたの辛抱強さに感謝します。

タグ付けと「デイリービルド」、「スナップショット」リリース

関連するプロジェクトが開発中であるとき、例えば「安定」リリースを普通に使うより、細かくバージョンの増加を追いかけることが重要になるかもしれません。安定リリースは、ドットで区切られた番号とアルファやベータなどと一緒に番号づけられますが、プロジェクトの開発バージョンはしばしば、リビジョンかビルド番号かビルドした日付でさえ使って追いかけられます。これは、開発中のプロジェクトが他のプロジェクトを参照しているときとくにそうで、それゆえ文字通り分単位のバージョンが必要になります!

このようなシナリオに対応するため、setuptoolsは、プロジェクトの「公式」のバージョン識別子に、以下のものをひとつ以上追加することで、ソースコードとeggの配布物に「タグをつける」ことができます:

  • "build"や"dev"のような手動で指定されたプレリリースタグ、あるいはビルド番号やリビジョン番号のような手動で指定されたポストリリースタグ (--tag-build=STRING, -bSTRING)
  • Subversionのメタデータから自動的に生成された「最後に修正されたリビジョン番号」の文字列（プロジェクトがSubversionの「ワーキングコピー」からビルドされることを仮定します） (--tag-svn-revision, -r)
  • ポストリリースタグとして、8文字表現のビルドした日付 (--tag-date, -d)

あなたはこれらのタグをegg_infoに追加し、デイリービルドかスナップショットを生成したいsdistかbdistコマンドの前のコマンドラインに、希望するオプションを追加することができます。より詳しい情報は、下の「egg_info」コマンドの節を参照してください（また、プロジェクトをリリースする前に、上の「プロジェクトのバージョンを指定する」の節で、setuptoolsとEasyInstallがバージョン番号を解析するのに、どのようにプレリリースタグとポストリリースタグが影響するか、確かめてください。依存関係を処理するツールが、プロジェクトのどのバージョンが他のバージョンよりも新しいか知るのかについて確かめておくため、これは重要です）。

最後に、頻繁にビルドしている場合で、かつ、ダウンロード可能な場所でビルドしているか、配布サーバにコピーしているなら、あなたはおそらくrotateコマンドを調べる必要があります。このコマンドにより、ファイル名のパターンにマッチするもっとも最近変更されたN個の配布物を除いて、すべてのものを自動的に削除できます。これにより、以下のようにコマンドを使うことができます: 

setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3

これは、'DEV-rNNNN'（ここでNNNNは、ソースツリーに影響を与えたもっとも最近のSubversionのリビジョン）を含むバージョン情報を持つeggをビルドし、それからもっとも最近ビルドされた3つを除いて、配布ディレクトリからすべてのeggファイルを削除します。

もし、複数のパッケージに対して自動的なビルドを管理しなければならず、それぞれが異なるタグづけとローテーションの規約を持っているならば、あなたはaliasコマンドも調査したいと思うでしょう。このコマンドにより、各パッケージはdailyのようなエイリアスを定義でき、このエイリアスは必要なタグづけとビルド、ローテートコマンドを実行します。そのため、各プロジェクトのディレクトリで、より単純なスクリプトかcronのジョブが、単にsetup.pyを毎日実行すればいいようになります（そして、あなたはdailyエイリアスのサイトごとかユーザごとのデフォルトのバージョンを定義でき、これにより自分自身を定義できないプロジェクトが、適切なデフォルト値を使用できるようになります）。

ソース配布物を生成する

setuptoolsは、ソースファイルの選択においてdistutilsのデフォルトのアルゴリズムを強化し、これによりプロジェクトのツリー内でCVSかSubversionによって管理されているすべてのファイルがビルドするソース配布物に含まれます。これは手動でMANIFEST.inファイルを書いて、プロジェクトに同期させつづけることからの、大きな改善点です。そのため、もしCVSかSubversionを使っていたら、ソースの配布物に必要なのは、バージョン管理システムに管理されているファイルを含めるだけであり、プロジェクトのMANIFEST.inファイルを作ってはいけません（そして、もしすでにMANIFEST.inを持っていたら、それを変更しなければならない次のときに、削除することを検討するとよいでしょう）（注意: CVSとSubversion以外の他のバージョン管理システムもプラグインを使えば対応できます;下の「他のバージョン管理システムに対応する」を参照して、そのようなプラグインをどのように記述するのか、情報を得てください）。

もしあなたが自動的に生成されるファイルや、対応していないバージョン管理システムにあるファイルを含めるのを必要としていたら、MANIFEST.inファイルを作成して、デフォルトのファイルの位置決めのアルゴリズムが捕捉できないすべてのファイルを指定する必要があります。MANIFEST.inファイルの形式のより詳細な情報については、distutilsのドキュメントを参照してください。

しかし、distutilsのドキュメントの中で、MANIFESTを扱っている部分や、MANIFEST.inからどのようにMANIFESTが生成されるかといった部分は、無視しても構わないことを覚えておいてください; setuptoolsはそれらの結果からあなたを守り、あらゆる場合で同様に動作しません。distutilsとは違い、setuptoolsはソースの配布物のマニフェストファイルを、ソースの配布物をビルドしたときに毎回再生成し、メインのプロジェクトのディレクトリから外れて、プロジェクトの.egg-infoディレクトリにビルドします。そのため、あなたはこのファイルが最新であるかどうか、心配する必要はありません。

実際、setuptoolsがソースの配布物の内容を決める方法は非常に簡単であるため、sdistコマンドは、distutilsのより複雑なsdistプロセスが必要とするオプションのほとんどすべてを削除します。すべての実際の目的のために、もしどれかのオプションを使うのであれば、あなたはおそらく--formatsオプションだけを使うでしょう（ところで、もし他のバージョン管理システムを使っていたら、setuptools.command.sdistモジュールへのパッチを提出することを考えてもよいです。そうすれば、我々はあなたのシステムへの対応を含めることができます）。

パッケージをEasyInstallで利用できるようにする

もしあなたがregisterコマンド (setup.py register) コマンドを使って、PyPIにパッケージを登録していたら、それはここでの勝利のほとんどです（詳細については、docs for the register commandを参照してください）。

またもしuploadコマンドを使ってパッケージの実際の配布物をアップロードしていたら、それは同じようによいです。なぜならば、EasyInstallはあなたのプロジェクトのPyPIのページからそれらを探して直接ダウンロードできるからです。

しかしながら、PyPIに配布物をアップロードしたくない理由があるかもしれませんし、代わりに既に存在している配布物だけ（かSubversionのチェックアウト）を欲しいかもしれません。

このため、registerコマンドを実行する前に必要なことを以下に記します。EasyInstallに影響を与えるsetup()の引数が3つあります:

  • urlとdownload_url

これらは、プロジェクトのPyPIページへのリンクです。EasyInstallは、これらがパッケージにリンクしているか調べるため（「プライマリリンク」）、あるいはこれらがHTMLページであるか調べるため、これらにアクセスします。もしHTMLページであったら、EasyInstallはページ中のすべてのHREFを走査し、プライマリリンクを探します。

  • long_description

EasyInstallは、この引数に含まれるURLをすべて調査して、これらがプライマリリンクではないかどうか調べます。

あるリンクが.tar.gzや.tgz, .zip, .egg, .egg.zip, .tar.bz2, .exeへのリンクであるか、リンクに#egg=projectか#egg=project-versionという断片的な識別子がついていたら、そのURLは「プライマリリンク」だとみなされます。EasyInstallは、ダウンロードせずに、プライマリリンクのテキストからプロジェクトの名前と付加されているバージョン番号を決定しようと試みます。もしすべてのプライマリリンクを発見したら、EasyInstallは要求されているバージョンとプラットフォームの互換性、他の条件にもっともマッチするものを選択します。

このため、urlかdownload_urlがダウンロード可能なソース配布物や、直接的なリンクを持つHTMLページを指していたら、EasyInstallは自動的にダウンロードを探し当てられます。もしSubversionのチェックアウトを利用したいなら、URLに付加されている#egg=projectか#egg=project-versionを使って、リンクを作成しなければなりません。プロジェクトとバージョンを、eggファイル名に持っている値に置換しなければなりません（プロジェクト名とバージョン番号のエスケープされた形式がなんであるか推測しようとするのではなく、実際にeggを生成して、ファイル名の最初の部分を使うことを、覚えておいてください）。

Subversionのチェックアウトへのリンクは、他の種類の配布物よりも優先度が低く、そのためEasyInstallは#egg=接尾語にバージョンがなく、プロジェクトへの他のすべてのリンクでEasyInstallがみたバージョンよりも高いバージョンでない限り、EasyInstallはSubversionのチェックアウトをダウンロードに選択しません。

結果として、チェックアウトのURLを"dev"バージョンで印を付ける（すなわち、#egg=projectname-dev）のは共通のプラクティスであり、ユーザは以下のようにできます: 

easy_install --editable projectname==dev

これにより、projectnameの開発バージョンをチェックアウトできます。

Subversionを使って「継続リリース」を管理する

Subversionを使って、ユーザが開発中のバージョンを追いかけることを期待するのであれば、少しのことを行うことで、EasyInstallを使って物事がスムーズに進むことを保証できます。最初に、プロジェクトのsetup.cfgファイルに以下を追加します: 

[egg_info]
tag_build = .dev
tag_svn_revision = 1

これにより、setuptoolsは1.0a1.dev-r1263のようなパッケージのバージョン番号を生成し、これは1.0a1より古いリリースだとみなされます。よって、実際に1.0a1をリリースしたとき、eggの環境全体（setuptoolsとpkg_resources, EasyInstallを含む）は、1.0a1がSubversionからのすべての当面のスナップショットと置き換わったことを知り、それによって適切に更新します（注意: setup.pyで指定したバージョン番号は常に、ソフトウェアの次のバージョンであり、最後にリリースされたバージョンではありません。代わりに、tag_build=.devを除外して、バージョン番号として常に最後のリリースを使うことができ、これによって1.0のあとのビルドは1.0-r1263とラベルづけされます。これは1.0のあとのパッチレベルを示します。しかし、ほとんどのプロジェクトではここまでは、開発中の間は将来のバージョンとして考え、パッチを当てられたポストバージョンとは考えない方が好ましいと思われます。もちろん、単一のプロジェクトにおいては、両方の状況もあり得、リリースブランチにポストリリース番号をつけ、trunkにプレリリース番号をつけます。しかし、そうしたいと思わない限り、物事を複雑にすべきではありません）。

共通のこととして、Subversionからコードをリリースするプロジェクトは、#egg=projectname-dev接尾語を使って、チェックアウトURLへのPyPIのリンクを含みます（前の節で述べた通り）。これにより、ユーザは、EasyInstallでprojectname==devをダウンロードすることができ、最新の開発コードを得ることができます。もしプロジェクトがそのような開発中のコードに依存している場合、install_requires（か他の必要とするもの）に==devを含むように望むでしょう: 

install_requires = ["OtherProject>=0.2a1.dev-r143,==dev"]

上の例は、「私は少なくともこの特定の開発リビジョン番号を求めているのであるが、もし#egg=OtherProject-devを見つけたら、そのリンクを使うのにはやぶさかではない」ことを意味します。これにより、利用可能な開発中のコードのスナップショットの、実際のソースかバイナリの配布物が必要になることを回避できます。ちょうど、プロジェクトが提供している最新でもっとも偉大なものに依存できるようになります。

Subversionでの開発において、最後の注意です: もしSVNリビジョンタグをこの節で述べたように使っていたら、Subversionにチェックインするか更新したあとに毎回、setup.py developを実行するのはいい考えです。なぜならば、プロジェクトのバージョン番号が変わり、それに応じてスクリプトのラッパーを更新する必要があるからです。

また、プロジェクトが要求しているものが変わったら、変更された拡張子をビルドするなどして、developコマンドは更新された依存関係に気をつけます。また、Subversionからプロジェクトをチェックアウトするすべてのユーザに、彼らのチェックアウトを完全に同期させるため、更新したあと毎回、setup.py developを実行する必要があることを、思い出させるようにしてください。

  • 「公式」（非スナップショット）リリースを作成する

ソースかバイナリの配布物を作成し、公式リリースを行ったら、setup.cfgのタグの設定を上書きし、foobar-0.7a1.dev-r34832のようなバージョンを登録して終わらないようにします。これをするのは、trunkで開発し、リリースにtagsかbranchesを使っていたら、簡単にできます - リリースをブランチするかタグづけしたあとにsetup.cfgを変更するだけで、trunkは依然開発のスナップショットを作成します。

代わりに、リリースのためにブランチしないのであれば、以下のようにして、コマンドラインのデフォルトのバージョンに関するオプションを上書きできます: 

python setup.py egg_info -RDb "" sdist bdist_egg register upload

このコマンドの最初の部分 (egg_info -RDb "") は、ソースとバイナリのeggを作成する前に、設定されているタグ情報を上書きし、PyPIにプロジェクトを登録し、ファイルをアップロードします。したがって、このコマンドはsetup.pyからの何も付加されていないバージョンを使用し、Subversionのリビジョン番号やビルドの設計文字列をつけたりしません。

もちろん、これをたくさん行うのであれば、この操作に対して個人的なエイリアスを作ろうと思うでしょう。例えば: 

python setup.py alias -u release egg_info -RDb ""

そうすると、これを以下のように使用できます: 

python setup.py release sdist bdist_egg register upload

あるいはもちろん、上のすべてを実行するもっと入念ななエイリアスを作成することもできます。より多くのアイデアは、下の「egg_info - eggのメタデータを作成し、ビルドタグを設定する」と「alias - よく使うコマンドをショートカットに定義する」の節を参照してください。

Pyrexを使って拡張を配布する

setuptoolsは、distutils.Extensionではなくsetuptools.Extensionを使って拡張を定義している限り、Pyrexの拡張をビルドするのに透過的に対応します。セットアップスクリプトで、Pyrexから何もインポートする必要もありません。

これらの規則に従っている限り、セットアップスクリプトでExtensionオブジェクトのソースとして.pyxファイルを安全に並べられます。setuptoolsはビルドするときに、どのPyrexがインストールされているかそうでないか検出します。もしインストールされていたら、setuptoolsはそれを使います。もしインストールされていなければ、setuptoolsは静かにExtensionオブジェクトを、.pyxファイルの.cの片割れを参照するように変更し、そして通常のdistutilsのC言語のコンパイル処理が実行されます。

もちろん、こうするためには、オリジナルの.pyxファイルだけでなく、Pyrexが生成したC言語のコードもソースの配布物の中に含まなければなりません。これは、あなたはおそらくバージョン管理システムに現在の.cファイルを含めようとし、.pyxソースファイルを変更するごとに、.cファイルを再ビルドしようとすることを意味します。これにより、CVSかSubversionでプロジェクトを追いかけている人たちは、Pyrexをインストールしていなくても、プロジェクトをビルドでき、Pyrexがあってもなくても、ソースのリリースは同じように使えるようになります。

コマンドリファレンス

alias - よく使うコマンドをショートカットに定義する

ときには、いつも同じコマンドを使う必要があり、しかしそれをデフォルトに設定する必要がない場合があります。例えば、あるプロジェクトの開発のスナップショットリリースと「安定」リリースを両方とも作成し、それらの配布物を異なる場所に置くか、あるいは異なるegg_infoタグづけオプションを使う、などといった場合です。これらの場合、distutilsの設定ファイルにそのオプションを設定するのには意味があります。なぜならば、それらのオプションの値はあなたが何をしようとしているかによって変わるからです。

そのため、setuptoolsでは「エイリアス」を定義することができます - エイリアスは、コマンドとオプションの任意の文字列のショートカット名で、setup.py alias aliasname expansionを使います。ここで、aliasnameは新しいエイリアスの名前で、コマンドの残りは展開部分です。例えば、このコマンドが"daily"と呼ばれるサイト全体のエイリアスを定義し、そのエイリアスは様々なegg_infoのタグづけオプションを設定します: 

setup.py alias --global-config daily egg_info --tag-svn-revision \
    --tag-build=development

いったんエイリアスが定義されたら、他のセットアップコマンドと一緒に使用できます。例えば: 

setup.py daily bdist_egg        # 日ごとの.eggファイルを生成します
setup.py daily sdist            # 日ごとのソースの配布物を生成します
setup.py daily sdist bdist_egg  # 両方とも生成します

上のコマンドでは、dailyがegg_info --tag-svn-revision --tag-build=developmentと置換されたように解釈されます。

setuptoolsは、与えられたコマンドラインで、各エイリアスを多くても一回展開することに注意して下さい。これにはふたつの目的があります。ひとつ目は、エイリアスのループを不意につくってしまったとしても、何の効果もありません; あなたは不明なコマンドに関するエラーメッセージを代わりに受け取ることでしょう。ふたつ目に、コマンドに対するエイリアスを定義できるようになり、そのエイリアスではそのコマンドを使用します。例えば、この（プロジェクトに固有の）エイリアスです: 

setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg

これは、bdist_eggコマンドを再定義し、最新のeggファイルを除くすべてのファイルを削除するrotateコマンドを毎回あとで実行するようにします。bdist_eggにおいて無限にループしません。なぜならば、このエイリアスは使用されたとき、たった一回だけ展開されるからです。

    • remove（か-r）オプションで、定義されたエイリアスを削除できます。例えば: 
setup.py alias --global-config --remove daily

これは、上で定義した"daily"エイリアスを削除します。

エイリアスは、プロジェクトごとか、ユーザごとか、サイト全体について定義できます。デフォルトはプロジェクトごとのエイリアスを定義したり削除したりしますが、設定ファイルのオプション（下の"saveopts"コマンドの下に一覧があります）を使用して、どのdistutilsの設定ファイルにエイリアスを追加するか（あるいは削除するか）決定できます。

もしaliasコマンドの「展開部分」の引数を省略したら、エイリアスの現在の定義（と、どの設定ファイルで定義されているか）が表示されます。エイリアス名も省略したら、現在のすべてのエイリアスが、設定されているファイルとともに表示されます。

bdist_egg - プロジェクトのPython Eggを作成する

このコマンドは、プロジェクトのPython Egg（.eggファイル）を生成します。Python EggはEasyInstallのためのバイナリの好ましい配布形式です。なぜならば、Python Eggは（「ピュアな」パッケージについては）クロスプラットフォームで、直接インポート可能で、スクリプトとプロジェクトの依存関係に関する情報を含むプロジェクトのメタデータを持っています。Python Eggは単純にダウンロードでき、sys.pathに直接追加でき、あるいはsys.pathにあるディレクトリに置いて、eggの実行時のシステムが自動的に発見できるようにできます。

このコマンドはegg_infoコマンドを実行し（もしまだ実行されていなければ）、プロジェクトのメタデータディレクトリ (.egg-info) を更新します。もし追加のメタデータファイルを.egg-infoディレクトリに追加したら、それらのファイルは新しいeggファイルのメタデータディレクトリに含まれるようになり、eggの実行時のシステムかそのメタデータを使うなんらかのアプリケーションかフレームワークが使用します。

通常は、このコマンドに特別なオプションを指定する必要はないでしょう; 単にbdist_eggを使えば、完了です。しかし、時折使い易いいくつかのオプションがあります:

  • --dist-dir=DIR, -d DIR

.eggファイルが置かれるディレクトリを設定します。もしこれを省略したら、bdistコマンドの--dist-dirの設定が使用され、これは普通、プロジェクトディレクトリのdistという名前のディレクトリです。

  • --plat-name=PLATFORM, -p PLATFORM

eggのファイル名に組み込まれるプラットフォームの名前の文字列を設定します（eggがC言語の拡張を持っていると仮定して）。これにより、distutilsのデフォルトのプラットフォーム名を、より意味のあるものに上書きすることができます。しかし、eggの実行時のシステムは、distutilsのプラットフォーム名とともにeggを見ることを期待していて、そのため非標準のプラットフォーム名を持つeggを無視するか拒否することを、覚えておいて下さい。同じように、EasyInstallプログラムは、ウェブページからダウンロードのリンクを探すときに、これらを無視します。しかし、もしクロスコンパイルした場合や、それ以外の普通ではないことをした場合は、このオプションの使い道に気づくでしょう。

  • --exclude-source-files

eggにモジュールの.pyファイルを含めず、コンパイルされたPythonと、C言語、データファイルだけを含めるようにします（これはEGG-INFOディレクトリとそのサブディレクトリにある.pyファイルには影響を与えません。そのため例えば、いまだに保持されなければならない.py拡張子のスクリプトを含めることができます）。プロプライエタリなエンドユーザが使用するアプリケーションにバンドルされるパッケージか、容量が絶対的に貴重な「組み込み」のシナリオ以外で、このオプションを使用するのは推奨しません。一方、パッケージが圧縮された形式でインストールされて使用されるなら、ソースを削除しても構いません。なぜならば、Pythonのtracebackモジュールは現在のところ、zipで圧縮されたソースコードをどのように表示するのか、あるいはコードがコンパイルされたのと違うところにあるファイルをどのように扱うのか、理解していないからです。

おそらく決して必要にならないであろうオプションもあります。しかし、これを作成するための例として使用した、似ているbdistコマンドからコピーしたため、それらは存在します。テストやデバッグのときには有用かもしれませんが、それが、これらを持ちつづけている理由です:

  • --keep-temp, -k

.eggファイルを作成したあと、--bdist-dirツリーの内容を保存しつづけます。

  • --bdist-dir=DIR, -b DIR

配布物を作成するための一時ディレクトリを設定します。パッケージのモジュールやデータ、拡張をコピーするための様々なインストールコマンドが実行された後、このディレクトリの内容物すべてが、.eggファイルをつくるためにzipで圧縮されます。

  • --skip-build

"build"コマンドを実行しません; インストールと圧縮フェーズをただちに実行します。

develop - 「開発モード」でプロジェクトのソースを配布する

このコマンドにより、プロジェクトがインポートできるひとつ以上の"staging areas"にある、プロジェクトのソースをデプロイできます。このデプロイは、プロジェクトのソースを変更するごとにビルドやインストールを実行する必要なしに、プロジェクトのソースへの変更をただちに利用できる方法で行われます。

developコマンドは、与えられたstaging areaで.egg-linkファイル（プロジェクトのために名前がつけられています）を作成することで動作します。そのstaging areaがPythonのsite-packagesディレクトリなら、developコマンドはeasy-install.pthファイルも更新し、そのためプロジェクトは、そのインストールされているPythonを使うすべてのプログラムで、最初からsys.path上に存在します。

developコマンドはまた、staging area（か、指定されていたら別のディレクトリ）にラッパースクリプトをインストールし、そのスクリプトは、プロジェクトのソースのスクリプトを実行する前に、プロジェクトが依存しているものがsys.path上に存在することを保証します。そして、staging sraeでプロジェクトが依存しているものが見つからなかったら、必要であればそれらをダウンロードしてインストールし、使えるように保証します。

最後に、とりわけ、developコマンドはbuild_ext -iコマンドを実行して、プロジェクト内のすべてのC言語の拡張がビルドされ、最新であることを保証し、egg_infoコマンドを実行し、プロジェクトのメタデータが更新されることを保証します（そのためランタイムとラッパーは、プロジェクトが依存しているものがなにか知っています）。もしプロジェクトのセットアップスクリプトかC言語の拡張になんらかの変更を加えたら、developコマンドをすべての関連したstaging areaに対して再実行し、プロジェクトのスクリプトとメタデータ、拡張が最新であるようにしなければなりません。プロジェクトに加えるそれ以外のほとんどの変更は、ビルド作業やdevelopコマンドの実行を要求しませんが、セットアップスクリプトを少しでも変更したら（例えばエントリポイントの定義を変更する）、developコマンドかtestコマンドを再実行し、配布物が最新であるようにしなければならないことを覚えておいてください。

developコマンドには、いくつかのオプションがあります。これらはプロジェクトそのものだけではなくプロジェクトが依存しているものにも影響を与え、そのためもしインストールされ、（例えば）--exclude-scriptsを使用しなければならないものに依存していたら、その依存しているスクリプトもインストールされないことに注意してください! このため、もし依存しているものについてインストールのオプションをより詳細に制御する必要があったら、developコマンドを実行する前に、プロジェクトが依存しているものをインストールするためにEasyInstallを使用したいと思うでしょう。

  • --uninstall, -u

現在のプロジェクトをアンインストールします。--install-dirか-dオプションを使って、staging areaを明示できます。もし.egg-linkファイルが作成され、プロジェクトのディレクトリをまだ指していたら、これは削除されます。staging areaがPythonのsite-packagesディレクトリだったら、プロジェクトのディレクトリはeasy-install.pthから削除されます。

このオプションは現在のところ、スクリプトのラッパーをアンインストールしないことに注意してください! あなたは自分でそれらをアンインストールし、あるいはEasyInstallを使ってそれらを上書きし、パッケージの違うバージョンが使えるようにしなければなりません。もしプロジェクトをデプロイするためにdevelopコマンドを実行するとき、--exclude-scripts（aka -x）を使っていたら、最初の場所にスクリプトのラッパーをインストールするのを回避することもできます。

  • --multi-version, -m

「マルチバージョン」モードです。このオプションを指定すると、developコマンドはデプロイされるプロジェクトをeasy-install.pthのエントリに加えなくなり、もしプロジェクトのなんらかのバージョンのエントリがすでに存在していたら、そのエントリはデプロイが成功したら削除されます。マルチバージョンモードでは、pkg_resources.require()を使ってプロジェクトをsys.pathに置いていない限り、あるいはsetuptoolsかEasyInstallによって生成されたラッパースクリプトを実行している（この場合、ラッパースクリプトはrequire()を呼び出します）のではない限り、パッケージの特定のバージョンをインポートできません。

もしsite-packages以外のディレクトリにインストールするのであれば、このオプションは自動的に効果を持ちます。なぜならば、.pthファイルはsite-packagesにおいてのみ使用可能だからです（少なくともPython 2.3と2.4では）。そのため、--install-dirか-dオプションを使ったら（あるいは設定ファイルを通して設定されていたら）、プロジェクトとプロジェクトが依存しているものはマルチバージョンモードでデプロイされます。

  • --install-dir=DIR, -d DIR

インストールディレクトリ (stagin area) を設定します。もしこのオプションがコマンドラインかdistutilsの設定ファイルでで直接指定されていなければ、distutilsのデフォルトのインストール場所が使用されます。通常、これはsite-pakcagesディレクトリですが、もしdistutilsの設定ファイルを使っていて、接頭語やinstall_libのような項目を設定していたら、デフォルトのstaging areaを決定するのにそれらの設定が関ってきます。

  • --script-dir=DIR, -s DIR

スクリプトをインストールするディレクトリを設定します。もしこのオプションを指定せず（コマンドラインか設定ファイルで）、しかし--install-dirを与えていたら、（コマンドラインか設定ファイルで）、このオプションのデフォルト値は同じディレクトリになり、そのためスクリプトは関連しているパッケージのインストールが探すことができます。一方、この設定のデフォルト値はdistutilsが通常スクリプトをインストールする場所になり、distutilsのあらゆる設定ファイルの設定が関ってきます。

  • --exclude-scripts, -x

スクリプトのラッパーをデプロイしません。staging areaにある既存のバージョンのスクリプトにわずらわされたくない場合、これは有用です。

  • --always-copy, -a

たとえsys.path上の他のディレクトリに既に存在していたとしても、staging areaに必要な全てのスクリプトをコピーします。デフォルトでは、sys.pathにあるディレクトリ中に既に存在する配布物を使って、必要条件を満たすことができる場合、staging areaにはコピーされません。

上のオプションに加えて、developコマンドはeasy_installが受け付けるのと同じオプションをすべて受け付けます。もしsetup.cfg（か他のdistutilsの設定ファイル）でeasy_installのなんらかの設定を行っていた場合、[develop]セクションで上書きするか、コマンドラインで上書きしない場合、developコマンドはそれらをデフォルトとして使用します。

easy_install - パッケージを探し、インストールする

このコマンドは、EasyInstall toolを実行します。これはeasy_installコマンドを実行するのとまったく同じです。このコマンドに続くすべてのコマンドライン引数は消滅させられ、distutilsによってそれ以上処理されず、したがってこのコマンドは、コマンドラインに並べる中で、最後のコマンドである必要があります。オプションのリファレンスと使い方の例については、EasyInstallのドキュメントを参照してください。通常、このコマンドをコマンドラインから使う理由はありません。easy_installを直接使用すればよいのです。このコマンドはここに並べられているだけで、これはこのコマンドがdistutilsコマンドであり、

  • コマンドのエイリアスを作成でき、
  • このコマンドをサブコマンドとして起動するdistutilsの拡張を作成でき、
  • setup.cfgや他のdistutilsの設定ファイルでオプションを設定できる

ことを意味します。

egg_info - eggのメタデータを作成し、ビルドタグを設定する

このコマンドはふたつのことを行います: このコマンドはプロジェクトの.egg-infoメタデータディレクトリ（bdist_eggとdevelop, testコマンドに使用されます）を更新し、プロジェクトのバージョン文字列を一時的に変更し、「デイリービルド」や「スナップショット」リリースができるようにします。このコマンドはsdistとbdist_egg, develop, register, testコマンドによって自動的に実行され、プロジェクトのメタデータを更新します。しかしメタデータを明示的に指定することも可能で、他のコマンドが実行している間、プロジェクトのバージョン文字列を一時的に変更できるようになります（このコマンドは``.egg-info/SOURCES.txt``マニフェストファイルも生成します。このファイルは、ソース配布物を生成するときに使用されます）。

setuptoolsによって定義され、pkg_resourcesによって必要とされている核となるeggのメタデータを書き込むのに加え、egg_info.writersグループ中にエントリポイントを定義することで、このコマンドは他のメタデータファイルを書くように拡張できます。詳細は、下の「新しいEGG-INFOファイルを追加する」を参照してください。追加したメタデータを書き込む拡張を使うときは、setup()にsetup_requires引数を与える必要があり、これにより希望する拡張がsys.path上にあることが保証されます。

  • リリースに使用するタグ付けのオプション

セットアップのコマンドラインの残りのすべてのコマンドに対し、プロジェクトのバージョン文字列を変更するために、以下のコマンドが使用できます。オプションは記述されている順序で処理され、そのためもしふたつ以上のオプションを使用したら、必要とされているタグは、以下の順所で追加されます:

  • --tag-build=NAME, -b NAME

プロジェクトのバージョン文字列にNAMEを追加します。"a"から"e"までの文字から始まる「プレリリース」バージョンの接頭語（"alpha"や"beta", "candidate"）をsetuptoolsが処理する方法により、プロジェクトのデフォルトのバージョンよりバージョン番号が低くみなされるようにするため、あなたは普通".build"や".dev"といったタグを使用したいと思うでしょう（もしバージョン番号をデフォルトのバージョンよりも高くしたかったら、常に--tag-buildを使用せず、以下のオプションを使用します）。

もしデフォルトのビルドタグの組み合わせをsetup.cfgに設定していたら、コマンドラインで-b ""か--tag-build=""をegg_infoコマンドの引数に使って、それを抑止することができます。

  • --tag-svn-revision, -r

もしカレントディレクトリがSubversionのチェックアウトであったら（つまり、.svnサブディレクトリを持っていたら）、このオプションは"-rNNNN"の形式で文字列をプロジェクトのバージョン文字列に追加します。ここでNNNNは、カレントディレクトリにもっとも最近加えられたリビジョン番号で、svn infoコマンドで得られます。

カレントディレクトリがSubversionチェックアウトでなければ、このコマンドは代わりにPKG-INFOファイルを探し、そこからリビジョン番号を探そうとします。これは、バージョン番号の終わりから"-rNNNN"という文字列を探すことで、行われます（これにより、Subversionのスナップショットのソース配布物からビルドされたパッケージは、正しいバージョン番号を持つバイナリを作成します）。

もしPKG-INFOファイルがないか、その中のバージョン番号が-rと番号で終わらなければ、-r0が使用されます。

  • --no-svn-revision, -R

バージョン番号に、Subversionのリビジョンを含みません。このオプションは、setup.cfgに含まれるデフォルトの設定を上書きできるようにするため、存在します。

  • --tag-date, -d

"-YYYYMMDD"（例えば"-20050228"）の形式で、日付をプロジェクトのバージョン番号に追加します。

    • no-date, -D

バージョン番号に、日付を含みません。このオプションは、setup.cfgに含まれるデフォルトの設定を上書きできるようにするため、存在します。

（注意: これらのオプションはプロジェクトのソースの配布物とバイナリの配布物に使用されるバージョン番号を変更するため、あなたはまず、結果として得られたバージョン番号がEasyInstallのような自動ツールにどのように解釈されるのか、知っているか確認しなければなりません。上の「プロジェクトのバージョンを指定する」で、プロジェクトのバージョンスキーマを選択し、変更する方法だけでなく、プレリリースタグやポストリリースタグの説明を読んでください）。

より高度な使い方として、設定可能なもうひとつのオプションがあり、プロジェクトの.egg-infoディレクトリの場所を変更できます。プロジェクトのソースディレクトリやメタデータを探す必要があるコマンドは、この設定から得ることができます:

  • 他のegg_infoのオプション
    • --egg-base=SOURCEDIR, -e SOURCEDIR

.egg-infoディレクトリがあるディレクトリを指定します。これは通常、プロジェクトのソースツリーのルートです（これはプロジェクトディレクトリと同じである必要はありません; 複数のプロジェクトが、ソースのルートとしてひとつのsrcやlibサブディレクトリを使用します）。通常、このディレクトリを指定する必要はありません。なぜならば、もしあれば、setup()関数のpackage_dir引数から普通は決定できるからです。package_dirが設定されていない場合は、このオプションの初期値はカレントディレクトリになります。

    • - egg_infoの例

日付がつけられた「ナイトリービルド」のスナップショットのeggをつくるときは: 

python setup.py egg_info --tag-date --tag-build=DEV bdist_egg

setup.cfgでデフォルトのタグが設定されていても、バージョンタグをつけないでリリースを作成してアップロードする場合は: 

python setup.py egg_info -RDb "" sdist bdist_egg register upload

（egg_infoコマンドは、バージョンの変更を適用したいと思う他のコマンドより前に、コマンドラインになければならない点に注意してください）

install - easy_installか、古いスタイルのインストールを実行する

setuptoolsのinstallコマンドは基本的に、現在のプロジェクトのeasy_installコマンドを実行するショートカットです。しかし、setuptoolsに基づいたプロジェクトの「システムパッケージ」を作成するときに便利なように、以下のオプションを使うこともできます:

  • --single-version-externally-managed

この真偽値のオプションにより、installコマンドは「古いスタイル」のインストールを実行して、.egg-infoディレクトリを追加するようになり、そのためインストールされたプロジェクトはいまだにメタデータを使うことができ、普通に動作します。このオプションを使用したら、--rootか--recordオプション（かその両方）も指定しなければなりません。なぜならば、一方で、インストールされたファイルを識別し、削除する方法がないからです。

このオプションは、他のdistutilsコマンドによってinstallコマンドが起動されたとき、自動的に効果を持つようになります。それにより、bdist_wininstやbdist_rpmといったコマンドはeggのシステムパッケージを作成します。--rootオプションを指定したときも、同じように自動的に有効になります。

install_egg_info - site-packagesに.egg-infoディレクトリをインストールする

setuptoolsはこのコマンドを、--single-version-externally-managedオプションを使ったinstallの動作の一部として実行します。これを直接起動する必要はありません; このコマンドは、ドキュメントを完全なものにするためにここに書かれているのであり、これにより、システムパッケージビルダーのようなdistutilsの拡張がこれを使うことができます。このコマンドは、ひとつのオプションのみを持っています:

  • --install-dir=DIR, -d DIR

.egg-infoディレクトリが置かれる親ディレクトリを指定します。デフォルトはinstall_libコマンドに与えられた--install-dirオプションと同じで、これは普通システムのsite-packagesディレクトリです。

このコマンドは、egg_infoコマンドはコマンドラインかsetup.cfgから適切なオプションを与えられていると仮定し、それによりこのコマンドはegg_infoコマンドを起動し、プロジェクトのソースの.egg-infoディレクトリを配置するためにegg_infoコマンドのオプションを使用します。

rotate - 古いファイルを削除する

プロジェクトの新しいバージョンを開発したら、あなたの配布物ディレクトリ (dist) は、古いソースやバイナリの配布物のファイルで次第にいっぱいになるでしょう。rotateコマンドを使えば、これらを自動的に削除でき、指定されたパターンにマッチする、もっとも最近変更されたN個のファイルだけを持つことができます。

  • --match=PATTERNLIST, -m PATTERNLIST

ファイル名にマッチするためのパターンの、コンマで区切られたリストです。このオプションは必須です。プロジェクト名と-*は与えられたパターンにprependedで、これにより現在のプロジェクトに属する配布物のみをマッチできます（複数プロジェクトで配布物のディレクトリを共有していることを想定しています）。典型的には、.zipや.eggといったパターンを使用し、指定されたタイプのファイルにマッチするようにします。それぞれの与えられたパターンは、削除するファイルを選択するために、個別のグループとして扱われることに注意してください。

  • --keep=COUNT, -k COUNT

保持する、マッチする配布物の数です。--matchオプションで指定されたパターンで識別されるファイルの各グループについて、そのグループ内でCOUNT個のもっとも最近変更されたファイルを除いて、すべてのファイルを削除します。このオプションは必須です。

  • --dist-dir=DIR, -d DIR

配布物があるディレクトリです。デフォルト値はbdistコマンドの--dist-dirオプションの値で、これは普通プロジェクトのdistサブディレクトリです。

例1: 3つのもっとも最近変更されたファイルを除いて、配布物のディレクトリからすべての.tar.gzファイルを削除します: 

setup.py rotate --match=.tar.gz --keep=3

例2: 各Pythonのバージョンについて、もっとも最近変更されたひとつを除いて、配布物のディレクトリからPython 2.3かPython 2.4のeggをすべて削除します: 

setup.py rotate --match=-py2.3*.egg,-py2.4*.egg --keep=1
saveopts - 設定ファイルに使用したオプションを保存する

distutilsの設定ファイルを探して編集するのは苦痛です。なぜならばとくに、設定のオプションをコマンドラインの形式から適切な設定ファイルの形式にも翻訳しなければならないからです。saveoptsコマンドを使えば、このような混乱を回避することができます。このオプションをコマンドラインに追加するだけで、使っているオプションを保存できます。例えば、このコマンドがmingw32 Cコンパイラを使っているプロジェクトをビルドするとき、将来のビルドのために--compilerの設定をデフォルト値として保存します（installコマンドから暗黙的に実行されるときでも）: 

setup.py build --compiler=mingw32 saveopts

saveoptsコマンドは、プロジェクトのローカルのsetup.cfgファイルに、コマンドライン上で指定されたすべてのコマンドについてすべてのオプションを保存します。ただし、オプションが保存されている設定ファイルのオプションのひとつを、変更するために使用し他場合は、この限りではありません。例えば、以下のコマンドは上と同じことをしますが、コンパイラの設定をサイト全体の（グローバルの）distutilsの設定に保存します: 

setup.py build --compiler=mingw32 saveopts -g

saveoptsコマンドをコマンドラインのどこに置くかは、問題ではないことに注意してください; このコマンドはすべてのコマンドについて、指定されたオプションをすべて保存します。例えば、以下は上の例を記述する、もうひとつの正当なやりかたです: 

setup.py saveopts -g build --compiler=mingw32

しかし、saveoptsがコマンドラインのどこに置かれようが、指定されたコマンドのすべてが常に実行されることに注意してください。

  • 設定ファイルのオプション

通常、オプションやエイリアスといった設定は、プロジェクトのローカルのsetup.cfgファイルに保存されます。しかし、これを上書きし、グローバルかユーザごとの設定ファイルか、手動で指定されたファイルに保存することができます。

  • --global-config, -g

設定を、distutilsパッケージディレクトリの中にあるグローバルのdistutils.cfgファイルに保存します。このオプションを使うにあたり、あなたはそのディレクトリに書き込む権限を持っていなければなりません。このオプションを、-uや-fと組み合わせて使うことはできません。

  • --user-config, -u

設定を、現在のユーザの~/.pydistutils.cfg (POSIX) か$HOME/pydistutils.cfg (Windows) ファイルに保存します。このオプションを-gや-fと組み合わせて使うことはできません。

  • --filename=FILENAME, -f FILENAME

設定を、指定された設定ファイルに保存します。このオプションを-gや-uと組み合わせて使うことはできません。もし非標準のファイル名を指定したら、distutilsとsetuptoolsはそのファイルの内容を使用しないでしょう。このオプションは主に、テストで使用するために含まれています。

これらのオプションは、設定ファイルを書き換える、aliasやsetoptといったコマンドが使います。

setopt - distutilsかsetuptoolsのオプションを設定ファイルに設定する

このコマンドは主にスクリプトが使いますが、どのファイルにオプションが設定されていたか思い出してエディタを開くことなく、distutilsの設定のオプションを変更する、素早くダーティな方法としても使われます。

例1. デフォルトのCコンパイラをmingw32に設定します（長いオプション名を使用します）: 

setup.py setopt --command=build --option=compiler --set-value=mingw32

例2. distutilsの、デフォルトでパッケージがインストールされるディレクトリの設定を、すべて削除します: 

setup.py setopt -c install -o install_lib -r

setoptコマンドのオプションは、以下の通りです:

  • --command=COMMAND, -c COMMAND

オプションを設定するコマンドです。このオプションは必須です。

  • --option=OPTION, -o OPTION

設定するオプションの名前です。このオプションは必須です。

  • --set-value=VALUE, -s VALUE

オプションに設定する値です。-rか--removeが設定されていたら、必要ありません。

  • --remove, -r

設定する代わりに、オプションを削除します。

上のオプションに加えて、任意の設定ファイルのオプション（上のsaveoptsコマンドで記述されています）を使用することができ、オプションが追加される（あるいは削除される）distutilsの設定ファイルを指定できます。

test - パッケージをビルドしてユニットテストスイートを実行する

テスト駆動開発をしているとき、あるいは、ダウンロードするか使うためにデプロイされる前にテストすることが必要な自動化されたビルドを実行するとき、developコマンドを使っていたとしても、実際にプロジェクトをどこかにデプロイすることなしに、プロジェクトのユニットテストを実行できるというのは、便利なことです。testコマンドはプロジェクトのユニットテストを、実際にデプロイすることなしに実行します。これは、最初にbuild_ext -iとegg_infoを実行し、すべてのC言語の拡張とプロジェクトのメタデータが最新であることを保証したのち、一時的にsys.path上にプロジェクトのソースを置いて行われます。

このコマンドを使うにあたり、プロジェクトのテストは、関数かTestCaseクラスかメソッドか、TestCaseクラスを持つモジュールかパッケージによって、unittestテストスイートの中にラップされていなければなりません。もし指定されたスイートがモジュールであり、そのモジュールがadditional_tests()関数を持っていたら、この関数は呼び出され、その戻り値（これはunittest.TestSuiteでなければなりません）は、実行されるテストに追加されます。指定されたスイートがパッケージならば、すべてのサブモジュールとサブパッケージが再帰的にテストスイートに追加されます（注意: プロジェクトがtest_loaderを指定していたら、選択されたtest_suiteを処理する規則は違ってきます; 詳細は、test_loaderのドキュメントを参照してください）。

doctestを含む多くのテストシステムが、TestSuiteオブジェクトが持つユニットテストではないテストをラップすることに対応しています。このため、もしこれに対応していないテストパッケージを使用していたら、それの開発者たちにテストスイートに対応するよう催促することを提案します。なぜならば、これが共通のテストハーネスの下で実行されるテストの集合に集約する便利で標準的な方法だからです。

デフォルトでは、テストはunittestパッケージのテキストテストランナーの「冗長」モードで実行されますが、セットアップスクリプトへのグローバルオプションとしてか（すなわち、setup.py -q test）、testコマンド自身へのオプションとして（すなわち、setup.py test -q）、-qオプションか--quietオプションを指定すれば、「静かな」モード（ドットだけ）で実行できます。この他に、ひとつのオプションがあります:

  • --test-suite=NAME, -s NAME

実行されるテストスイート（またはモジュールかクラス、メソッド）を指定します（すなわち、some_module.test_suite）。このオプションのデフォルト値は、setup()関数のtest_suite引数として設定することができます: 

    setup(
        # ...
        test_suite = "my_package.tests.test_all"
    )

もしsetup()の呼び出しでtest_suiteを設定しておらず、--test-suiteオプションを与えていなかったら、エラーが発生します。

upload - ソースと配布物をPyPIにアップロードする

PyPIは現在、再配布のために、プロジェクトのファイルのアップロードに対応しています; プロジェクトのホームページにダウンロードのリンクがなくても、EasyInstallによってアップロードされたファイルは簡単に見つけられます。

Python 2.5ではPyPIにすべての種類の配布物をアップロードすることができますが、setuptoolsはソースの配布物とeggのみに対応しています（これが、他の様々な種類に対する、PyPIのアップロードへの対応が、現在は壊れていることの理由です）。ファイルをアップロードするためには、セットアップのコマンドラインでsdistかbdist_eggコマンドのあとにuploadコマンドを含めなければなりません。例えば: 

setup.py bdist_egg upload         # eggを作成し、アップロードする
setup.py sdist upload             # ソースの配布物を作成し、アップロードする
setup.py sdist bdist_egg upload   # 両方ともアップロードする

プロジェクトのファイルをアップロードするために、distutilsのregisterコマンドを使って、対応するバージョンがすでにPyPIに登録されている必要があります。コマンドラインの最初にregisterコマンドを含めるというのは通常いい考えで、これによって、配布物をビルドしてアップロードする前に、すべての登録する際の問題が発見され、修正されます。すなわち: 

setup.py register sdist bdist_egg upload

これはPyPIのリストを、プロジェクトの現在のバージョンで更新します。

ところで、setup()の呼び出しでのメタデータは、PyPIでパッケージに表示されるものを決定する点に注意してください。できる限りこれらを記述するようにしてください。なぜならば、こうすることでPyPIに表示される項目を手動で追加し更新するときの多くの問題を解決できるからです。setup.pyにこれらを設定し、registerコマンドを使うだけで、PyPIを最新の状態に保つことができます。

uploadコマンドは、記述する価値があるいくつかのオプションを持っています:

  • --sign, -s

アップロードする各ファイルをGPG (GNU Privacy Guard) で署名します。システムのPATHでgpgプログラムが実行可能になっていなければなりません。

  • --identity=NAME, -i NAME

署名する際に使用するGPGの識別子かキー名を指定します。このオプションの値は、gpgプログラムの--local-userオプションに渡されます。

  • --show-response

サーバからの応答をすべて表示します; これはPyPIの問題をデバッグする際に役に立ちます。

  • --repository=URL, -r URL

アップロードするリポジトリのURLです。デフォルトはhttp://www.python.org/pypi（すなわち、PyPIのメインのインストール）です。