2. setup スクリプトを書く
*************************

注釈:

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

setup スクリプトは、Distutils を使ってモジュールをビルドし、配布し、イ
ンストールする際の全ての動作の中心になります。 setup スクリプトの主な
目的は、モジュール配布物について Distutils に伝え、モジュール配布を操
作するための様々なコマンドを正しく動作させることにあります。上の 簡単
な例 の節で見てきたように、 setup スクリプトは主に "setup()" の呼び出
しからなり、開発者が distuils に対して与えるほとんどの情報は "setup()"
のキーワード引数として指定されます。

ここではもう少しだけ複雑な例: Distutils 自体の setup スクリプト、を示
します。これについては、以降の二つの節でフォローします。 (Distutils が
入っているのは Python 1.6 以降であり、 Python 1.5.2 ユーザが他のモジュ
ール配布物をインストールできるようにするための独立したパッケージがある
ことを思い出してください。ここで示した、Distutils 自身の setup スクリ
プトは、Python 1.5.2 に Distutils パッケージをインストールする際に使い
ます。)

   #!/usr/bin/env python

   from distutils.core import setup

   setup(name='Distutils',
         version='1.0',
         description='Python Distribution Utilities',
         author='Greg Ward',
         author_email='gward@python.net',
         url='https://www.python.org/sigs/distutils-sig/',
         packages=['distutils', 'distutils.command'],
        )

上の例と、 簡単な例 で示したファイル一つからなる小さな配布物とは、違う
ところは二つしかありません: メタデータの追加と、モジュールではなくパッ
ケージとして pure Python モジュール群を指定しているという点です。この
点は重要です。というのも、 Distutils は 2 ダースものモジュールが (今の
ところ) 二つのパッケージに分かれて入っているからです; 各モジュールにつ
いていちいち明示的に記述したリストは、作成するのが面倒だし、維持するの
も難しくなるでしょう。その他のメタデータについては、 追加のメタデータ
を参照してください。

setup スクリプトに与えるパス名 (ファイルまたはディレクトリ) は、 Unix
におけるファイル名規約、つまりスラッシュ ('/') 区切りで書かねばなりま
せん。Distutils はこのプラットフォーム中立の表記を、実際にパス名として
使う前に、現在のプラットフォームに適した表記に注意深く変換します。この
機能のおかげで、setup スクリプトを異なるオペレーティングシステム間にわ
たって可搬性があるものにできます。言うまでもなく、これは Distutils の
大きな目標の一つです。この精神に従って、このドキュメントでは全てのパス
名をスラッシュ区切りにしています。

もちろん、この取り決めは Distutils に渡すパス名だけに適用されます。も
し、例えば "glob.glob()" や "os.listdir()" のような、標準の Python 関
数を使ってファイル群を指定するのなら、パス区切り文字 (path separator)
をハードコーディングせず、以下のように可搬性のあるコードを書くよう注意
すべきです:

   glob.glob(os.path.join('mydir', 'subdir', '*.html'))
   os.listdir(os.path.join('mydir', 'subdir'))


2.1. パッケージを全て列挙する
=============================

"packages" オプションは、 "packages" リスト中で指定されている各々のパ
ッケージについて、パッケージ内に見つかった全ての pure Python モジュー
ルを処理 (ビルド、配布、インストール、等) するよう Distutils に指示し
ます。このオプションを指定するためには、当然のことながら各パッケージ名
はファイルシステム上のディレクトリ名と何らかの対応付けができなければな
りません。デフォルトで使われる対応関係はきわめてはっきりしたものです。
すなわち、パッケージ "distutils" が配布物ルートディレクトリからの相対
パス "distutils" で表されるディレクトリ中にあるというものです。つまり
、setup スクリプト中で "packages = ['foo']" と指定したら、スクリプトの
置かれたディレクトリからの相対パスで "foo/__init__.py" を探し出せると
Distutils に確約したことになります。この約束を裏切ると Distutils は警
告を出しますが、そのまま壊れたパッケージの処理を継続します。

