SumiTomohikoの日記 このページをアンテナに追加 RSSフィード

2007-06-09

[Python] setuptools

この記事について

この記事は、setuptools - The PEAK Developer's Centerの日本語訳です。まだ途中ですが、先が長いので、ここで一旦公開します。

なお、訳者は翻訳しただけで、記事の内容については確認していません。悪しからずご了承下さい。

setuptoolsを使ったパッケージのビルドと配布

setuptoolsは、Pythonのdistutils(ほとんどのプラットフォームではPython 2.3.5以上に対応します; 64ビットのプラットフォームでは、Python 2.4以上が必要です)を多く拡張します。これにより、Pythonのパッケージをビルドし、配布することが容易になります。他のパッケージに依存しているパッケージでは、とくにそうなります。

setuptoolsを使ってビルドされ、配布されたパッケージは、ユーザにはdistutilsを使った普通のPythonパッケージのように見えます。ユーザがsetuptoolsをインストールするばかりか、setuptoolsについて知っている必要はなく、あなたが配布物にsetuptoolsパッケージ全部を含める必要はありません。たったひとつの起動モジュール(8Kの.pyファイル)を含めれば、ユーザがパッケージをソースからビルドするとき、適切なバージョンのsetuptoolsがインストールされていなければ、あなたのパッケージはsetuptoolsを自動的にダウンロードし、インストールします。

特徴
  • EasyInstallを使ってビルドするとき、自動的に依存しているものを探し、ダウンロードし、インストールし、アップグレードします。EasyInstallは、ダウンロードHTTPFTP, Subversion, SourceForgeを使い、PyPIからリンクされているウェブページを自動的に走査し、ダウンロードするリンクを探します(これは、現在Pythonが使えるものの中で、もっともCPANに近いものです)。
  • Python Eggsの生成 - 単一のファイルでインストール可能な配布形式
  • あなたのパッケージのディレクトリにデータファイルを含めることができ、あなたのコードはそれらを実際に使うことができます(Python 2.4のdistutilsもこの機能に対応していますが、setuptoolsはPython 2.3にもこの機能を追加し、zipで圧縮されたパッケージのデータファイルへのアクセスにも対応します)。
  • あなたのソースツリーにすべてのパッケージを自動的に含めます。setup.pyに個々に記述することなく。
  • あなたのソースの配布物に、すべての関連するファイルを自動的に含めます。MANIFEST.inファイルを作成する必要はなく、ソースツリーを変更したとき、MANIFESTファイルを再生成する必要はありません。
  • あなたのプロジェクトの"main"関数に対して、ラッパースクリプトか、Windows(コンソールとGUI)の.exeファイルを自動的に生成します(注意: これはpy2exeの代わりとなるものではありません; .exeファイルはローカルのPythonに依存します)。
  • 透過的なPyrexへの対応。これにより、あなたのsetup.pyに.pyxファイルを記述することができ、エンドユーザがPyrexをインストールしていなくても、動作させることができます(Pyrexが生成したC言語のファイルを、あなたのソースの配布物に含めるようなものです)。
  • コマンドのエイリアス - よく使用するコマンドとオプションの、プロジェクトごと、ユーザごと、あるいはサイトごとのショートカット
  • PyPIアップロードに対応 - あなたのソースの配布物とeggをPyPIにアップロードします。
  • あなたのプロジェクトを「配置モード」で配置します。これはsys.pathに依存し、しかし、チェックアウトしたソースから直接編集することもできます。
  • distutilsに新しいコマンドやsetup()の引数を簡単に追加し、あなたの拡張を複数のプロジェクトに配布/再利用できます。コードをコピーすることなく。
  • 拡張を自動的に探す拡張可能なアプリケーションフレームワークを作成します。これは、プロジェクトのセットアップスクリプトで宣言された簡単な「エントリポイント」を使用します。

PyPIからのダウンロードに加え、setuptoolsの開発バージョンはPythonSVNサンドボックスから入手できます。また、開発バージョン0.6ブランチが利用可能です。

目次

  • 開発者ガイド
    • setuptoolsをインストールする
    • 基本的な使い方
      • プロジェクトのバージョンを指定する
    • 新しい、あるいは変更されたsetup()のキーワード
      • find_packages()を使う
    • 自動的にスクリプトを生成する
    • 依存関係を宣言する
      • PyPIにない依存物
      • "extras"を宣言する(オプションの機能と依存物)
    • データファイルを含める
      • 実行時にデータファイルにアクセスする
      • パッケージにないデータファイル
      • リソースの自動的な拡張
    • 拡張可能なアプリケーションフレームワーク
      • サービスとプラグインを動的に発見する
      • 追加のメタデータを定義する
      • 「開発モード」
      • setuptoolsに基づいたプロジェクトを配布する
          • setuptoolsを使用する...バンドルせずに!
          • あなたのユーザが知らなければならないこと
          • 複数プロジェクトを管理する
          • zip_safeフラグを設定する
          • 名前空間パッケージ
          • タグ付けと「デイリービルド」、「スナップショット」リリース
          • ソース配布物を生成する
          • パッケージをEasyInstallで利用できるようにする
          • Subversionを使って「継続リリース」を管理する
          • Pyrexを使って拡張を配布する
      • コマンドリファレンス
      • setuptoolsを拡張し、再利用する
          • distutilsの拡張を作成する
            • コマンドを追加する
            • setup()の引数を追加する
            • 新しいEGG-INFOファイルを追加する
            • 他のバージョン管理システムに対応する
            • コマンドを継承する
          • setuptoolsのコードを再利用する
            • ez_setup
            • setuptools.archive_util
            • setuptools.sandbox
            • setuptools.package_index
          • リリースノート/変更履歴

