# 7. 使用例

この章は distutils を使い始めるのに役立つ幾つかの基本的な例を提供します。distutils を使うための追加の情報は Distutils Cookbook で見つけることができます。

参考

Distutils Cookbook

  distutils をもっと制御するためのレシピ集。

## 7.1. pure Python 配布物 (モジュール形式)

単に二つのモジュール、特定のパッケージに属しないモジュールを配布するだけなら、setup スクリプト中で `py_modules` オプションを使って個別に指定できます。

もっとも単純なケースでは、二つのファイル: setup スクリプト自体と、配布したい単一のモジュール、この例では `foo.py` について考えなければなりません:

    <root>/
            setup.py
            foo.py

(この節の全ての図において、<root> は配布物ルートディレクトリを参照します。) この状況を扱うための最小の setup スクリプトは以下のようになります:

    from distutils.core import setup
    setup(name='foo',
          version='1.0',
          py_modules=['foo'],
          )

配布物の名前は `name` オプションで個々に指定し、配布されるモジュールの一つと配布物を同じ名前にする必要はないことに注意してください (とはいえ、この命名方法はよいならわしでしょう)。ただし、配布物名はファイル名を作成するときに使われるので、文字、数字、アンダースコア、ハイフンだけで構成しなければなりません。

`py_modules` はリストなので、もちろん複数のモジュールを指定できます。例えば、モジュール `foo` と `bar` を配布しようとしているのなら、 setup スクリプトは以下のようになります:

    <root>/
            setup.py
            foo.py
            bar.py

また、セットアップスクリプトは以下のようになります

    from distutils.core import setup
    setup(name='foobar',
          version='1.0',
          py_modules=['foo', 'bar'],
          )

モジュールのソースファイルは他のディレクトリに置けますが、そうしなければならないようなモジュールを沢山持っているのなら、モジュールを個別に列挙するよりもパッケージを指定した方が簡単でしょう。

## 7.2. pure Python 配布物 (パッケージ形式)

二つ以上のモジュールを配布する場合、とりわけ二つのパッケージに分かれている場合、おそらく個々のモジュールよりもパッケージ全体を指定する方が簡単です。たとえモジュールがパッケージ内に入っていなくても状況は同じで、その場合はルートパッケージにモジュールが入っていると Distutils に教えることができ、他のパッケージと同様にうまく処理されます (ただし、 `__init__.py` があってはなりません)。

最後の例で挙げた setup スクリプトは

    from distutils.core import setup
    setup(name='foobar',
          version='1.0',
          packages=[''],
          )

のようにも書けます (空文字はルートパッケージを意味します)

これら二つのファイルをサブディレクトリ下に移動しておいて、インストール先はルートパッケージのままにしておきたい、例えば:

    <root>/
            setup.py
            src/      foo.py
                      bar.py

のような場合には、パッケージ名にはルートパッケージをそのまま指定しておきますが、ルートパッケージに置くソースファイルがどこにあるかを Distutils に教えなければなりません:

    from distutils.core import setup
    setup(name='foobar',
          version='1.0',
          package_dir={'': 'src'},
          packages=[''],
          )

もっと典型的なケースでは、複数のモジュールを同じパッケージ (またはサブパッケージ) に入れて配布しようと思うでしょう。例えば、 `foo` と `bar` モジュールがパッケージ `foobar` に属する場合、ソースツリーをレイアウトする一案として、以下が考えられます

    <root>/
            setup.py
            foobar/
                     __init__.py
                     foo.py
                     bar.py

実際、Distutils ではこれをデフォルトのレイアウトとして想定していて、setup スクリプトを書く際にも最小限の作業しか必要ありません:

    from distutils.core import setup
    setup(name='foobar',
          version='1.0',
          packages=['foobar'],
          )

モジュールを入れるディレクトリをパッケージの名前にしたくない場合、ここでも `package_dir` オプションを使う必要があります。例えば、パッケージ `foobar` のモジュールが `src` に入っているとします:

    <root>/
            setup.py
            src/
                     __init__.py
                     foo.py
                     bar.py

適切な setup スクリプトは、以下のようになるでしょう

    from distutils.core import setup
    setup(name='foobar',
          version='1.0',
          package_dir={'foobar': 'src'},
          packages=['foobar'],
          )

また、メインパッケージ内のモジュールを配布物ルート下に置くことがあるかもしれません:

    <root>/
            setup.py
            __init__.py
            foo.py
            bar.py

この場合、setup スクリプトは

    from distutils.core import setup
    setup(name='foobar',
          version='1.0',
          package_dir={'foobar': ''},
          packages=['foobar'],
          )

のようになるでしょう。(空文字列も現在のディレクトリを表します。)