ソースコードディレクトリの配置について違った規約を使っていても、まった
く問題はありません: 単に "package_dir" オプションを指定して、
Distutils に自分の規約を教えればよいのです。例えば、全ての Python ソー
スコードを "lib" 下に置いて、 "ルートパッケージ" 内のモジュール (つま
り、どのパッケージにも入っていないモジュール) を "lib" 内に入れ、
"foo" パッケージを "lib/foo" に入れる、といった具合にしたいのなら

   package_dir = {'': 'lib'}

を setup スクリプト内に入れます。辞書内のキーはパッケージ名で、空のパ
ッケージ名はルートパッケージを表します。キーに対応する値はルートパッケ
ージからの相対ディレクトリ名です、この場合、 "packages = ['foo']" を指
定すれば、 "lib/foo/__init__.py" が存在すると Distutils に確約したこと
になります。

もう一つの規約のあり方は "foo" パッケージを "lib" に置き換え、
"foo.bar" パッケージが "lib/bar" にある、などとするものです。このよう
な規約は、 setup スクリプトでは

   package_dir = {'foo': 'lib'}

のように書きます。 "package_dir" 辞書に "package: dir" のようなエント
リがあると、 *package* の下にある全てのパッケージに対してこの規則が暗
黙のうちに適用され、その結果 "foo.bar" の場合が自動的に処理されます。
この例では、 "packages = ['foo', 'foo.bar']" は、 Distutils に
"lib/__init__.py" と "lib/bar/__init__.py" を探すように指示します。
("package_dir" は再帰的に適用されますが、この場合 "packages" の下にあ
る全てのパッケージを明示的に指定しなければならないことを心に留めておい
てください: Distutils は "__init__.py" を持つディレクトリをソースツリ
ーから再帰的にさがしたりは *しません* 。)


2.2. 個々のモジュールを列挙する
===============================

小さなモジュール配布物の場合、パッケージを列挙するよりも、全てのモジュ
ールを列挙するほうがよいと思うかもしれません --- 特に、単一のモジュー
ルが "ルートパッケージ" にインストールされる (すなわち、パッケージは全
くない) ような場合がそうです。この最も単純なケースは 簡単な例 で示しま
した; ここではもうちょっと入り組んだ例を示します:

   py_modules = ['mod1', 'pkg.mod2']

ここでは二つのモジュールについて述べていて、一方は "ルート" パッケージ
に入り、他方は "pkg" パッケージに入ります。ここでも、デフォルトのパッ
ケージ/ディレクトリのレイアウトは、二つのモジュールが "mod1.py" と
"pkg/mod2.py" にあり、 "pkg/__init__.py" が存在することを暗示していま
す。また、パッケージ/ディレクトリの対応関係は "package_dir" オプション
でも上書きできます。


2.3. 拡張モジュールについて記述する
===================================

pure Python モジュールを書くより Python 拡張モジュールを書く方がちょっ
とだけ複雑なように、 Distutils での拡張モジュールに関する記述もちょっ
と複雑です。pure モジュールと違い、単にモジュールやパッケージを列挙し
て、Distutils が正しいファイルを見つけてくれると期待するだけでは十分で
はありません; 拡張モジュールの名前、ソースコードファイル (群) 、そして
何らかのコンパイル/リンクに関する必要事項 (include ディレクトリ、リン
クすべきライブラリ、等) を指定しなければなりません。

それらは全て、もう 1 つの "setup()" のオプション引数、 "ext_modules"
オプションを通じて行われます。 "ext_modules" は単なる "Extension" のリ
ストで、それぞれがある 1 つの拡張モジュールを記述しています。配布物に
、 "foo" という名前の "foo.c" に実装がある拡張モジュールが 1 つ含まれ
ているとします。コンパイラ/リンカへのこれ以上の指示が無い場合は、拡張
モジュールの記述は単純です:

   Extension('foo', ['foo.c'])

"Extension" クラスは、 "setup()" によって、 "distutils.core" から
import されます。従って、拡張モジュールが一つだけ入っていて、他には何
も入っていないモジュール配布物を作成するための setup スクリプトは、以
下のようになるでしょう:

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