開発者ガイド

setuptoolsをインストールする

EasyInstall Installation Instructionsにしたがって、現在の安定バージョンのsetuptoolsをインストールしてください。とくに、もしあなたがPythonのsite-packagesディレクトリ以外のどこかにインストールしていたら、Custom Installation Locationsを読んでください。

もしsetuptoolsの現在の開発バージョンが欲しかったら、最初に安定バージョンをインストールし、それから次のように実行してください:

ez_setup.py setuptools==dev

これにより最新の開発中の(すなわち不安定な)バージョンのsetuptoolsがPython Subversionサンドボックスからダウンロードされ、インストールされます。

基本的な使い方

setuptoolsの基本的な使い方として、distutilsの代わりにsetuptoolsからものをインポートします。setuptoolsを使った最小のセットアップスクリプトは、以下の通りです:

from setuptools import setup, find_packages
setup(
    name = "HelloWorld",
    version = "0.1",
    packages = find_packages(),
)

見ての通り、プロジェクトでsetuptoolsを使用するのに、それほど多くのものを必要としません。上のようにしたら、このプロジェクトはeggを作成し、PyPIにアップロードし、setup.pyがあるディレクトリにすべてのパッケージを自動的に含めることができます。下のコマンドリファレンスを参照し、このセットアップスクリプトに与えることができるコマンドを確認して下さい。

もちろん、あなたがプロジェクトをPyPIにリリースする前に、セットアップスクリプトにもっと情報を追加して、他の人たちがあなたのプロジェクトを探し、調べられるようにしたいと思うでしょう。そしてもしかしたら、プロジェクトは依存しているものと、おそらくデータファイルとスクリプトを含んで、もっと大きくなるでしょう。

from setuptools import setup, find_packages
setup(
    name = "HelloWorld",
    version = "0.1",
    packages = find_packages(),
    scripts = ['say_hello.py'],

    # Project uses reStructuredText, so ensure that the docutils get
    # installed or upgraded on the target machine
    install_requires = ['docutils>=0.3'],

    package_data = {
        # If any package contains *.txt or *.rst files, include them:
        '': ['*.txt', '*.rst'],
        # And include any *.msg files found in the 'hello' package, too:
        'hello': ['*.msg'],
    },

    # metadata for upload to PyPI
    author = "Me",
    author_email = "me@example.com",
    description = "This is an Example Package",
    license = "PSF",
    keywords = "hello world example examples",
    url = "http://example.com/HelloWorld/",   # project home page, if any

    # could also include long_description, download_url, classifiers, etc.
)

続く節では、setup()の引数のほとんど(メタデータを除く)が何をするかについて、そしてそれらをプロジェクトで使用する様々な方法について説明します。

  • プロジェクトのバージョンを指定する

setuptoolsは、ほとんどのバージョンの形式を扱うことができます; しかし、少し注意しなければならない特殊なことがあります。それは、setuptoolsとEasyInstallが、あなたのパッケージのどのバージョンが、他のバージョンよりも新しいか教えることができるようにするためです。これらを知れば、あなたのプロジェクトが依存している他のプロジェクトのバージョンが何か、正確に指定することができるようになります。

バージョンは、一連のリリース番号と、プレリリースまたはポストリリースタグから構成されます。リリース番号は、ドットで区切られた一連の数字であり、2.4や0.5のようになります。一連の数字は整数のように扱われ、そのため、リリース2.1と2.1.0は同じリリース番号を記す異なる方法であり、リリース2の最初のサブリリースを表します。しかし2.10はリリース2の10番目のリリースであり、2.1や2.1.0とは異なり、新しいリリースとなります。一連の数値の中の先頭のゼロは無視され、そのため2.01は2.1と同じであり、2.0.1とは異なります。

リリース番号に続いて、プレリリースタグかポストリリースタグを付けることができます。プレリリースタグは、それが付加されているバージョンよりも古いバージョンであることを示します。そのため、リビジョン2.4はリビジョン2.4c1よりも新しく、2.4c1は今度は2.4b1や2.4a1よりも新しいです。ポストリリースタグはそれが付加されているバージョンよりも新しいバージョンであることを示します。そのため、2.4-1や2.4pl3のようなリビジョンンは2.4よりも新しく、しかし2.4.1よりは古いです(これはより高いリリース番号を持っています)。

