7. Distutilsの拡張
******************

注釈:

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

Distutilsは様々な方法で拡張できます。ほとんどの拡張は新規のコマンドと
いう形をとるか、既存のコマンドを置換します。例えば、新しいコマンドはプ
ラットフォーム特有の新しいパッケージ形式をサポートするために書かれてい
るかもしませんし、既存のコマンドを置換するものは既存コマンドでのパッケ
ージ処理の詳細を変更するでしょう。

ほとんどのdistutilsの拡張は、既存コマンドの動作を修正したい "setup.py"
スクリプト中で行われます。その多くは、パッケージ中にコピーすべきファイ
ルとして、 ".py" ファイル以外のいくつかのファイル拡張子を単に追加する
ものです。

ほとんどのdistutilsのコマンド実装は "distutils.cmd.Command" クラスのサ
ブクラスとして実装されています。新しいコマンドは "Command" を直接継承
し、置換するコマンドでは置換対象のコマンドのサブクラスにすることで
"Command" を間接的に継承します。コマンドは "Command" から派生したもの
である必要があります。


7.1. 新しいコマンドの統合
=========================

新しいコマンド実装をdistutilsに統合するにはいくつかの方法があります。
一番難しい方法は新機能をdistutils本体に取り込むように働きかけ、そのサ
ポートを提供するPythonのバージョンが出ることを待つ(そして要求する)こと
です。これは様々な理由で本当に難しいことです。

もっとも一般的な、そしておそらくほとんどの場合にもっとも妥当な方法は、
新しい実装をあなたの "setup.py" スクリプトに取り込み、
"distutils.core.setup()" 関数でそれらを使うようにすることです:

   from distutils.command.build_py import build_py as _build_py
   from distutils.core import setup

   class build_py(_build_py):
       """Specialized Python source builder."""

       # implement whatever needs to be different...

   setup(cmdclass={'build_py': build_py},
         ...)

このアプローチは、新実装をある特定のパッケージで利用したい時、そのパッ
ケージに興味をもつ人全員がコマンドの新実装を必要とする時にもっとも価値
があります。

Python 2.4から、インストールされたPythonを変更せずに、既存の
"setup.py" スクリプトをサポートするための3つめの選択肢が利用できるよう
になりました。これは追加のパッケージングシステムのサポートを追加するサ
ードパーティ拡張を提供することを想定していますが、これらのコマンドは
distutilsが利用されている何にでも利用可能です。新しい設定オプション
"command_packages" (コマンドラインオプション "--command-packages") は
、コマンド実装モジュールを検索する追加のパッケージを指定するために利用
できます。 distutilsの全てのオプションと同様に、このオプションもコマン
ドラインまたは設定ファイルで指定できます。このオプションは設定ファイル
中では "[global]" セクションか、コマンドラインのコマンドより前でだけ設
定できます。設定ファイル中で指定する場合、コマンドラインで上書きするこ
とができます。空文字列を指定するとデフォルト値が使われます。これはパッ
ケージと一緒に提供する設定ファイルでは指定しないでください。

この新オプションによってコマンド実装を探すためのパッケージをいくつでも
追加することができます。複数のパッケージ名はコンマで区切って指定します
。指定がなければ、検索は "distutils.command" パッケージのみで行われま
す。ただし "setup.py" がオプション "--command-packages
distcmds,buildcmds" で実行されている場合には、パッケージは
"distutils.command" 、 "distcmds" 、そして "buildcmds" を、この順番で
検索します。新コマンドはコマンドと同じ名前のモジュールに、コマンドと同
じ名前のクラスで実装されていると想定しています。上のコマドラインオプシ
ョンの例では、コマンド **bdist_openpkg** は、
"distcmds.bdist_openpkg.bdist_openpkg" か、
"buildcmds.bdist_openpkg.bdist_openpkg" で実装されるかもしれません。


7.2. 配布物の種類を追加する
===========================

配布物 ("dist/" ディレクトリの中のファイル) を作成するコマンドは、
**upload** がその配布物をPyPIにアップロードできるように、 "(command,
filename)" のペアを "self.distribution.dist_files" に追加する必要があ
ります。ペア中の *filename* はパスに関する情報を持たず、単にファイル名
だけを持ちます。 dry-run モードでも、何が作成されたかを示すために、同
じペアが必要になります。