"Extension" クラス (実質的には、 "Extension" クラスの根底にある
**build_ext** コマンドで実装されている、拡張モジュールをビルドする機構
) は、Python 拡張モジュールをきわめて柔軟に記述できるようなサポートを
提供しています。これについては後の節で説明します。


2.3.1. 拡張モジュールの名前とパッケージ
---------------------------------------

"Extension" コンストラクタの第 1 引数は、常に任意のパッケージ名を含む
拡張モジュールの名前です。例えば、

   Extension('foo', ['src/foo1.c', 'src/foo2.c'])

とすると、拡張モジュールをルートパッケージに置くことになります。一方

   Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])

は、同じ拡張モジュールを "pkg" パッケージの下に置くよう記述しています
。ソースコードファイルと、作成されるオブジェクトコードはどちらの場合で
も同じです; 作成された拡張モジュールがファイルシステム上のどこに置かれ
るか (すなわち Python の名前空間上のどこに置かれるか) が違うにすぎませ
ん。

同じパッケージ内に (または、同じ基底パッケージ下に) いくつもの拡張モジ
ュールがある場合、 "ext_package" キーワード引数を "setup()" に指定しま
す。例えば、

   setup(...,
         ext_package='pkg',
         ext_modules=[Extension('foo', ['foo.c']),
                      Extension('subpkg.bar', ['bar.c'])],
        )

とすると、 "foo.c" をコンパイルして "pkg.foo" にし、 "bar.c" をコンパ
イルして "pkg.subpkg.bar" にします。


2.3.2. 拡張モジュールのソースファイル
-------------------------------------

"Extension" コンストラクタの第 2 引数は、ソースファイルのリストです。
Distutils は現在 C 、 C++ 、 Objective-C 拡張モジュールしかサポートし
ていないため、それらは通常は C/C++/Objective-C ソースファイルです。
(C++ ソースファイルと判別できるように適切な拡張子を使用するようにして
ください: ".cc" と ".cpp" が Unix と Windows のコンパイラの両方が認識
できるようです。)

ただし、 SWIG インターフェース (".i") ファイルはリストに含められます;
**build_ext** コマンドは、 SWIG で書かれた拡張パッケージをどう扱えばよ
いか心得ています: **build_ext** は、インターフェースファイルを SWIG に
かけ、得られた C/C++ ファイルをコンパイルして拡張モジュールを生成しま
す。

この警告にかかわらず、現在次のようにしてSWIGに対してオプションを渡すこ
とができます:

   setup(...,
         ext_modules=[Extension('_foo', ['foo.i'],
                                swig_opts=['-modern', '-I../include'])],
         py_modules=['foo'],
        )

もしくは、次のようにコマンドラインからオプションを渡すこともできます:

   > python setup.py build_ext --swig-opts="-modern -I../include"

プラットフォームによっては、コンパイラで処理され、拡張モジュールに取り
込まれるような非ソースコードファイルを含められます。非ソースコードファ
イルとは、現状では Visual C++向けの Windows メッセージテキスト (".mc")
ファイルや、リソース定義 (".rc") ファイルを指します。これらのファイル
はバイナリリソース (".res") ファイルにコンパイルされ、実行ファイルにリ
ンクされます。


2.3.3. プリプロセッサオプション
-------------------------------

検索するインクルードディレクトリやプリプロセッサマクロの
define/undefine を指定する必要がある場合、 "Extension" の 3 つのオプシ
ョン引数が役に立ちます: "include_dirs" 、 "define_macros" 、
"undef_macros" です。

例えば、拡張モジュールが配布物ルート下の "include" ディレクトリにある
ヘッダファイルを必要とするときには、 "include_dirs" オプションを使いま
す:

   Extension('foo', ['foo.c'], include_dirs=['include'])

ここには絶対パスも指定できます; 例えば、自分の拡張モジュールが、
"/usr" の下にX11R6 をインストールした Unix システムだけでビルドされる
と知っていれば、このように書けます

   Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])