プレリリースタグは一連の文字で、アルファベット順で"final"より前です。プレリリースタグの例として、alpha, beta, a, c, devなどがあります。もしプレリリースタグが数字の直後にあったら、プレリリースタグの前にドットを付ける必要はありません。しかし、あなたがそうしたいのなら、しても構いません。そのため、2.4c1と2.4.c1はどちらもバージョン2.4のリリース候補1を表し、setuptoolsは同じように取り扱います。

さらに、文字cとして扱われる特殊なプレリリースタグが3つあります: preとpreview, rcです。そのため、バージョン2.4rc1と2.4pre1, 2.4preview1はすべて2.4c1とまったく同じです。setuptoolsはこれらを同じに扱います。

ポストリリースタグは一連の文字からなり、アルファベット順で"final"と同じかそれ以降であるか、ダッシュ (-) です。ポストリリースタグは一般的に、パッチ番号やポート番号、ビルド番号、リビジョン番号、日付をリリース番号からわけるために使用されます。例えば、バージョン2.4-r1263はおそらく、バージョン2.4のSubversionのリビジョン1263のポストリリースパッチのことでしょう。あるいは、日付をつけたポストリリースを表すため、2.4-20051127を使うこともできます。

プレリリースタグやポストリリースタグの後ろに、プレリリースタグやポストリリースタグが再度続く他のリリース番号を自由に付けることができるという点に注意してください。たとえば、0.6a9.dev-r41475は、リリース0.6の9番目の開発中のアルファバージョンで、Subversionのリビジョン41475を表すことができます。devはプレリリースタグであるので、このバージョンは0.6a9(リリース0.6の9番目のアルファそのもの)よりも低いバージョン番号であることに注意してください。しかし-r41475はポストリリースタグであるので、このバージョンは0.6a9.devよりは新しいです。

ほとんどの場合において、setuptoolsのバージョン番号の解析は直感的ですが、苦境でトラブルに遭遇しないためのコツがいくつかあります:

  • ポストリリースタグを本当に必要としているのでない限り、- や . 以外の文字を区切り文字として使用しないこと。2.1rc2と2.1.c2はあなたが2.1の前に出したものだということを意味するのに対して、2.1-rc2はあなたがすでに2.1をリリースしていることを意味します。もしあなたがプレリリースを表すポストリリースのコピーを不意に配布してしまった場合、安全に修正する方法は、メインのリリース番号を上げ(すなわち、2.1.1)、プロジェクトを再度リリースすることしかありません。
  • ドットや数字を間に入れることなく、プレリリースタグを詰めて繋げないこと。バージョン1.9adevは、1.9のプレリリースadevであり、1.9aの開発版プレリリースではりません。1.9a.devにように.devを代わりに使用するか、1.9a0devや1.9a.dev, 1.9a0dev, あるいは1.9.a.devのように、プレリリースタグを番号で区切ると、setuptoolsからは同じバージョンとみなされるので、あなたの好きな形式を使えばいいです。

もしあなたの選んだ番号の形式が思った通りに働くか確かめたかったら、pkg_resources.parse_version()関数を使って異なるバージョン番号を比較することができます。

>>> from pkg_resources import parse_version
>>> parse_version('1.9.a.dev') == parse_version('1.9a0dev')
True
>>> parse_version('2.1-rc2') < parse_version('2.1')
False
>>> parse_version('0.6a9dev-r41475') < parse_version('0.6a9')
True

自分のプロジェクトのバージョン番号の形式を決めたら、開発リリースに自動的にプレリリースタグかポストリリースタグを自動的に付けるように、setuptoolsを設定することができます。詳細は、以下の節を参照してください:

新しい、あるいは変更されたsetup()のキーワード

以下のsetup()のキーワード引数は、setuptoolsによって追加されたか、変更されます。すべて、任意の引数です; setuptoolsの機能を使う必要がなければ、これらの引数を指定する必要はありません。

  • include_package_data

Trueに設定したら、setuptoolsは、パッケージのディレクトリ中にあり、かつCVSSubversionの管理下にあるか、MANIFEST.inファイルで指定されているデータファイルを自動的に含めます。詳細は、下の「データファイルを含める」の節を参照してください。

  • exclude_package_data

パッケージ名と、パッケージのディレクトリから除外するファイル名のパターンのリストを対応付ける辞書です。これにより、include_package_dataに含まれる不要なファイルを除外できます。完全な説明と例は、下の「データファイルを含める」の節を参照してください。

  • package_data

パッケージ名と、ファイル名のパターンのリストを対応付ける辞書です。完全な説明と例は、下の「データファイルを含める」の節を参照してください。あなたがinclude_package_dataを使っており、例えばセットアップスクリプトビルドプロセスで生成される(したがって、ソース管理下に入っていないか、ソースの配布に含めたいと思わない)ファイルを含める必要がなければ、このオプションを使う必要はありません。

  • zip_safe

真偽値(TrueまたはFalse)で、プロジェクトがzipファイルから安全にインストールされ、実行されるか指定します。もしこの引数が指定されていなければ、bdist_eggコマンドは、eggをビルドするたびに、問題が発生しないかプロジェクトの中身をすべて解析します。

  • install_requires

