http://neko-daisuki.ddo.jp/~SumiTomohiko/index.htmlこの広告は、90日以上更新していないブログに表示しています。setuptoolsこの記事についてこの記事は、id:SumiTomohiko:20070622:1182537643の続きです。setuptoolsに基づいたプロジェクトを配布するsetuptoolsを使用する...バンドルせずに!あなたのユーザは自分のマシンにsetuptoolsをインストールしていないでしょうし、あるいはもししていたとしても、正しいバージョンであるとは限りません。ez_setup.pyをダウンロードして、これをあなたのsetup.pyスクリプトと同じディレクトリに置けばいいです(ez_setup.pyをバージョン管理システムに追加するのを忘れないでください)。したら以下の2行を、セットアップスクリプトがsetuptoolsから何かをインポートする前に、あなたのセットアップスクリプトの先頭に追加します。ez_setupez_setup.use_setuptools()これで全部です。ez_setupモジュールは、setuptoolsが対象のシステムになければ、自動的にPyPIから適切なバージョンのsetuptoolsをダウンロードします。setuptoolsの新しいバージョンをインストールしたら常に、プロジェクトのez_setup.pyファイルも更新しなければなりません。これにより対象のマシンで適切なバージョンがインストールされるようになります。uploadを実行して、それぞれソースかeggの配布物をアップロードできます。registerで、登録することができます。すべてを1ステップでこなすこともできます。uploadは、パッケージを登録し、ソースとeggの配布物をビルドし、それからそれらを両方ともPyPIにアップロードします。PyPIでは、プロジェクトに依存する他のプロジェクトが、簡単にアップロードしたものを探し出すことができます(ところで、setuptoolsの特定のバージョンを配布する必要があるとき、use_setuptools()関数のパラメータに、正確なバージョンとダウンロードするURLを指定できます。詳細は、この関数のdocstringを参照して下さい)。あなたのユーザがインターネットに接続できて、site-packagesにインストールしている限りは。ユーザの中には、これらの条件が適用できない人もいて、setuptoolsを使っているプロジェクトに最初に遭遇したとき、彼らはいらいらします。彼らをいい気分にさせておくために、彼らがあなたのプロジェクトに関連していて、あなたが対象とするユーザがsetuptoolsとeasy_installにまだ詳しくなかったら、あなたのプロジェクトのインストール方法について、以下の点を検討する必要があります。instructionsが使うsetuptoolsの正しいバージョンがすでにインストールされている必要があることを、あなたはユーザに教える必要があります。これらの指示には、どうやって手動でsetuptoolsをダウンロードしてインストールするかの他に、ファイアウォールをどうするかという指示もついています。Locationで指示されている方法で、setuptoolsを最初にインストールしなければならないことを、ユーザに教える必要があります。あなたのプロジェクトが依存しているものあなたのプロジェクトがPyPIか他の場所からダウンロードされる必要がある他のプロジェクトに依存していたら、あなたはインストールの方法にそれらの一覧を記述するか、依存しているものを探し出す方法をユーザに教えなければいけません。ほとんどのユーザはこの情報を必要としていませんが、無制限のインターネット接続を持っていないすべてのユーザは他のプロジェクトを手動で探し、ダウンロードし、インストールしなければなりません(次の点にも注意してください。彼らはいまだにeasy_installを使ってそれらのプロジェクトをインストールする必要があり、そうしなければあなたのプロジェクトはそれらがインストールされていないことを知ることができず、あなたのセットアップスクリプトはそれらを再びダウンロードしようと試みることでしょう)。ネットワーク接続に制限があるユーザに特に友好的であろうとしたら、あなたのプロジェクトと依存しているもののeggをビルドして、あなたのサイトからそれらすべてがダウンロードできるようにし、あるいは少なくとも必要なすべてのeggへのリンクがあるページを作ろうと願うかもしれません。この方法だと、ネットワーク接続に制限があるユーザは、ひとつのディレクトリにすべてのeggを手動でダウンロードし、eggを探すディレクトリを指定するためにeasy_installの-fオプションを使えます。完全にネットワークに接続できるユーザは、あなたのダウンロードページのURLを指定するために-fオプションを使うだけでよく、そうすればeasy_installはあなたのリンクから直接必要なeggをすべて探します。これは、あなたのユーザがパッケージをコンパイルできない(例えば、ほとんどのWindowsユーザたち)うえ、あなたのパッケージが依存しているもののいくつかがC言語のコードを含んでいるときにも有効です。他のバージョン管理システムを使っている開発中のコードを追いかけているユーザと共同開発者は、おそらくこのマニュアルのこのような開発に関連している節を読む必要があります。あなたは、特定の状況に適用するこのマニュアルからの情報が書かれているクイックリファレンスガイドを作ろうと思うかもしれません。developを実行する必要があることをユーザに教えなければなりません。ユーザに推測させたままにしておくのではなく、あなたのプロジェクトの最良のプラクティスを記して、ユーザに親切にしましょう)。bdist_dump形式に対応しています。ユーザが、distutilsのinstallコマンドを内部で使っている、"bdist"パッケージツールをローカルにインストールしていたら、これはsetuptoolsとともに動作すべきです。setuptoolsと一緒に動作する"bdist"形式の例は、Windows用のbdist_nsi形式とbdist_msi形式を含みます。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パッケージを除外し、配布物に含まれないようにする必要があります。find_packages(exclude=['ez_setup']),)もちろん、ez_setupパッケージはまだあなたのパッケージのソースの配布物に含まれており、これは必要です。以下のexternalsの定義を使用すると、便利です。.それから、上の行を編集するファイルに追加します。zip_safeフラグを設定する性能を最大化するため、Pythonパッケージはzipファイルとしてインストールされるのがもっともよいです。すべてのパッケージが圧縮された形式で実行できるわけではありません。それらは通常のOSのファイルとしてソースコードやデータファイルにアクセスできることを期待するからです。このため、setuptoolsはプロジェクトをzipファイルとしても、ディレクトリとしてもインストールでき、デフォルトはプロジェクトのzip_safeフラグによって決定されます。setup()関数のzip_safe引数にTrueかFalseを渡すか、省略できます。省略した場合、bdist_eggコマンドはプロジェクトを解析して、zipファイルとして動作するのに妨げとなる条件が検出されるかどうか、調査します。bdist_eggコマンドは、そのように見つけた条件について、コンソールに注意を出力します。bdist_eggコマンドは、プロジェクトがC言語の拡張かデータファイルなどを含んでいたら、そのプロジェクトは安全ではないと判断します。これは単に、プロジェクトが動作することを断言するのに、bdist_eggの作者が気楽ではないことを意味します。プロジェクトがC言語もデータファイルも含んでおらず、__file__や__path__といったイントロスペクションやソースコードの操作をしないなら、zipファイルとしてインストールされたときにプロジェクトが動作するとても手堅い機会です(そしてプロジェクトがすべてのデータファイルのアクセスにpkg_resourcesを使っていたら、C言語の拡張と他のデータファイルはまったく問題になりません。詳しいことは、上の「実行時にデータファイルにアクセスする」の節を読んでください)。bdist_eggはあなたのパッケージが動作するか保証できないときは、それが出したすべての警告を調べて、それが動作することに満足し(あるいは自分でそれを試したい場合)、setup()を呼び出すときにzip_safeをTrueに設定できます。動作しないことが判明したら、あなたはいつもそれをFalseに変更できます。これにより、setuptoolsはプロジェクトをzipファイルではなくディレクトリとしてインストールします。エンドユーザがパッケージをインストールするのにEasyInstallを使っていたら、エンドユーザはまだこの決定を上書きできます。.をプロジェクトのディレクトリで実行すればよいです。これにより、パッケージはそれぞれ、zipファイルとして、あるいはディレクトリとしてインストールされます。将来は、私たちが別のパッケージでもっと経験を積んだら、pkg_resourcesの実行の信頼性に満足でき、「zipとしても安全か」の解析はより正確になるでしょう。我々は、あなたが自分自身で、プロジェクトがzipファイルとしてインストールされたときに正常に機能するかどうか決め、できれば問題を集め、zip_safeフラグにTrueかFalseか明示的に与えることを強く推奨します。これにより、bdist_eggやEasyInstallがzipファイルとして動作するか推測するように試みる必要はなくなります。名前空間パッケージときとして、巨大なパッケージはより小さいeggの集まりとして配布したらより使い易いことがあります。Pythonは通常、ひとつのパッケージの内容を、ふたつ以上の場所から集めることはできません。「名前空間パッケージ」は、この問題に対する解決策です。あなたがあるパッケージを名前空間パッケージとして宣言したとき、そのパッケージは__init__.pyに意味のある内容を持たず、単にモジュールやサブパッケージのコンテナになります。pkg_resourcesのランタイムは、それから自動的に、複数のeggやディレクトリに分かれている名前空間パッケージの内容を、単一の「仮想」パッケージにまとめます。setup()のnamespace_packages引数により、プロジェクトが名前空間パッケージであることを宣言でき、これによりそれらのパッケージはプロジェクトのメタデータを含むようになります。この引数は、eggに加わるする名前空間パッケージの一覧です。['zope'])なぜならば、これはzope名前空間パッケージの下にあるzope.interfaceパッケージを持つからです。同じように、標準のzope.publisherもまた、zope名前空間パッケージを宣言します。これらのプロジェクトがインストールされて使用されるとき、Pythonはこれらを両方共「仮想的な」zopeパッケージの一部であるとみなします。これらが別々の場所にインストールされたとしても。名前空間パッケージは、トップレベルパッケージである必要はありません。3のzope.appパッケージは名前空間パッケージであり、将来のPEAKのpeak.utilパッケージも同様です。ところで、次の点に注意してください。プロジェクトのソースツリーは、Pythonのパッケージレイアウトに沿って、名前空間パッケージの__init__.pyファイル(とすべての親パッケージの__init__.py)を含んでいなければなりません。これらの__init__.pyファイルは、次の行を含んでいなければなりません:__import__('pkg_resources').declare_namespace(__name__)このコードにより、名前空間パッケージの機構が動作し、現在のパッケージが名前空間パッケージに登録されることが保証されます。あなたは、名前空間パッケージの__init__.pyに、他のコードやデータをふくめてはいけません。そのような場合、__init__.pyファイルをインストールせず、単独で実行させます。問題となっている名前空間パッケージの内容物を持つすべてのプロジェクトの__init__.pyに、declare_namespace()の行を含めなければなりません。これにより、どのプロジェクトの__init__.pyのコピーが最初に読み込まれても、名前空間が宣言されることが保証されます。0.6aは実行時に自動的にdeclare_namespace()を呼び出しますが、0.7aは呼び出しません。自動的な宣言の機能にはいくつか問題があるからです。pkg_resourcesの実行時の初期化中に、すべての名前空間パッケージをインポートする必要があり、またいずれかの名前空間パッケージが動作する前にpkg_resourcesを正確にインポートする必要もあるからです。0.7aのリリースから、あなたは自分自身の宣言行を含める責任があり、自動的な宣言の機能は問題を除去するために削除されます。0.6の残りの開発サイクルの間は、それゆえ、setuptoolsは__init__.pyファイルにdeclare_namespace()の呼び出しがないことを警告します。0.7a1がリリースされる前に、できるだけ早くこれを修正しなければなりません。0.7a1に更新したら動作しなくなり、そのため、現場であなたのコードが壊れるのを回避するために、いまこの変更をすることが重要です。我々は不便をかけたことを謝罪し、あなたの辛抱強さに感謝します。タグ付けと「デイリービルド」、「スナップショット」リリース関連するプロジェクトが開発中であるとき、例えば「安定」リリースを普通に使うより、細かくバージョンの増加を追いかけることが重要になるかもしれません。安定リリースは、ドットで区切られた番号とアルファやベータなどと一緒に番号づけられますが、プロジェクトの開発バージョンはしばしば、リビジョンかビルド番号かビルドした日付でさえ使って追いかけられます。-d)あなたはこれらのタグをegg_infoに追加し、デイリービルドかスナップショットを生成したいsdistかbdistコマンドの前のコマンドラインに、希望するオプションを追加することができます。詳しい情報は、下の「egg_info」コマンドの節を参照してください(また、プロジェクトをリリースする前に、上の「プロジェクトのバージョンを指定する」の節で、setuptoolsとEasyInstallがバージョン番号を解析するのに、どのようにプレリリースタグとポストリリースタグが影響するか、確かめてください。依存関係を処理するツールが、プロジェクトのどのバージョンが他のバージョンよりも新しいか知るのかについて確かめておくため、これは重要です)。最後に、頻繁にビルドしている場合で、かつ、ダウンロード可能な場所でビルドしているか、配布サーバにコピーしているなら、あなたはおそらくrotateコマンドを調べる必要があります。このコマンドにより、ファイル名のパターンにマッチするもっとも最近変更されたN個の配布物を除いて、すべてのものを自動的に削除できます。-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ファイルの形式のより詳細な情報については、distutilsのドキュメントを参照してください。setuptoolsはそれらの結果からあなたを守り、あらゆる場合で同様に動作しません。distutilsとは違い、setuptoolsはソースの配布物のマニフェストファイルを、ソースの配布物をビルドしたときに毎回再生成し、メインのプロジェクトのディレクトリから外れて、プロジェクトの.egg-infoディレクトリにビルドします。そのため、あなたはこのファイルが最新であるかどうか、心配する必要はありません。実際、setuptoolsがソースの配布物の内容を決める方法は非常に簡単であるため、sdistコマンドは、distutilsのより複雑なsdistプロセスが必要とするオプションのほとんどすべてを削除します。すべての実際の目的のために、もしどれかのオプションを使うのであれば、あなたはおそらく--formatsオプションだけを使うでしょう(ところで、もし他のバージョン管理システムを使っていたら、setuptools.command.sdistモジュールへのパッチを提出することを考えてもよいです。すれば、我々はあなたのシステムへの対応を含めることができます)。commandを参照してください)。uploadコマンドを使ってパッケージの実際の配布物をアップロードしていたら、それは同じようによいです。EasyInstallはあなたのプロジェクトのPyPIのページからそれらを探して直接ダウンロードできるからです。PyPIに配布物をアップロードしたくない理由があるかもしれませんし、代わりに既に存在している配布物だけ(かSubversionのチェックアウト)を欲しいかもしれません。このため、registerコマンドを実行する前に必要なことを以下に記します。EasyInstallに影響を与えるsetup()の引数が3つあります:urlとdownload_urlこれらは、プロジェクトのPyPIページへのリンクです。EasyInstallは、これらがパッケージにリンクしているか調べるため(「プライマリリンク」)、あるいはこれらがHTMLページであるか調べるため、これらにアクセスします。HTMLページであったら、EasyInstallはページ中のすべてのHREFを走査し、プライマリリンクを探します。long_descriptionEasyInstallは、この引数に含まれるURLをすべて調査して、これらがプライマリリンクではないかどうか調べます。.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のチェックアウトをダウンロードに選択しません。projectname==devこれにより、projectnameの開発バージョンをチェックアウトできます。Subversionを使って「継続リリース」を管理するSubversionを使って、ユーザが開発中のバージョンを追いかけることを期待するのであれば、少しのことを行うことで、EasyInstallを使って物事がスムーズに進むことを保証できます。1これにより、setuptoolsは1.0a1.dev-r1263のようなパッケージのバージョン番号を生成し、これは1.0a1より古いリリースだとみなされます。setup.pyで指定したバージョン番号は常に、ソフトウェアの次のバージョンであり、最後にリリースされたバージョンではありません。代わりに、tag_build=.devを除外して、バージョン番号として常に最後のリリースを使うことができ、これによって1.0のあとのビルドは1.0-r1263とラベルづけされます。これは1.0のあとのパッチレベルを示します。ほとんどのプロジェクトではここまでは、開発中の間は将来のバージョンとして考え、パッチを当てられたポストバージョンとは考えない方が好ましいと思われます。単一のプロジェクトにおいては、両方の状況もあり得、リリースブランチにポストリリース番号をつけ、trunkにプレリリース番号をつけます。したいと思わない限り、物事を複雑にすべきではありません)。共通のこととして、Subversionからコードをリリースするプロジェクトは、#egg=projectname-dev接尾語を使って、チェックアウトURLへのPyPIのリンクを含みます(前の節で述べた通り)。これにより、ユーザは、EasyInstallでprojectname==devをダウンロードすることができ、最新の開発コードを得ることができます。["OtherProject>=0.2a1.dev-r143,==dev"]上の例は、「私は少なくともこの特定の開発リビジョン番号を求めているのであるが、もし#egg=OtherProject-devを見つけたら、そのリンクを使うのにはやぶさかではない」ことを意味します。これにより、利用可能な開発中のコードのスナップショットの、実際のソースかバイナリの配布物が必要になることを回避できます。プロジェクトが提供している最新でもっとも偉大なものに依存できるようになります。developを実行するのはいい考えです。プロジェクトのバージョン番号が変わり、それに応じてスクリプトのラッパーを更新する必要があるからです。プロジェクトが要求しているものが変わったら、変更された拡張子をビルドするなどして、developコマンドは更新された依存関係に気をつけます。developを実行する必要があることを、思い出させるようにしてください。「公式」(非スナップショット)リリースを作成するソースかバイナリの配布物を作成し、公式リリースを行ったら、setup.cfgのタグの設定を上書きし、foobar-0.7a1.dev-r34832のようなバージョンを登録して終わらないようにします。リリースをブランチするかタグづけしたあとにsetup.cfgを変更するだけで、trunkは依然開発のスナップショットを作成します。ソースとバイナリのeggを作成する前に、設定されているタグ情報を上書きし、PyPIにプロジェクトを登録し、ファイルをアップロードします。したがって、このコマンドはsetup.pyからの何も付加されていないバージョンを使用し、Subversionのリビジョン番号やビルドの設計文字列をつけたりしません。これをたくさん行うのであれば、この操作に対して個人的なエイリアスを作ろうと思うでしょう。uploadあるいはもちろん、上のすべてを実行するもっと入念ななエイリアスを作成することもできます。使うコマンドをショートカットに定義する」の節を参照してください。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があってもなくても、ソースのリリースは同じように使えるようになります。使うコマンドをショートカットに定義するときには、いつも同じコマンドを使う必要があり、しかしそれをデフォルトに設定する必要がない場合があります。あるプロジェクトの開発のスナップショットリリースと「安定」リリースを両方とも作成し、それらの配布物を異なる場所に置くか、あるいは異なるegg_infoタグづけオプションを使う、などといった場合です。これらの場合、distutilsの設定ファイルにそのオプションを設定するのには意味があります。それらのオプションの値はあなたが何をしようとしているかによって変わるからです。expansionを使います。ここで、aliasnameは新しいエイリアスの名前で、コマンドの残りは展開部分です。--tag-build=developmentいったんエイリアスが定義されたら、他のセットアップコマンドと一緒に使用できます。--tag-build=developmentと置換されたように解釈されます。setuptoolsは、与えられたコマンドラインで、各エイリアスを多くても一回展開することに注意して下さい。これにはふたつの目的があります。あなたは不明なコマンドに関するエラーメッセージを代わりに受け取ることでしょう。ふたつ目に、コマンドに対するエイリアスを定義できるようになり、そのエイリアスではそのコマンドを使用します。-m.eggこれは、bdist_eggコマンドを再定義し、最新のeggファイルを除くすべてのファイルを削除するrotateコマンドを毎回あとで実行するようにします。bdist_eggにおいて無限にループしません。このエイリアスは使用されたとき、たった一回だけ展開されるからです。remove(か-r)オプションで、定義されたエイリアスを削除できます。dailyこれは、上で定義した"daily"エイリアスを削除します。エイリアスは、プロジェクトごとか、ユーザごとか、サイト全体について定義できます。デフォルトはプロジェクトごとのエイリアスを定義したり削除したりしますが、設定ファイルのオプション(下の"saveopts"コマンドの下に一覧があります)を使用して、どのdistutilsの設定ファイルにエイリアスを追加するか(あるいは削除するか)決定できます。aliasコマンドの「展開部分」の引数を省略したら、エイリアスの現在の定義(と、どの設定ファイルで定義されているか)が表示されます。エイリアス名も省略したら、現在のすべてのエイリアスが、設定されているファイルとともに表示されます。Egg(.eggファイル)を生成します。EggはEasyInstallのためのバイナリの好ましい配布形式です。Eggは(「ピュアな」パッケージについては)クロスプラットフォームで、直接インポート可能で、スクリプトとプロジェクトの依存関係に関する情報を含むプロジェクトのメタデータを持っています。Eggは単純にダウンロードでき、sys.pathに直接追加でき、あるいはsys.pathにあるディレクトリに置いて、eggの実行時のシステムが自動的に発見できるようにできます。追加のメタデータファイルを.egg-infoディレクトリに追加したら、それらのファイルは新しいeggファイルのメタデータディレクトリに含まれるようになり、eggの実行時のシステムかそのメタデータを使うなんらかのアプリケーションかフレームワークが使用します。bdist_eggを使えば、完了です。DIR.eggファイルが置かれるディレクトリを設定します。これを省略したら、bdistコマンドの--dist-dirの設定が使用され、これは普通、プロジェクトディレクトリのdistという名前のディレクトリです。PLATFORMeggのファイル名に組み込まれるプラットフォームの名前の文字列を設定します(eggがC言語の拡張を持っていると仮定して)。これにより、distutilsのデフォルトのプラットフォーム名を、より意味のあるものに上書きすることができます。eggの実行時のシステムは、distutilsのプラットフォーム名とともにeggを見ることを期待していて、そのため非標準のプラットフォーム名を持つeggを無視するか拒否することを、覚えておいて下さい。同じように、EasyInstallプログラムは、ウェブページからダウンロードのリンクを探すときに、これらを無視します。クロスコンパイルした場合や、それ以外の普通ではないことをした場合は、このオプションの使い道に気づくでしょう。--exclude-source-fileseggにモジュールの.pyファイルを含めず、コンパイルされたPythonと、C言語、データファイルだけを含めるようにします(これはEGG-INFOディレクトリとそのサブディレクトリにある.pyファイルには影響を与えません。そのため例えば、いまだに保持されなければならない.py拡張子のスクリプトを含めることができます)。プロプライエタリなエンドユーザが使用するアプリケーションにバンドルされるパッケージか、容量が絶対的に貴重な「組み込み」のシナリオ以外で、このオプションを使用するのは推奨しません。パッケージが圧縮された形式でインストールされて使用されるなら、ソースを削除しても構いません。Pythonのtracebackモジュールは現在のところ、zipで圧縮されたソースコードをどのように表示するのか、あるいはコードがコンパイルされたのと違うところにあるファイルをどのように扱うのか、理解していないからです。必要にならないであろうオプションもあります。これを作成するための例として使用した、似ているbdistコマンドからコピーしたため、それらは存在します。-k.eggファイルを作成したあと、--bdist-dirツリーの内容を保存しつづけます。DIR配布物を作成するための一時ディレクトリを設定します。パッケージのモジュールやデータ、拡張をコピーするための様々なインストールコマンドが実行された後、このディレクトリの内容物すべてが、.eggファイルをつくるためにzipで圧縮されます。インストールと圧縮フェーズをただちに実行します。areas"にある、プロジェクトのソースをデプロイできます。このデプロイは、プロジェクトのソースを変更するごとにビルドやインストールを実行する必要なしに、プロジェクトのソースへの変更をただちに利用できる方法で行われます。areaで.egg-linkファイル(プロジェクトのために名前がつけられています)を作成することで動作します。areaがPythonのsite-packagesディレクトリなら、developコマンドはeasy-install.pthファイルも更新し、そのためプロジェクトは、そのインストールされているPythonを使うすべてのプログラムで、最初からsys.path上に存在します。area(か、指定されていたら別のディレクトリ)にラッパースクリプトをインストールし、そのスクリプトは、プロジェクトのソースのスクリプトを実行する前に、プロジェクトが依存しているものがsys.path上に存在することを保証します。sraeでプロジェクトが依存しているものが見つからなかったら、必要であればそれらをダウンロードしてインストールし、使えるように保証します。-iコマンドを実行して、プロジェクト内のすべてのC言語の拡張がビルドされ、最新であることを保証し、egg_infoコマンドを実行し、プロジェクトのメタデータが更新されることを保証します(そのためランタイムとラッパーは、プロジェクトが依存しているものがなにか知っています)。areaに対して再実行し、プロジェクトのスクリプトとメタデータ、拡張が最新であるようにしなければなりません。プロジェクトに加えるそれ以外のほとんどの変更は、ビルド作業やdevelopコマンドの実行を要求しませんが、セットアップスクリプトを少しでも変更したら(例えばエントリポイントの定義を変更する)、developコマンドかtestコマンドを再実行し、配布物が最新であるようにしなければならないことを覚えておいてください。developコマンドには、いくつかのオプションがあります。このため、もし依存しているものについてインストールのオプションをより詳細に制御する必要があったら、developコマンドを実行する前に、プロジェクトが依存しているものをインストールするためにEasyInstallを使用したいと思うでしょう。-u現在のプロジェクトをアンインストールします。areaを明示できます。.egg-linkファイルが作成され、プロジェクトのディレクトリをまだ指していたら、これは削除されます。areaがPythonのsite-packagesディレクトリだったら、プロジェクトのディレクトリはeasy-install.pthから削除されます。あなたは自分でそれらをアンインストールし、あるいはEasyInstallを使ってそれらを上書きし、パッケージの違うバージョンが使えるようにしなければなりません。-x)を使っていたら、最初の場所にスクリプトのラッパーをインストールするのを回避することもできます。-m「マルチバージョン」モードです。このオプションを指定すると、developコマンドはデプロイされるプロジェクトをeasy-install.pthのエントリに加えなくなり、もしプロジェクトのなんらかのバージョンのエントリがすでに存在していたら、そのエントリはデプロイが成功したら削除されます。マルチバージョンモードでは、pkg_resources.require()を使ってプロジェクトをsys.pathに置いていない限り、あるいはsetuptoolsかEasyInstallによって生成されたラッパースクリプトを実行している(この場合、ラッパースクリプトはrequire()を呼び出します)のではない限り、パッケージの特定のバージョンをインポートできません。site-packages以外のディレクトリにインストールするのであれば、このオプションは自動的に効果を持ちます。2.3と2.4では)。そのため、--install-dirか-dオプションを使ったら(あるいは設定ファイルを通して設定されていたら)、プロジェクトとプロジェクトが依存しているものはマルチバージョンモードでデプロイされます。このオプションがコマンドラインかdistutilsの設定ファイルでで直接指定されていなければ、distutilsのデフォルトのインストール場所が使用されます。areaを決定するのにそれらの設定が関ってきます。DIRスクリプトをインストールするディレクトリを設定します。このオプションを指定せず(コマンドラインか設定ファイルで)、しかし--install-dirを与えていたら、(コマンドラインか設定ファイルで)、このオプションのデフォルト値は同じディレクトリになり、そのためスクリプトは関連しているパッケージのインストールが探すことができます。この設定のデフォルト値はdistutilsが通常スクリプトをインストールする場所になり、distutilsのあらゆる設定ファイルの設定が関ってきます。-xスクリプトのラッパーをデプロイしません。areaにある既存のバージョンのスクリプトにわずらわされたくない場合、これは有用です。areaに必要な全てのスクリプトをコピーします。areaにはコピーされません。上のオプションに加えて、developコマンドはeasy_installが受け付けるのと同じオプションをすべて受け付けます。setup.cfg(か他のdistutilsの設定ファイル)でeasy_installのなんらかの設定を行っていた場合、[develop]セクションで上書きするか、コマンドラインで上書きしない場合、developコマンドはそれらをデフォルトとして使用します。toolを実行します。これはeasy_installコマンドを実行するのとまったく同じです。このコマンドに続くすべてのコマンドライン引数は消滅させられ、distutilsによってそれ以上処理されず、したがってこのコマンドは、コマンドラインに並べる中で、最後のコマンドである必要があります。オプションのリファレンスと使い方の例については、EasyInstallのドキュメントを参照してください。通常、このコマンドをコマンドラインから使う理由はありません。easy_installを直接使用すればよいのです。このコマンドはここに並べられているだけで、これはこのコマンドがdistutilsコマンドであり、コマンドのエイリアスを作成でき、このコマンドをサブコマンドとして起動するdistutilsの拡張を作成でき、setup.cfgや他のdistutilsの設定ファイルでオプションを設定できることを意味します。testコマンドに使用されます)を更新し、プロジェクトのバージョン文字列を一時的に変更し、「デイリービルド」や「スナップショット」リリースができるようにします。testコマンドによって自動的に実行され、プロジェクトのメタデータを更新します。メタデータを明示的に指定することも可能で、他のコマンドが実行している間、プロジェクトのバージョン文字列を一時的に変更できるようになります(このコマンドは``.egg-info/SOURCES.txt``マニフェストファイルも生成します。このファイルは、ソース配布物を生成するときに使用されます)。setuptoolsによって定義され、pkg_resourcesによって必要とされている核となるeggのメタデータを書き込むのに加え、egg_info.writersグループ中にエントリポイントを定義することで、このコマンドは他のメタデータファイルを書くように拡張できます。詳細は、下の「新しいEGG-INFOファイルを追加する」を参照してください。追加したメタデータを書き込む拡張を使うときは、setup()にsetup_requires引数を与える必要があり、これにより希望する拡張がsys.path上にあることが保証されます。リリースに使用するタグ付けのオプションセットアップのコマンドラインの残りのすべてのコマンドに対し、プロジェクトのバージョン文字列を変更するために、以下のコマンドが使用できます。NAMEプロジェクトのバージョン文字列にNAMEを追加します。"candidate")をsetuptoolsが処理する方法により、プロジェクトのデフォルトのバージョンよりバージョン番号が低くみなされるようにするため、あなたは普通".build"や".dev"といったタグを使用したいと思うでしょう(もしバージョン番号をデフォルトのバージョンよりも高くしたかったら、常に--tag-buildを使用せず、以下のオプションを使用します)。""か--tag-build=""をegg_infoコマンドの引数に使って、それを抑止することができます。-rもしカレントディレクトリがSubversionのチェックアウトであったら(つまり、.svnサブディレクトリを持っていたら)、このオプションは"-rNNNN"の形式で文字列をプロジェクトのバージョン文字列に追加します。infoコマンドで得られます。カレントディレクトリがSubversionチェックアウトでなければ、このコマンドは代わりにPKG-INFOファイルを探し、そこからリビジョン番号を探そうとします。これは、バージョン番号の終わりから"-rNNNN"という文字列を探すことで、行われます(これにより、Subversionのスナップショットのソース配布物からビルドされたパッケージは、正しいバージョン番号を持つバイナリを作成します)。PKG-INFOファイルがないか、その中のバージョン番号が-rと番号で終わらなければ、-r0が使用されます。-Rバージョン番号に、Subversionのリビジョンを含みません。このオプションは、setup.cfgに含まれるデフォルトの設定を上書きできるようにするため、存在します。-d"-YYYYMMDD"(例えば"-20050228")の形式で、日付をプロジェクトのバージョン番号に追加します。-Dバージョン番号に、日付を含みません。このオプションは、setup.cfgに含まれるデフォルトの設定を上書きできるようにするため、存在します。これらのオプションはプロジェクトのソースの配布物とバイナリの配布物に使用されるバージョン番号を変更するため、あなたはまず、結果として得られたバージョン番号がEasyInstallのような自動ツールにどのように解釈されるのか、知っているか確認しなければなりません。上の「プロジェクトのバージョンを指定する」で、プロジェクトのバージョンスキーマを選択し、変更する方法だけでなく、プレリリースタグやポストリリースタグの説明を読んでください)。高度な使い方として、設定可能なもうひとつのオプションがあり、プロジェクトの.egg-infoディレクトリの場所を変更できます。SOURCEDIR.egg-infoディレクトリがあるディレクトリを指定します。複数のプロジェクトが、ソースのルートとしてひとつのsrcやlibサブディレクトリを使用します)。通常、このディレクトリを指定する必要はありません。あれば、setup()関数のpackage_dir引数から普通は決定できるからです。package_dirが設定されていない場合は、このオプションの初期値はカレントディレクトリになります。easy_installか、古いスタイルのインストールを実行するsetuptoolsのinstallコマンドは基本的に、現在のプロジェクトのeasy_installコマンドを実行するショートカットです。setuptoolsに基づいたプロジェクトの「システムパッケージ」を作成するときに便利なように、以下のオプションを使うこともできます:--single-version-externally-managedこの真偽値のオプションにより、installコマンドは「古いスタイル」のインストールを実行して、.egg-infoディレクトリを追加するようになり、そのためインストールされたプロジェクトはいまだにメタデータを使うことができ、普通に動作します。このオプションを使用したら、--rootか--recordオプション(かその両方)も指定しなければなりません。一方で、インストールされたファイルを識別し、削除する方法がないからです。このオプションは、他のdistutilsコマンドによってinstallコマンドが起動されたとき、自動的に効果を持つようになります。それにより、bdist_wininstやbdist_rpmといったコマンドはeggのシステムパッケージを作成します。--rootオプションを指定したときも、同じように自動的に有効になります。site-packagesに.egg-infoディレクトリをインストールするsetuptoolsはこのコマンドを、--single-version-externally-managedオプションを使ったinstallの動作の一部として実行します。このコマンドは、ドキュメントを完全なものにするためにここに書かれているのであり、これにより、システムパッケージビルダーのようなdistutilsの拡張がこれを使うことができます。DIR.egg-infoディレクトリが置かれる親ディレクトリを指定します。デフォルトはinstall_libコマンドに与えられた--install-dirオプションと同じで、これは普通システムのsite-packagesディレクトリです。このコマンドは、egg_infoコマンドはコマンドラインかsetup.cfgから適切なオプションを与えられていると仮定し、それによりこのコマンドはegg_infoコマンドを起動し、プロジェクトのソースの.egg-infoディレクトリを配置するためにegg_infoコマンドのオプションを使用します。古いソースやバイナリの配布物のファイルで次第にいっぱいになるでしょう。rotateコマンドを使えば、これらを自動的に削除でき、指定されたパターンにマッチする、もっとも最近変更されたN個のファイルだけを持つことができます。PATTERNLISTファイル名にマッチするためのパターンの、コンマで区切られたリストです。このオプションは必須です。プロジェクト名と-*は与えられたパターンにprependedで、これにより現在のプロジェクトに属する配布物のみをマッチできます(複数プロジェクトで配布物のディレクトリを共有していることを想定しています)。典型的には、.zipや.eggといったパターンを使用し、指定されたタイプのファイルにマッチするようにします。それぞれの与えられたパターンは、削除するファイルを選択するために、個別のグループとして扱われることに注意してください。COUNT保持する、マッチする配布物の数です。--matchオプションで指定されたパターンで識別されるファイルの各グループについて、そのグループ内でCOUNT個のもっとも最近変更されたファイルを除いて、すべてのファイルを削除します。このオプションは必須です。DIR配布物があるディレクトリです。デフォルト値はbdistコマンドの--dist-dirオプションの値で、これは普通プロジェクトのdistサブディレクトリです。設定ファイルに使用したオプションを保存するdistutilsの設定ファイルを探して編集するのは苦痛です。設定のオプションをコマンドラインの形式から適切な設定ファイルの形式にも翻訳しなければならないからです。saveoptsコマンドを使えば、このような混乱を回避することができます。このオプションをコマンドラインに追加するだけで、使っているオプションを保存できます。saveoptssaveoptsコマンドは、プロジェクトのローカルのsetup.cfgファイルに、コマンドライン上で指定されたすべてのコマンドについてすべてのオプションを保存します。オプションが保存されている設定ファイルのオプションのひとつを、変更するために使用し他場合は、この限りではありません。このコマンドはすべてのコマンドについて、指定されたオプションをすべて保存します。--compiler=mingw32しかし、saveoptsがコマンドラインのどこに置かれようが、指定されたコマンドのすべてが常に実行されることに注意してください。設定ファイルのオプション通常、オプションやエイリアスといった設定は、プロジェクトのローカルのsetup.cfgファイルに保存されます。これを上書きし、グローバルかユーザごとの設定ファイルか、手動で指定されたファイルに保存することができます。-g設定を、distutilsパッケージディレクトリの中にあるグローバルのdistutils.cfgファイルに保存します。このオプションを使うにあたり、あなたはそのディレクトリに書き込む権限を持っていなければなりません。このオプションを、-uや-fと組み合わせて使うことはできません。ファイルに保存します。このオプションを-gや-fと組み合わせて使うことはできません。FILENAME設定を、指定された設定ファイルに保存します。このオプションを-gや-uと組み合わせて使うことはできません。非標準のファイル名を指定したら、distutilsとsetuptoolsはそのファイルの内容を使用しないでしょう。このオプションは主に、テストで使用するために含まれています。これらのオプションは、設定ファイルを書き換える、aliasやsetoptといったコマンドが使います。distutilsかsetuptoolsのオプションを設定ファイルに設定するこのコマンドは主にスクリプトが使いますが、どのファイルにオプションが設定されていたか思い出してエディタを開くことなく、distutilsの設定のオプションを変更する、素早くダーティな方法としても使われます。COMMANDオプションを設定するコマンドです。このオプションは必須です。OPTION設定するオプションの名前です。このオプションは必須です。VALUEオプションに設定する値です。-rか--removeが設定されていたら、必要ありません。-r設定する代わりに、オプションを削除します。上のオプションに加えて、任意の設定ファイルのオプション(上のsaveoptsコマンドで記述されています)を使用することができ、オプションが追加される(あるいは削除される)distutilsの設定ファイルを指定できます。パッケージをビルドしてユニットテストスイートを実行するテスト駆動開発をしているとき、あるいは、ダウンロードするか使うためにデプロイされる前にテストすることが必要な自動化されたビルドを実行するとき、developコマンドを使っていたとしても、実際にプロジェクトをどこかにデプロイすることなしに、プロジェクトのユニットテストを実行できるというのは、便利なことです。testコマンドはプロジェクトのユニットテストを、実際にデプロイすることなしに実行します。-iとegg_infoを実行し、すべてのC言語の拡張とプロジェクトのメタデータが最新であることを保証したのち、一時的にsys.path上にプロジェクトのソースを置いて行われます。このコマンドを使うにあたり、プロジェクトのテストは、関数かTestCaseクラスかメソッドか、TestCaseクラスを持つモジュールかパッケージによって、unittestテストスイートの中にラップされていなければなりません。指定されたスイートがモジュールであり、そのモジュールがadditional_tests()関数を持っていたら、この関数は呼び出され、その戻り値(これはunittest.TestSuiteでなければなりません)は、実行されるテストに追加されます。詳細は、test_loaderのドキュメントを参照してください)。doctestを含む多くのテストシステムが、TestSuiteオブジェクトが持つユニットテストではないテストをラップすることに対応しています。このため、もしこれに対応していないテストパッケージを使用していたら、それの開発者たちにテストスイートに対応するよう催促することを提案します。これが共通のテストハーネスの下で実行されるテストの集合に集約する便利で標準的な方法だからです。-q)、-qオプションか--quietオプションを指定すれば、「静かな」モード(ドットだけ)で実行できます。NAME実行されるテストスイート(またはモジュールかクラス、メソッド)を指定します(すなわち、some_module.test_suite)。)もしsetup()の呼び出しでtest_suiteを設定しておらず、--test-suiteオプションを与えていなかったら、エラーが発生します。プロジェクトのホームページにダウンロードのリンクがなくても、EasyInstallによってアップロードされたファイルは簡単に見つけられます。2.5ではPyPIにすべての種類の配布物をアップロードすることができますが、setuptoolsはソースの配布物とeggのみに対応しています(これが、他の様々な種類に対する、PyPIのアップロードへの対応が、現在は壊れていることの理由です)。ファイルをアップロードするためには、セットアップのコマンドラインでsdistかbdist_eggコマンドのあとにuploadコマンドを含めなければなりません。両方ともアップロードするプロジェクトのファイルをアップロードするために、distutilsのregisterコマンドを使って、対応するバージョンがすでにPyPIに登録されている必要があります。コマンドラインの最初にregisterコマンドを含めるというのは通常いい考えで、これによって、配布物をビルドしてアップロードする前に、すべての登録する際の問題が発見され、修正されます。uploadこれはPyPIのリストを、プロジェクトの現在のバージョンで更新します。ところで、setup()の呼び出しでのメタデータは、PyPIでパッケージに表示されるものを決定する点に注意してください。できる限りこれらを記述するようにしてください。することでPyPIに表示される項目を手動で追加し更新するときの多くの問題を解決できるからです。setup.pyにこれらを設定し、registerコマンドを使うだけで、PyPIを最新の状態に保つことができます。システムのPATHでgpgプログラムが実行可能になっていなければなりません。NAME署名する際に使用するGPGの識別子かキー名を指定します。このオプションの値は、gpgプログラムの--local-userオプションに渡されます。これはPyPIの問題をデバッグする際に役に立ちます。URLアップロードするリポジトリのURLです。デフォルトはhttp://www.python.org/pypi(すなわち、PyPIのメインのインストール)です。