自分のコードを配布する際には、このような可搬性のない使い方は避けるべき
です: おそらく、C のコードを次のように書いたほうがましでしょう

   #include <X11/Xlib.h>

他の Python 拡張モジュール由来のヘッダを include する必要があるなら、
Distutils の **install_header** コマンドが一貫した方法でヘッダファイル
をインストールするという事実を活用できます。例えば、 Numerical Python
のヘッダファイルは、 (標準的な Unix がインストールされた環境では)
"/usr/local/include/python1.5/Numerical" にインストールされます。 (実
際の場所は、プラットフォームやどの Python をインストールしたかで異なり
ます。) Python の include ディレクトリ --- 今の例では
"/usr/local/include/python1.5" --- は、 Python 拡張モジュールをビルド
する際に常にヘッダファイル検索パスに取り込まれるので、 C コードを書く
上でもっともよいアプローチは、以下のようなものとなります

   #include <Numerical/arrayobject.h>

"Numerical" インクルードディレクトリ自体をヘッダ検索パスに置きたいのな
ら、このディレクトリを Distutils の "distutils.sysconfig" モジュールを
使って見つけさせられます:

   from distutils.sysconfig import get_python_inc
   incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
   setup(...,
         Extension(..., include_dirs=[incdir]),
         )

この書き方も可搬性はあります --- プラットフォームに関わらず、どんな
Python がインストールされていても動作します --- が、単に実践的な書き方
で C コードを書く方が簡単でしょう。

"define_macros" および "undef_macros" オプションを使って、プリプロセッ
サマクロを定義 (define) したり、定義解除 (undefine) したりもできます。
"define_macros" はタプル "(name, value)" からなるリストを引数にとりま
す。 "name" は定義したいマクロの名前 (文字列) で、 "value" はその値で
す: "value" は文字列か "None" になります。(マクロ "FOO" を "None" にす
ると、C ソースコード内で "#define FOO" と書いたのと同じになります: こ
う書くと、ほとんどのコンパイラは "FOO" を文字列 "1" に設定します。)
"undef_macros" には、定義解除したいマクロ名からなるリストを指定します
。

例えば:

   Extension(...,
             define_macros=[('NDEBUG', '1'),
                            ('HAVE_STRFTIME', None)],
             undef_macros=['HAVE_FOO', 'HAVE_BAR'])

は、全ての C ソースコードファイルの先頭に、以下のマクロがあるのと同じ
になります:

   #define NDEBUG 1
   #define HAVE_STRFTIME
   #undef HAVE_FOO
   #undef HAVE_BAR


2.3.4. ライブラリオプション
---------------------------

拡張モジュールをビルドする際にリンクするライブラリや、ライブラリを検索
するディレクトリも指定できます。 "libraries" はリンクするライブラリの
リストで、 "library_dirs" はリンク時にライブラリを検索するディレクトリ
のリストです。また、 "runtime_library_dirs" は、実行時に共有ライブラリ
(動的にロードされるライブラリ) を検索するディレクトリのリストです。

例えば、ビルド対象システムの標準ライブラリ検索パスにあることが分かって
いるライブラリをリンクする時には、以下のようにします

   Extension(...,
             libraries=['gdbm', 'readline'])

非標準のパス上にあるライブラリをリンクしたいなら、その場所を
"library_dirs" に入れておかなければなりません:

   Extension(...,
             library_dirs=['/usr/X11R6/lib'],
             libraries=['X11', 'Xt'])

(繰り返しになりますが、この手の可搬性のない書き方は、コードを配布する
のが目的なら避けるべきです。)


2.3.5. その他のオプション
-------------------------

他にもいくつかオプションがあり、特殊な状況を扱うために使います。

"optional" オプションはブール型で、真の場合は拡張モジュールのビルドに
失敗したときにビルドプロセス自体を停止せず、単にその拡張モジュールのイ
ンストールをしません。

"extra_objects" オプションには、リンカに渡すオブジェクトファイルのリス
トを指定します。ファイル名には拡張子をつけてはならず、コンパイラで使わ
れているデフォルトの拡張子が使われます。