文字列か文字列のリストで、この配布物がインストールされるときに、インストールされていなければならない他の配布物を指定します。この引数の形式の詳細と例については、下の「依存関係を宣言する」を参照してください。

  • entry_points

エントリーポイントのグループ名と、エントリーポイントを定義する文字列または文字列のリストを対応付ける辞書です。エントリーポイントは、プロジェクトが提供するサービスまたはプラグインを動的に探す手助けをします。この引数の形式の詳細と例については、下の「サービスとプラグインを動的に発見する」を参照してください。さらに、この引数は、「自動的にスクリプトを生成する」でも使用されます。

  • extras_require

「拡張」(あなたのプロジェクトの付加的な機能)の名前と、その機能を使うためにインストールされていなければならない他の配布物を示す文字列か文字列のリストを対応付ける辞書です。この引数の詳細と形式の例については、下の「依存関係を宣言する」の節を参照してください。

  • setup_requires

文字列または文字列のリストで、セットアップスクリプトを実行するのに必要な他の配布物の名前を指定します。setuptoolsは、セットアップスクリプトやコマンドの残りを実行する前に、(EasyInstallを使ってダウンロードして)これらを入手しようとします。あなたがビルドプロセスの一部としてdistutilsの拡張を使用していたら、この引数が必要です; 例えば、setup()の引数を処理し、それらをEGG-INFOメタデータファイルに入れる拡張です(注意: setup_requiresで指定されているプロジェクトは、セットアップスクリプトが実行されるときに、システムに自動的にインストールされません。もしそれらがローカルで使用可能でなければ、それらは単にセットアップディレクトリダウンロードされるだけです。もし、セットアップスクリプトを実行するときに利用可能となるように、それらをインストールしたければ、install_requiresとsetup_requiresにそれらを追加してください)。

  • dependency_links

依存関係を解決するときに探すURLの文字列のリストです。これらのリンクは、setup_requiresかtests_requiresで指定されているパッケージをインストールする必要があるときに使用されます。これらはまた、EasyInstallのようなツールが.eggファイルをインストールするときに使用されるよう、eggのメタデータに書き込まれます。

  • namespace_packages

プロジェクトの「名前空間パッケージ」を示す文字列のリストです。名前空間パッケージは、複数のプロジェクトの配布物にまたがることができるパッケージです。例えば、Zope 3のzopeパッケージは名前空間パッケージです。なぜならば、zope.interfacezope.publisherのようなサブパッケージを別々に配布することができるからです。eggの実行時のシステムは、このようなサブパッケージを実行時に自動的に、名前空間パッケージの__init__.pyが何のコードも含んでいないかのように、単一の親パッケージにマージします。詳細は、下の「名前空間パッケージ」を参照してください。

  • test_suite

unittest.TestCaseを継承したクラス(またはそのようなクラスをひとつ以上含むパッケージまたはモジュールか、そのようなクラスのメソッド)の名前か、引数なしで呼び出され、unittest.TestSuiteを返す関数の名前を示す文字列です。名前が指しているスイートがモジュールで、モジュールがadditional_tests()関数を持っていたら、それは呼び出され、戻り値が実行するテストに追加されます。名前が示すスイートがパッケージならば、あらゆるサブモジュールとサブパッケージが再帰的にテストスイート全体に追加されます。

この引数を指定すると、例えばsetup.py testを使って、指定されたテストスイートをtestコマンドで実行することができるようになります。詳細は、下のtestコマンドの節を参照してください。

  • tests_require

もしあなたのプロジェクトのテストが、ひとつ以上の追加のパッケージを必要とし、それらをインストールする必要があるときは、このオプションを使って、それらを指定することができます。これは、パッケージのテストを実行するときに存在する必要がある他の配布物を指す文字列か、文字列のリストである必要があります。testコマンドを実行すると、setuptoolsはそれらを入手しようとします(EasyInstallを使ってダウンロードすることもあります)。必要とされるプロジェクトは、テストが実行されるシステムにはインストールされず、ローカルにすでにインストールされていなければ、プロジェクトのセットアップディレクトリダウンロードされるだけだということに、注意してください。

  • test_loader

setuptoolsが通常やるやり方以外で、実行するテストを探す違った方法を使いたいなら、この引数モジュール名とクラス名を指定できます。名前が指し示すクラスは引数なしでインスタンス化可能でなくてはならず、そのインスタンスPythonのunittestモジュールのTestLoaderクラスが定義するようにloadTestsFromNames()メソッドを持っていなければなりません。setuptoolsは、names引数にテストの「名前」だけを渡します: 値は、test_suite引数に与えられたものになります。あなたが指定したローダーは、test_suiteに含まれる文字列に何の制限がないので、好きなようにこの文字列を解析して構いません。

モジュール名とクラス名は : で区切られている必要があります。この引数デフォルトの値は、"setuptools.command.test:ScanningLoader"です。もしデフォルトの挙動通りにunittestを使いたいなら、"test_loader"引数に代わりに"unittest:TestLoader"を指定できます。これで、サブモジュールとサブパッケージを自動的に探すことはなくなります。

