1. Distutilsの紹介

注釈

このドキュメントは、 https://setuptools.readthedocs.io/en/latest/setuptools.html にある setuptools のドキュメントが現時点でここにある関連情報を全て網羅するまで、単独でここに載せておかれます。

このドキュメントで扱っている内容は、 Distutils を使った Python モジュールの配布で、とりわけ開発者/配布者の役割に重点を置いています: Python モジュールのインストールに関する情報を探しているのなら、 Python モジュールのインストール (旧版) を参照してください。

1.1. 概念と用語

Distutils の使い方は、モジュール開発者とサードパーティ製のモジュールをインストールするユーザ/管理者のどちらにとってもきわめて単純です。開発者側のやるべきことは (もちろん、しっかりした実装で、詳しく文書化され、よくテストされたコードを書くことは別として！) 以下の項目になります:

  • setup スクリプト (setup.py という名前にするのがならわし) を書く

  • (必要があれば) setup 設定ファイルを書く

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

  • (必要があれば) 一つまたはそれ以上のビルド済み (バイナリ) 形式の配布物を作成する

これらの作業については、いずれもこのドキュメントで扱っています。

全てのモジュール開発者が複数の実行プラットフォームを利用できるわけではないので、全てのプラットフォーム向けにビルド済みの配布物を提供してもらえると期待するわけにはいきません。ですから、仲介を行う人々、いわゆる パッケージ作成者 (packager) がこの問題を解決すべく立ち上がってくれることが望ましいでしょう。パッケージ作成者はモジュール開発者がリリースしたソースコード配布物を、一つまたはそれ以上のプラットフォーム上でビルドして、得られたビルド済み配布物をリリースすることになります。したがって、ほとんどの一般的なプラットフォームにおけるユーザは、setup スクリプト一つ実行せず、コードを一行たりともコンパイルしなくても、使っているプラットフォーム向けのきわめて普通の方法でほとんどの一般的な Python モジュール配布物をインストールできるでしょう。

1.2. 簡単な例

setup スクリプトは通常単純なものですが、Python で書かれているため、スクリプト中で何かを処理しようと考えたとき特に制限はありません。とはいえ、setup スクリプト中に何かコストの大きな処理を行うときは十分注意してください。autoconf 形式の設定スクリプトとは違い、setup スクリプトはモジュール配布物をビルドしてインストールする中で複数回実行されることがあります。

foo.py という名前のファイルに収められている foo という名前のモジュールを配布したいだけなら、setup スクリプトは以下のような単純なものになります:

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

以下のことに注意してください:

  • Distutils に与えなければならない情報のほとんどは、 setup() 関数のキーワード引数として与えます

  • キーワード引数は二つのカテゴリ: パッケージのメタデータ (パッケージ名、バージョン番号)、パッケージに何が収められているかの情報 (上の場合は pure Python モジュールのリスト)、に行き着きます

  • モジュールはファイル名ではなく、モジュール名で指定します (パッケージと拡張モジュールについても同じです)

  • 作者名、電子メールアドレス、プロジェクトの URL といった追加のメタデータを入れておくよう奨めます (setup スクリプトを書く の例を参照してください)

このモジュールのソース配布物を作成するには、上記のコードが書かれた setup スクリプト setup.py を作成し、端末からこのコマンドを実行してください:

python setup.py sdist

Windows では、コマンドプロンプトのウィンドウを開き (スタート ‣ アクセサリ) 、次のようにコマンドを変えてください:

setup.py sdist

sdist は、 setup スクリプト setup.py とモジュール foo.py を含むアーカイブファイル (例。 Unix の tarball や Windows の ZIP ファイル) を作成します。アーカイブファイルは foo-1.0.tar.gz (あるいは .zip) という名前になり、 foo-1.0 というディレクトリに展開されます。

エンドユーザが foo モジュールをインストールしたければ、 foo-1.0.tar.gz (または .zip) をダウンロードし、それを展開して、以下のスクリプトを --- foo-1.0 ディレクトリ中で --- 実行するだけです

python setup.py install

この操作を行うと、インストールされている Python での適切なサードパーティ製モジュール置き場に foo.py を完璧にコピーします。