"extra_compile_args" および "extra_link_args" には、それぞれコンパイラ
とリンカに渡す追加のコマンドライン引数を指定します。

"export_symbols" は Windows でのみ意味があります。このオプションには、
公開 (export) する (関数や変数の) シンボルのリストを入れられます。コン
パイルして拡張モジュールをビルドする際には、このオプションは不要です:
Distutils は公開するシンボルを自動的に "initmodule" に渡すからです。

"depends" オプションは、拡張モジュールが依存している(例: ヘッダーファ
イルなどの) ファイルのリストです。このファイルのいずれかが前回のビルド
から変更された時、ビルドコマンドはこのソースファイルをコンパイルしてリ
ビルドします。


2.4. パッケージと配布物の関係
=============================

配布物はパッケージと3種類の方法で関係します:

1. パッケージかモジュールを要求する。

2. パッケージかモジュールを提供する。

3. パッケージかモジュールを廃止する。

これらの関係は、 "distutils.core.setup()" 関数のキーワード引数を利用し
て指定することができます。

他のPythonモジュールやパッケージに対する依存は、 "setup()" の
*requires* キーワード引数で指定できます。引数の値は文字列のリストでな
ければなりません。各文字列は、必要とするパッケージと、オプションとして
パッケージのバージョンを指定します。

あるモジュールかパッケージの任意のバージョンが必要な場合、指定する文字
列はモジュール名かパッケージ名になります。例えば、 "'mymodule'" や
"'xml.parsers.expat'" を含みます。

特定のバージョンが必要な場合、修飾子(qualifier)の列を加えることができ
ます。各修飾子は、比較演算子とバージョン番号からなります。利用できる比
較演算子は:

   <    >    ==
   <=   >=   !=

これらの修飾子はカンマ(空白文字を入れても良いです)で区切って複数並べる
ことができます。その場合、全ての修飾子が適合する必要があります; 評価す
る時に論理ANDでつなげられます。

いくつかの例を見てみましょう:

+---------------------------+------------------------------------------------+
| require式                 | 説明                                           |
|===========================|================================================|
| "==1.0"                   | version "1.0" のみが適合します                 |
+---------------------------+------------------------------------------------+
| ">1.0, !=1.5.1, <2.0"     | "1.5.1" を除いて、 "1.0" より後ろで "2.0" より |
|                           | 前の全てのバージョンに適 合します。            |
+---------------------------+------------------------------------------------+

これで、依存を指定することができました。同じように、この配布物が他の配
布物に必要とされる何を提供するのかを指定する必要があります。これは、
"setup()" の *provides* キーワード引数によって指定できます。この引数の
値は文字列のリストで、各要素はPythonモジュールかパッケージの名前です。
バージョンを指定することもできます。もしバージョンが指定されなかった場
合、配布物のバージョン番号が利用されます。

いくつかの例です:

+-----------------------+------------------------------------------------+
| provide 式            | 説明                                           |
|=======================|================================================|
| "mypkg"               | "mypkg" を提供します。バージョンは配布物のもの |
|                       | を使います。                                   |
+-----------------------+------------------------------------------------+
| "mypkg (1.1)"         | "mypkg" version 1.1 を提供します。配布物のバー |
|                       | ジョン番号は気にしません                       |
+-----------------------+------------------------------------------------+

パッケージは *obsoletes* キーワードを利用することで、他のパッケージを
廃止することを宣言することもできます。この値は *requires* キーワードと
似ています: モジュールやパッケージを指定する文字列のリストです。各文字
列は、モジュールかパッケージの名前と、オプションとして一つ以上のバージ
ョン指定から構成されています。バージョン指定は、モジュールやパッケージ
の名前のうしろに、丸括弧 (parentheses) でかこわれています。

指定されたバージョンは、その配布物によって廃止されるバージョンを示して
います。バージョン指定が存在しない場合は、指定された名前のモジュールま
たはパッケージの全てが廃止されたと解釈されます。