testコマンドを実行するときに、ローダークラスを含むパッケージが存在することを保証するためにtests_requireオプションを使う限り、ここで指定するモジュールとクラスが他のパッケージに含まれていても構いません。

  • eager_resources

なんらかのリソースが必要とされたとき、あるいは、プロジェクトに含まれるCの拡張がインポートされるときに、一緒に展開されるリソースを示す文字列のリストです。この引数は、プロジェクトがzipファイルとしてインストールされ、リストの中のリソースファイルシステムに一緒に展開される必要があるときだけ、この引数を使います。リスト中のリソースは'/'で区切られた、ソースからの相対パスである必要があり、そのためパッケージbar.baz中のリソースfoo.pngをリストに加えるときは、この引数にbar/baz/foo.pngを含めます。

もしリソースをその都度取得できればいいだけのときや、プロジェクト内の他のファイル(データファイルや共有ライブラリ)にアクセスしないC言語の拡張を持っていない場合は、あなたはおそらくこの引数を必要としておらず、これで乱雑にするべきではありません。この引数の詳細な動作については、下の「リソースの自動的な拡張」を参照してください。

find_packages()を使う

単純なプロジェクトでは、setup()のpackages引数に手動でパッケージを追加するのは普通簡単です。しかし、大変大きなプロジェクト(TwistedやPEAK, Zope, Chandlerなど)では、パッケージのリストを更新するのには多大な労力を要します。これが、setuptools.find_packages()が存在する理由です。

find_packages()はソースディレクトリと、除外するパッケージ名かパターンのリストをを取ります。省略された場合、ソースディレクトリはセットアップスクリプトと同じディレクトリになります。プロジェクトの中にはsrcやlibディレクトリをソースツリーのルートとするものがあり、それらのプロジェクトではもちろん、find_packages()の最初の引数は"src"または"lib"です(そして、setup()の引数にpackage_dir = {'':'src'}などとする必要がありますが、これは普通のdistutilsの話です)。

いずれにせよ、find_packages()は対象のディレクトリを走査し、__init__.pyファイルを見つけることでPythonのパッケージを探します。このとき、除外するパターンを使ってパッケージのリストを絞り込みます。

除外パターンはパッケージ名で、ワイルドカードを使うこともできます。例えば、find_packages(exclude=["*.tests"])は、名前の最後の部分がtestsであるすべてのパッケージを除外します。あるいは、find_packages(exclude=["*.tests", "*.tests.*"])は、testsという名前のパッケージのすべてのサブパッケージも除外しますが、トップレベルにあるtestsパッケージとそのサブパッケージは除外しません。実際、あなたがtestsパッケージをまったく本当に欲しくない場合は、すべてのパッケージを対象とするために、以下のようにする必要があります:

find_packages(exclude=["*.tests", "*.tests.*", "tests.*", "tests"])

実際には、パッケージとそのサブパッケージを指定してひとつだけ除外するように、除外パターンはこれよりも簡単になるでしょう。

対象ディレクトリや除外に関らず、find_packages()関数はsetup()のpackages引数に使用するのに適したパッケージ名のリストを返すので、あなたのセットアップスクリプト引数に設定するのが普通もっとも簡単な方法です。とくに、プロジェクトがトップレベルのパッケージやサブパッケージを追加して大きくなったときに毎回、セットアップスクリプトを修正するのを思い出さなければならないことから、あなたは解放されます。

自動的にスクリプトを生成する

distutilsを使ってスクリプトをパッケージしてインストールするのは、少々やっかいになることがあります。そのひとつとして、スクリプトのファイル名をWindowsPOSIXの両プラットフォームのローカルの流儀に合わせる簡単な方法がありません。また、実際の"main"がモジュールのどこかの関数であった場合、"main"スクリプトのためだけに別のファイルを作成しなければならないことがあります。Python 2.4においてですら、-mオプションを使っても、パッケージの中にインストールされていない実際の.pyファイルに対してしか動作しません。

setuptoolsは、適切な拡張を使ってスクリプトを自動的に生成することでこれらの問題を解決し、WindowsにおいてはユーザがPATHEXTの設定を変更しなくてもよくなるように.exeファイルの生成すらします。この機能を使うためには、、セットアップスクリプトの中に「エントリポイント」を定義します。これは、生成されたスクリプトにおいてどの関数インポートされ、実行されなければならないかを指定します。例えば、fooとbarというふたつのコンソールスクリプトと、bazというGUIスクリプトを作成するためには、以下のようにします:

setup(
    # other arguments here...
    entry_points = {
        'console_scripts': [
            'foo = my_package.some_module:main_func',
            'bar = other_module:some_func',
        ],
        'gui_scripts': [
            'baz = my_package_gui.start_func',
        ]
    }
)

このプロジェクトがWindowsではないプラットフォームに("setup.py install"か"setup.py develop"かEasyInstallを使って)インストールされた場合、fooとbar, bazスクリプトインストールされ、それらは指定されたモジュールからmain_funcとsome_funcをインポートします。指定された関数引数なしで呼び出され、戻り値はsys.exit()に渡されます。そのため、あなたはエラーレベルを返すか、標準エラー出力にメッセージを表示できます。