サブパッケージがある場合、 `packages` で明示的に列挙しなければなりませんが、 `package_dir` はサブパッケージへのパスを自動的に展開します。 (別の言い方をすれば、 Distutils はソースツリーを 走査せず 、どのディレクトリが Python パッケージに相当するのかを `__init__.py` files. を探して調べようとします。) このようにして、デフォルトのレイアウトはサブパッケージ形式に展開されます:

    <root>/
            setup.py
            foobar/
                     __init__.py
                     foo.py
                     bar.py
                     subfoo/
                               __init__.py
                               blah.py

対応する setup スクリプトは以下のようになります

    from distutils.core import setup
    setup(name='foobar',
          version='1.0',
          packages=['foobar', 'foobar.subfoo'],
          )

## 7.3. 単体の拡張モジュール

拡張モジュールは、`ext_modules` オプションを使って指定します。`package_dir` は、拡張モジュールのソースファイルをどこで探すかには影響しません; pure Python モジュールのソースのみに影響します。もっとも単純なケースでは、単一の C ソースファイルで書かれた単一の拡張モジュールは以下のようになります:

    <root>/
            setup.py
            foo.c

`foo` 拡張モジュールがルートパッケージに属している場合は、 setup スクリプトは次のように書けます

    from distutils.core import setup
    from distutils.extension import Extension
    setup(name='foobar',
          version='1.0',
          ext_modules=[Extension('foo', ['foo.c'])],
          )

同じソースツリーレイアウトで、この拡張モジュールを `foopkg` の下に置き、拡張モジュールの名前を変えるには

`foopkg` 拡張をルートパッケージ下に所属させたい場合、 setup スクリプトは以下のようにします:

    from distutils.core import setup
    from distutils.extension import Extension
    setup(name='foobar',
          version='1.0',
          ext_modules=[Extension('foopkg.foo', ['foo.c'])],
          )

## 7.4. パッケージのチェック

`check` コマンドで、パッケージのメタデータが配布物をビルドするための最低限の条件を満たしているかの検証が行えます。

コマンドを実行するには、単純に `setup.py` スクリプトを使って呼び出してください。何かが不足していた場合は、 `check` で警告が表示されるでしょう。

簡単なスクリプトを例に取ってみましょう:

    from distutils.core import setup

    setup(name='foobar')

`check` コマンドを走らせると、いくつかの警告が表示されます:

    $ python setup.py check
    running check
    warning: check: missing required meta-data: version, url
    warning: check: missing meta-data: either (author and author_email) or
             (maintainer and maintainer_email) must be supplied

`long_description` フィールドで reStructuredText の構文を使用し、docutils がインストールされている場合は、`check` コマンドに `restructuredtext` オプションを使用して、その構文が正しいかどうかチェックできます。

例えば、 `setup.py` スクリプトを次のように変えたとします:

    from distutils.core import setup

    desc = """\
    My description
    ==============

    This is the description of the ``foobar`` package.
    """

    setup(name='foobar', version='1', author='tarek',
        author_email='tarek@ziade.org',
        url='http://example.com', long_description=desc)

long description の壊れている箇所を、 `docutils` 構文解析器を使い `check` で検出できます:

    $ python setup.py check --restructuredtext
    running check
    warning: check: Title underline too short. (line 2)
    warning: check: Could not finish the parsing.

## 7.5. メタデータの読み込み

`distutils.core.setup()` 関数は、プロジェクトの `setup.py` スクリプトを通して、プロジェクトのメタデータフィールドの値を調べることのできるコマンドライン・インターフェイスを提供します:

    $ python setup.py --name
    distribute

この呼び出しは、 `distutils.core.setup()` 関数を実行して `name` メタデータを読み取っています。ソース配布物もしくはバイナリ配布物が Distutils で作られていたとしても、メタデータフィールドは `PKG-INFO` という静的なファイルに書かれます。Distutils ベースのプロジェクトが Python にインストールされるとき、 `NAME-VERSION-pyX.X.egg-info` 以下にある配布物のモジュールやパッケージと一緒に `PKG-INFO` がコピーされます。ここで `NAME` はプロジェクト名、 `VERSION` はメタデータで定義されたバージョン、 `pyX.X` は `2.7` や `3.2` のような Python のメジャーバージョンとマイナーバージョンです。

`distutils.dist.DistributionMetadata` クラスとその `read_pkg_file()` メソッドを使って、この静的ファイルを読むことができます:

    >>> from distutils.dist import DistributionMetadata
    >>> metadata = DistributionMetadata()
    >>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))
    >>> metadata.name
    'distribute'
    >>> metadata.version
    '0.6.8'
    >>> metadata.description
    'Easily download, build, install, upgrade, and uninstall Python packages'

このクラスは、値を読み取るメタデータのファイルパスを引数に取ってインスタンス化することもできることに注意してください:

    >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info'
    >>> DistributionMetadata(pkg_info_path).name
    'distribute'