2.5. スクリプトをインストールする
=================================

ここまでは、スクリプトから import され、それ自体では実行されないような
pure Python モジュールおよび非 pure Python モジュールについて扱ってき
ました。

スクリプトとは、Python ソースコードを含むファイルで、コマンドラインか
ら実行できるよう作られているものです。スクリプトは Distutils に複雑な
ことを一切させません。唯一の気の利いた機能は、スクリプトの最初の行が
"#!" で始まっていて、 "python" という単語が入っていた場合、Distutils
は最初の行を現在使っているインタプリタを参照するよう置き換えます。デフ
ォルトでは現在使っているインタプリタと置換しますが、オプション "--
executable" (または "-e") を指定することで、明示的にインタプリタのパス
を指定して上書きすることができます。

"scripts" オプションには、単に上で述べた方法で取り扱うべきファイルのリ
ストを指定するだけです。PyXML の setup スクリプトを例に示します:

   setup(...,
         scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
         )

バージョン 3.1 で変更: テンプレートが提供されない時、全てのスクリプト
が "MANIFEST" ファイルに追加されるようになりました。 配布するファイル
を指定する を参照してください


2.6. パッケージデータをインストールする
=======================================

しばしばパッケージに追加のファイルをインストールする必要があります。こ
のファイルは、パッケージの実装に強く関連したデータや、そのパッケージを
使うプログラマーが必要とするドキュメントなどです。これらのファイルを *
パッケージデータ* と呼びます。

パッケージデータは関数 "setup()" にキーワード引数 "package_data" を与
えることで追加できます。この値はパッケージ名から、パッケージへコピーさ
れる相対パス名リストへのマップである必要があります。それぞれのパスは対
応するパッケージが含まれるディレクトリ(もし適切なら "package_dir" のマ
ッピングが利用されます)からの相対パスとして扱われます。つまり、ファイ
ルはソースディレクトリ中にパッケージの一部として存在すると仮定されてい
ます。この値にはグロブパターンを含むことができます。

パス名にはディレクトリ部分を含むことができます。必要なディレクトリはイ
ンストール時に作成されます。

たとえば、パッケージがいくつかのデータファイルを含むサブディレクトリを
含んでいる場合、ソースツリーでは以下のように配置できます:

   setup.py
   src/
       mypkg/
           __init__.py
           module.py
           data/
               tables.dat
               spoons.dat
               forks.dat

対応する "setup()" 呼び出しは以下のようになります:

   setup(...,
         packages=['mypkg'],
         package_dir={'mypkg': 'src/mypkg'},
         package_data={'mypkg': ['data/*.dat']},
         )

バージョン 3.1 で変更: テンプレートが提供されない時、全ての
"package_data" にマッチするファイルが "MANIFEST" ファイルに追加される
ようになりました。 配布するファイルを指定する を参照してください


2.7. 追加のファイルをインストールする
=====================================

"data_files" オプションを使うと、モジュール配布物で必要な追加のファイ
ル: 設定ファイル、メッセージカタログ、データファイル、その他これまで述
べてきたカテゴリに収まらない全てのファイルを指定できます。

"data_files" には、(*directory*, *files*) のペアを以下のように指定しま
す:

   setup(...,
         data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
                     ('config', ['cfg/data.cfg'])],
        )

シーケンス中のそれぞれの (*directory*, *files*) ペアは、インストール先
ディレクトリとそこにインストールするファイルのリストを指定します。

*files* リスト中の各ファイル名はパッケージのソースディストリビューショ
ンの最上位にある "setup.py" スクリプトからの相対パスとして解釈されます
。データファイルがインストールされるディレクトリは指定できますが、デー
タファイルの名前を変更することはできないことに注意してください。

*directory* は相対パスである必要があり、インストールプレフィックス (シ
ステムインストールの場合は Python の "sys.prefix"; ユーザーインストー
ルの場合は "site.USER_BASE") からの相対パスと解釈されます。 Distutils
は *directory* に絶対パスを指定することができますが、この方法は wheel
パッケージング形式と互換性がないため推奨されません。 *files* のディレ
クトリ情報はインストール先の決定には使われません; ファイル名だけが使わ
れます。