Windowsでは、foo.pyとbar.py, baz.pywのファイルに沿って、foo.exeとbar.exe, baz.exeというランチャーが生成されます。これらの.exeラッパーは、.pyファイルか.pywファイルを実行するのに適切なバージョンのPythonを探して実行します。

あなたは"console script"と"gui script"のエントリポイントを好きなだけ定義でき、それぞれにおいて、依存している"extras"を指定することができます。これは、スクリプトが実行されるときに、sys.pathに追加されます。"extras"のより詳細な情報は、下の「「エキストラ」を宣言する(オプションの機能と依存物)」を参照してください。「エントリポイント」の一般的な情報については、下の「サービスとプラグインを動的に発見する」を参照してください。

依存関係を宣言する

setuptoolsは、パッケージをインストールするときに、依存しているものを自動的にインストールすることができます。また、Python Eggに、依存に関する情報を含めることができます(そのため、EasyInstallのようなパッケージ管理ツールは、この情報を使うことができます)。

setuptoolsとpkg_resourcesは、プロジェクトに必要なものを指定するのに、同じシンタックスを使用します。このシンタックスは、プロジェクトのPyPI名を記述し、必要ならばブラケット中に"extras"をコンマで区切ったリストを続け、必要ならばバージョン指定子をコンマで区切って続けます。バージョン指定子は、バージョン識別子の後に、演算子<か>, <=, >=, ==, !=のどれかひとつを続けて記述します。トークンを空白で区切ってもいいですが、プロジェクト名とバージョン識別子の中にある空白や非標準の文字は、-で置き換えなければなりません。

プロジェクトのバージョン指定子は、バージョン順で昇順に内部で並び替えられ、受け入れられるバージョンの範囲が求められます。隣接した冗長な条件は、整理されます(すなわち、">1, >2"は">1"となり、"<2,<3"は"<3"となります)。"!="とされたバージョンは、含まれる範囲から除外されます。それから、プロジェクトのバージョンが結果の範囲内にあるか検査されます(同じバージョンに対して衝突する条件(すなわち、"<2,>=2"とか"==2,!=2"とか)を与えるのは無意味で、奇妙な結果になります)。

要求指定子の例を挙げます:

docutils >= 0.3

# コメント文と、要求文字列の中で\による文の継続が使用できます。
BazSpam ==1.1, ==1.2, ==1.3, ==1.4, ==1.5, \
    ==1.6, ==1.7  # 行末のコメント

PEAK[FastCGI, reST]>=0.5a4

setuptools==0.5a7

要求指定子を含めるもっとも簡単な方法は、setup()のinstall_requires引数を使用することです。これは、要求指定子を含む文字列か、文字列のリストを取ります。もし文字列中にふたつ以上の要求を含める場合は、1行にひとつの要求を記述しなければなりません。

これは、3つの効果を持ちます:

  1. EasyInstallでもsetup.py installでもsetup.py developでも、プロジェクトがインストールされるとき、依存しているものでインストールされていないものはすべて、探され(PyPIから)、ダウンロードされ、(必要なら)ビルドされ、そしてインストールされます。
  2. あなたのプロジェクト中のすべてのスクリプトラッパーとともにインストールされ、実行時に指定された依存しているものが利用可能か調べられ、正しいバージョンがsys.pathに追加されます(すなわち、複数のバージョンがインストールされた場合)。
  3. Python Egg配布物は、依存関係の一覧をメタデータファイルに含めます。

ところで、もしあなたがsetup.pyに依存関係を宣言した場合、プロジェクトをインストールしたり、開発のためにsetup.py developを使う限り、スクリプトモジュールでrequire()関数を使う必要はありません(setup.py developを使うことの詳細な情報は、下の「開発モード」を参照してください)。

PyPIにない依存物

あなたのプロジェクトがPyPIに登録されていないパッケージに依存している場合、それらがeggとして、あるいは標準のdistutilsのsdist形式で、あるいは単一の.pyファイルとしてダウンロード可能である限り、まだそれらに依存することが可能です。あなたは、setup()のdependency_links引数に、URLを追加しさえすればよいです。

このURLは、以下のどちらかである必要があります:

  1. 直接ダウンロードできるURL
  2. 直接ダウンロードできるリンクがあるウェブページURL

一般的には、ウェブページにリンクした方がよいです。なぜならば、ウェブページを更新するのは、あなたのプロジェクトの新しいバージョンをリリースするより普通は簡単だからです。あなたが依存しているパッケージがSourceForgeで配布されていたら、SourceForgeのshowfiles.phpを使うこともできます。

もし単一の.pyファイルとして配布されているパッケージに依存していたら、URLに"#egg=project-version"接尾語を含め、プロジェクト名とバージョン番号を与えなければなりません(名前とバージョン中のダッシュをアンダースコアに置換してエスケープするのを忘れないでください)。EasyInstallはこの接尾語を認識して、単一の.pyファイルをeggとしてラップする平凡なsetup.pyを作成します。