ここで述べた簡単な例では、 Distutils の基本的な概念のいくつかを示しています。まず、開発者とインストール作業者は同じ基本インターフェース、すなわち setup スクリプトを使っています。二人の作業の違いは、使っている Distutils コマンド (command) にあります: sdist コマンドは、ほぼ完全に開発者だけが対象となる一方、 install はどちらかというとインストール作業者向けです (とはいえ、ほとんどの開発者は自分のコードをインストールしたくなることがあるでしょう)。

その他の有用な配布形態としては、 bdist_rpm に実装されている RPM 形式、 Solaris pkgtool (bdist_pkgtool) 、 HP-UX swinstall (bdist_sdux) があります。例えば、以下のコマンドを実行すると、 foo-1.0.noarch.rpm という名前の RPM ファイルを作成します:

python setup.py bdist_rpm

(bdist_rpm コマンドは rpm コマンドを使うため、 Red Hat Linux や SuSE Linux、 Mandrake Linux といった RPM ベースのシステムで実行しなければなりません)

どの配布形式が利用できるかは、これを実行すれば分かります

python setup.py bdist --help-formats

1.3. Python 一般の用語

このドキュメントを読んでいるのなら、モジュール (module)、拡張モジュール (extension) などが何を表すのかをよく知っているかもしれません。とはいえ、読者がみな共通のスタートポイントに立って Distutils の操作を始められるように、ここで一般的な Python 用語について以下のような用語集を示しておきます:

module

Python においてコードを再利用する際の基本単位: すなわち、他のコードから import されるひとかたまりのコードです。ここでは、三種類のモジュール: pure Python モジュール、拡張モジュール、パッケージが関わってきます。

pure Python モジュール

Python で書かれ、単一の .py ファイル内に収められたモジュールです (.pyc ファイルと関連があります) 。 "pure モジュール (pure module)" と呼ばれることもあります。

extension module

Python を実装している低水準言語: Python の場合は C/C++ 、 Jython の場合は Java 、で書かれたモジュールです。通常は、動的にロードできるコンパイル済みの単一のファイルに入っています。例えば、Unix向け Python 拡張のための共有オブジェクト (.so) 、 Windows 向け Python 拡張のための DLL (.pyd という拡張子が与えられています)、 Jython 拡張のための Java クラスといった具合です。 (現状では、 Distutils は Python 向けの C/C++ 拡張モジュールしか扱わないので注意してください。)

package

他のモジュールが入っているモジュールです; 通常、ファイルシステム内のあるディレクトリに収められ、 __init__.py が入っていることで通常のディレクトリと区別できます。

ルートパッケージ

階層的なパッケージの根 (root) の部分にあたるパッケージです。(この部分には __init__.py ファイルがないので、本当のパッケージではありませんが、便宜上そう呼びます。) 標準ライブラリの大部分はルートパッケージに入っています、また、多くの小規模な単体のサードパーティモジュールで、他の大規模なモジュールコレクションに属していないものもここに入ります。正規のパッケージと違い、ルートパッケージ上のモジュールの実体は様々なディレクトリにあります: 実際は、 sys.path に列挙されているディレクトリ全てが、ルートパッケージに配置されるモジュールの内容に影響します。

1.4. Distutils 固有の用語

以下は Distutils を使って Python モジュールを配布する際に使われる特有の用語です:

モジュール配布物

単一のダウンロード可能なリソースとして配布され、一纏めに インストールできる Python モジュールの集まりです。よく知られているモジュール配布物の例は NumPy、SciPy、Pillow、mxBase です。(Python の文脈で既に使われてるとき以外は、これは パッケージ と呼ばれます: 1 つのモジュール配布物は 0 個か 1 個かもっと多くの Python パッケージを含みます。)

pure module distribution

pure Python モジュールやパッケージだけが入ったモジュール配布物です。"pure 配布物 (pure distribution)" とも呼ばれます。

non-pure module distribution

少なくとも一つの拡張モジュールが入ったモジュール配布物です。"非 pure 配布物"とも呼びます。

配布物ルート

ソースコードツリー (またはソース配布物) ディレクトリの最上階層で、 setup.py のある場所です。一般的には、 setup.py はこのディレクトリ上で実行します。