"data_files" オプションは、ターゲットディレクトリを指定せずに、単にフ
ァイルの列を指定できます。しかし、このやり方は推奨されておらず、指定す
ると **install** コマンドが警告を出力します。ターゲットディレクトリに
データファイルを直接インストールしたいなら、ディレクトリ名として空文字
列を指定してください。

バージョン 3.1 で変更: テンプレートが提供されない時、全ての
"data_files" にマッチするファイルが "MANIFEST" ファイルに追加されるよ
うになりました。 配布するファイルを指定する を参照してください


2.8. 追加のメタデータ
=====================

setup スクリプトには、名前やバージョンにとどまらず、その他のメタデータ
を含められます。以下のような情報を含められます:

+------------------------+-----------------------------+-------------------+----------+
| メタデータ             | 説明                        | 値                | 注釈     |
|========================|=============================|===================|==========|
| "name"                 | パッケージ名                | 短い文字列        | (1)      |
+------------------------+-----------------------------+-------------------+----------+
| "version"              | リリースのバージョン        | 短い文字列        | (1)(2)   |
+------------------------+-----------------------------+-------------------+----------+
| "author"               | パッケージ作者名            | 短い文字列        | (3)      |
+------------------------+-----------------------------+-------------------+----------+
| "author_email"         | パッケージ作者の電子メール  | 電子メールアドレ  | (3)      |
|                        | アドレス                    | ス                |          |
+------------------------+-----------------------------+-------------------+----------+
| "maintainer"           | パッケージメンテナンス担当  | 短い文字列        | (3)      |
|                        | 者の名前                    |                   |          |
+------------------------+-----------------------------+-------------------+----------+
| "maintainer_email"     | パッケージメンテナンス担当  | 電子メールアドレ  | (3)      |
|                        | 者の電子メールアドレス      | ス                |          |
+------------------------+-----------------------------+-------------------+----------+
| "url"                  | パッケージのホームページ    | URL               | (1)      |
+------------------------+-----------------------------+-------------------+----------+
| "description"          | パッケージについての簡潔な  | 短い文字列        |          |
|                        | 概要説明                    |                   |          |
+------------------------+-----------------------------+-------------------+----------+
| "long_description"     | パッケージについての詳細な  | 長い文字列        | (4)      |
|                        | 説明                        |                   |          |
+------------------------+-----------------------------+-------------------+----------+
| "download_url"         | パッケージをダウンロードで  | URL               |          |
|                        | きる場所                    |                   |          |
+------------------------+-----------------------------+-------------------+----------+
| "classifiers"          | 分類語のリスト              | 文字列からなるリ  | (6)(7)   |
|                        |                             | スト              |          |
+------------------------+-----------------------------+-------------------+----------+
| "platforms"            | プラットフォームのリスト    | 文字列からなるリ  | (6)(8)   |
|                        |                             | スト              |          |
+------------------------+-----------------------------+-------------------+----------+
| "keywords"             | キーワードのリスト          | 文字列からなるリ  | (6)(8)   |
|                        |                             | スト              |          |
+------------------------+-----------------------------+-------------------+----------+
| "license"              | パッケージのライセンス      | 短い文字列        | (5)      |
+------------------------+-----------------------------+-------------------+----------+

注釈:

1. 必須のフィールドです。

2. バージョン番号は *major.minor[.patch[.sub]]* の形式をとるよう奨めま
   す。

3. 作者かメンテナのどちらかは必ず区別してください。メンテナが与えられ
   ると、distutils は "PKG-INFO" に作者としてリストします。

4. "long_description" フィールドは、パッケージを PyPI で公開する際にプ
   ロジェクトページ作成のために使われます。

5. "license" フィールドは、ライセンスが "License" Trove 分類から選ばれ
   たのではない場合にパッケージをカバーするライセンスを示すテキストで
   す。 "Classifier" フィールドを参照してください。お気づきの通り、廃
   止された "licence" というオプションがあり、未だに "license" のエイ
   リアスとして働いています。