dependency_links引数は、URLの文字列のリストを受け取ります。例えば以下は、パッケージが依存しているものがインストールされていなければ、EasyInstallは指定されたページからeggかソース配布物を探します:

setup(
    ...
    dependency_links = [
        "http://peak.telecommunity.com/snapshots/"
    ],
)
"extras"を宣言する(オプションの機能と依存物)

ときにはプロジェクトが、プロジェクトのすべての使用には必要としない「推奨する」依存物をもつことがあります。例えば、ReportLabインストールされていた場合、プロジェクトはPDF出力の機能を追加され、docutilsがインストールされていた場合はreStructuredTextに対応します。それらの付加的な機能は"extras"と呼ばれ、setuptoolsでそれらに必要なものを定義できます。この方法だと、それらの付加的な機能を要求する他のプロジェクトは、install_requiresに必要なextrasを記述することで、追加で必要とされるものがインストールされるのを強制できます。

例えば、Project AがPDFreSTオプションで対応する場合:

setup(
    name="Project-A",
    ...
    extras_require = {
        'PDF':  ["ReportLab>=1.2", "RXP"],
        'reST': ["docutils>=0.3"],
    }
)

このように、extras_requires引数は、"extra"の機能の名前を、それらの機能に必要なものを記述する文字列か文字列のリストを受け取ります。これらの要求されたものは、他のパッケージがプロジェクト名の後ろのブラケット中に希望する"extras"を含めて(直接的にあるいは間接的に)依存していない限り(あるいは、EasyInstallのコマンドラインで必要なスペック中に記述されない限り)、自動的にはインストールされません。

extrasは、動的な依存を指定する、プロジェクトのエントリポイントに使われることもできます。例えば、Project Aが"rst2pdf"スクリプトを含んでいるとき、以下のように記述し、"rst2pdf"スクリプトが実行されるときにだけ"PDF"への要求を解決するようにできます:

setup(
    name="Project-A",
    ...
    entry_points = {
        'console_scripts':
            ['rst2pdf = project_a.tools.pdfgen [PDF]'],
            ['rst2html = project_a.tools.htmlgen'],
            # more script entry points ...
    }
)

依存関係を指定するとき、プロジェクトは他のプロジェクトのextrasを使うこともできます。例えば、もしProject BがPDFに対応してインストールされている"Project A"を必要としているとき、依存関係を以下のように記述できます:

setup(
    name="Project-B",
    install_requires = ["Project-A[PDF]"],
    ...
)

これで、もしProject Bがインストールされるとき、Project Aがすでにインストールされているときであっても、ReportLabがProject Aとともにインストールされます。この方法で、付加的な「依存関係の下流」のグループを機能名で隠蔽することができ、依存しているパッケージが、依存関係の下流がどんなであるか、知る必要がなくなります。もしProject Aの新しいバージョンがPDFに対応してビルドされ、もはやReportLabを必要としなくなり、あるいはPDFへ対応するためにReportLab以外のものに依存するようになった場合、Project Bのセットアップ情報は変更される必要がなく、しかし必要であれば正しいパッケージがインストールされます。

ところで注意する点として、プロジェクトがある機能に対応するのに他のパッケージを必要としなくなった場合、extras_require引数でその機能については空のリストにしておかなければならず、これによりこの機能に依存するパッケージは壊れません(利用できない機能名のために)。例えば、上のProject AがPDFに対応してビルドされ、それからReportLabを必要としなくなった場合、setupを次のように書き換えます:

setup(
    name="Project-A",
    ...
    extras_require = {
        'PDF':  [],
        'reST': ["docutils>=0.3"],
    }
)

これにより、Package Bは要求指定子から[PDF]を削除する必要がありません。

データファイルを含める

distutilsは伝統的に「データファイル」のインストールを認めていますが、データファイルが置かれる場所はプラットフォームによって異なります。しかし、パッケージと一緒に配布されるデータファイルのもっとも共通のユースケースは、そのパッケージによって使われることであり、普通そのパッケージのディレクトリ内にデータファイルを含めます。

setuptoolsでパッケージにデータファイルを含めるよう指定する方法は、3つあります。最初の方法は、単にinclude_package_dataキーワードを使用する方法で、すなわち:

from setuptools import setup, find_packages
setup(
    ...
    include_package_data = True
)

これで、setuptoolsはパッケージ内で見つかったすべてのデータファイルをインストールします。データフぁいるはCVSSubversionの管理下になければならず、あるいはdistutilsのMANIFEST.inファイルで指定されていなければなりません(適切なプラグインを使えば、他のバージョン管理システムを使うこともできます。そのようなプラグインの書き方の情報については、下の「他のバージョン管理システムに対応する」を参照してください)。

もしどのファイルが含まれるかもっとよく制御したかったら(例えば、パッケージディレクトリにドキュメントを含めていて、それらをインストールから排除したいとき)、package_dataキーワードを使用できます:

from setuptools import setup, find_packages
setup(
    ...
    package_data = {
        # 任意のパッケージが*.txtや*.rstを持っていたら、それらを含める: 
        '': ['*.txt', '*.rst'],
        # 'hello'パッケージ内のすべての*.msgファイルも含める: 
        'hello': ['*.msg'],
    }
)

package_data引数は辞書で、パッケージ名をファイル名のパターンに対応づけます。データファイルがパッケージのサブディレクトリ中にあったら、ファイル名のパターンにはサブディレクトリの名前を含めることもできます。例えば、パッケージツリーが以下のようになっていたとします:

setup.py
src/
    mypkg/
        __init__.py
        mypkg.txt
        data/
            somefile.dat
            otherdata.dat

setuptoolsのセットアップファイルは、以下のようにできます:

from setuptools import setup, find_packages
setup(
    ...
    packages = find_packages('src'),  # src下のすべてのパッケージを含める
    package_dir = {'':'src'},   # distutilsに、パッケージがsrc下にあることを教える

    package_data = {
        # 任意のパッケージが*.txtファイルを持っていたら、それらを含める: 
        '': ['*.txt'],
        # 'mypkg'パッケージの'data'サブディレクトリ内で見つかったすべての*.dat
        # ファイルを含める: 
        'mypkg': ['data/*.dat'],
    }
)

次の点に注意してください。package_dataで、空の文字列に対してパターンを列挙したら、それらのパターンはすべてのパッケージでファイルを見つけるのに使用されます。パッケージが、自分自身のパターンのリストを持っていてもです。そのため、上の例では、mypkg.txtファイルは、mypkgにおいては列挙されていなくても、含まれることになります。

また、パスを使うときは、Windowsを使っていたとしても、パスのセパレータにはスラッシュ (/) を使用しなければならないことも、注意してください。setuptoolsは自動的にスラッシュを適切なプラットフォーム特有のセパレータに、ビルド時に変換します(注意: 以前、package_data引数はsetuptoolsでしか使用できませんでしたが、Python 2.4のPython distutilsパッケージにも追加されました; python.orgのウェブサイトに、利用可能な機能に関するドキュメントがあります)。

ときには、include_package_dataやpackage_dataオプション単体ではどのファイルを含めるのか正確に定義するのに充分ではないことがあります。例えば、バージョン管理システムとソース配布物にはパッケージのREADMEファイルを含めたいが、インストール時には排除したいときです。setuptoolsは、exclude_package_dataオプションを持っており、以下のようにして使うことができます:

from setuptools import setup, find_packages
setup(
    ...
    packages = find_packages('src'),  # src以下のすべてのパッケージを含める
    package_dir = {'':'src'},   # distutilsにパッケージがsrc下にあることを教える

    include_package_data = True,    # バージョン管理システムにあるものすべてを含める

    # ...だたし、すべてのパッケージからREADME.txtを排除する
    exclude_package_data = { '': ['README.txt'] },
)

exclude_package_dataオプションは辞書で、パッケージ名をワイルドカードのパターンのリストに対応づけます。ちょうどpackage_dataオプションのようなものです。そして、package_dataオプションと同じように、''というキーは、すべてのパッケージに対して指定されたパターンを適用します。しかし、それらのパターンにマッチしたファイルは、インストールから排除されます。たとえ、package_dataに列挙されていたり、include_package_dataの結果に含まれていたとしてもです。

まとめると、3つのオプションで:

  • include_package_data

MANIFEST.inにマッチするか、バージョン管理システム下にあるすべてのデータファイルとディレクトリを受け入れます。

  • package_data

MANIFEST.inにマッチするかあるいはバージョン管理システム下にあるかに関らず、ファイルとディレクトリにマッチさせる追加のパターンを指定します。

  • exclude_package_data

パッケージがインストールされるときに含めないようにするファイルとディレクトリのパターンを指定します。それらが上のオプションの結果含まれることになっていたとしても。

注意: distutilsのビルドプロセスの挙動により、プロジェクトに含めた後含めるのをやめたデータファイルは、プロジェクトのビルドディレクトリ中でみなしごとなり、setup.py clean --allを実行して完全に削除する必要があります。あなたのユーザやコントリビュータがSubversionを使ってあなたのプロジェクトの中間のリビジョンを追いかけている場合、彼らにとっても重要です; 含まれているファイルを削除するように変更した場合は、setup.py clean --allを実行するように、彼らに教えるのを忘れないでください。

実行時にデータファイルにアクセスする

典型的には、存在するプログラムは、データファイルの場所を探すために、パッケージの__file__属性を操作します。しかしこの操作は、zipファイルとPython Eggからのimportも含めて、PEP302に基づいたimportのフックとは互換性がありません。データファイルを使用する際は、それらにアクセスするためにpkg_resourcesのリソース管理APIを使用することが、強く推奨されます。pkg_resourcesモジュールはsetuptoolsの一部として配布され、リソース管理APIを使用しない理由はありません。__file__の代わりにpkg_resourcesを使うようにコードを変換する簡潔な例については、パッケージのリソースにアクセスするを参照してください。

以下翻訳中。

スパム対策のためのダミーです。もし見えても何も入力しないでください
ゲスト


画像認証