6. このフィールドはリストでなければなりません。

7. 有効な分類語のリストは PyPI を参照してください。

8. 後方互換性を保つため、このフィールドはリストに加えて文字列も受け付
   けます。コンマ区切りの文字列``'foo, bar'>>``<<を与えると、文字列の
   リスト``['foo', 'bar']``に変換されます。それ以外の場合、1つの文字列
   だけを含むリストに変換されます。

「短い文字列」
   200 文字以内の一行のテキスト。

「長い文字列」
   複数行からなり、ReStructuredText 形式で書かれたプレーンテキスト
   (http://docutils.sourceforge.net/ を参照してください)。

「文字列のリスト」
   下記を参照してください。

バージョン情報のコード化は、それ自体が一つのアートです。 Python のパッ
ケージは一般的に、 *major.minor[.patch][sub]* というバージョン表記に従
います。メジャー (major) 番号は最初は 0 で、これはソフトウェアが実験的
リリースにあることを示します。メジャー番号は、パッケージが主要な開発目
標を達成したとき、それを示すために加算されてゆきます。マイナー (minor)
番号は、パッケージに重要な新機能が追加されたときに加算されてゆきます。
パッチ (patch) 番号は、バグフィクス版のリリースが作成されたときに加算
されます。末尾にバージョン情報が追加され、サブリリースを示すこともあり
ます。これは "a1,a2,...,aN" (アルファリリースの場合で、機能や API が変
更されているとき)、 "b1,b2,...,bN" (ベータリリースの場合で、バグフィク
スのみのとき) 、そして "pr1,pr2,...,prN"  (プレリリースの最終段階で、
リリーステストのとき) になります。以下に例を示します:

0.1.0
   パッケージの最初の実験的なリリース

1.0.1a2
   1.0 の最初のパッチバージョンに対する、2 回目のアルファリリース

"classifiers" はリストの中で指定しなければなりません:

   setup(...,
         classifiers=[
             'Development Status :: 4 - Beta',
             'Environment :: Console',
             'Environment :: Web Environment',
             'Intended Audience :: End Users/Desktop',
             'Intended Audience :: Developers',
             'Intended Audience :: System Administrators',
             'License :: OSI Approved :: Python Software Foundation License',
             'Operating System :: MacOS :: MacOS X',
             'Operating System :: Microsoft :: Windows',
             'Operating System :: POSIX',
             'Programming Language :: Python',
             'Topic :: Communications :: Email',
             'Topic :: Office/Business',
             'Topic :: Software Development :: Bug Tracking',
             ],
         )

バージョン 3.7 で変更: "setup" は``classifiers``, "keywords",
>>``<<platforms``のいずれかのフィールドに文字列でもリストでもない値が
指定されたときに、警告を出すようになりました。


2.9. setup スクリプトをデバッグする
===================================

setup スクリプトのどこかがまずいと、開発者の思い通りに動作してくれませ
ん。

Distutils は setup 実行時の全ての例外を捉えて、簡単なエラーメッセージ
を出力してからスクリプトを終了します。このような仕様にしているのは、
Python にあまり詳しくない管理者がパッケージをインストールする際に混乱
しなくてすむようにするためです。もし Distutils のはらわた深くからトレ
ースバックした長大なメッセージを見たら、管理者はきっと Python のインス
トール自体がおかしくなっているのだと勘違いして、トレースバックを最後ま
で読み進んで実はファイルパーミッションの問題だったと気づいたりはしない
でしょう。

しかし逆に、この仕様は開発者にとってはうまくいかない理由を見つける役に
は立ちません。そこで、 "DISTUTILS_DEBUG" 環境変数を空文字以外の何らか
の値に設定しておけば、 Distutils が何を実行しているか詳しい情報を出力
し、例外が発生した場合には完全なトレースバックをダンプし、(C コンパイ
ラのような) 外部プログラムが失敗した時はコマンドライン全体を表示するよ
うにできます。
