Distutilsを使うためにインストールする必要がある唯一のモジュールが distutils.core モジュールです。 setup() 関数 (セットアップスクリプトから呼び出されます)を提供します。間接的に distutils.dist.Distribution クラスと distutils.cmd.Command クラスを提供します。
全てを実行する基本的な関数で、Distutilsでできるほとんどのことを実行します。
setup関数はたくさんの引数をとります。以下のテーブルにまとめます。
引数名 | 値 | 型 |
---|---|---|
name | パッケージの名前 | 文字列 |
version | パッケージのバージョン番号 | distutils.version を参照してください |
description | 1行で書いたパッケージ解説 | 文字列 |
long_description | パッケージの長い解説 | 文字列 |
author | パッケージ作者の名前 | 文字列 |
author_email | パッケージ作者のemailアドレス | 文字列 |
maintainer | 現在のメンテナの名前(パッケージ作者と異なる場合) | 文字列 |
maintainer_email | 現在のメンテナのemailアドレス(パッケージ作者と異なる場合) | |
url | パッケージのURL(ホームページ) | URL |
download_url | パッケージダウンロード用URL | URL |
packages | distutilsが操作するPythonパッケージのリスト | 文字列のリスト |
py_modules | distutilsが操作するPythonモジュールのリスト | 文字列のリスト |
scripts | ビルドおよびインストールする単体スクリプトファイルのリスト | 文字列のリスト |
ext_modules | ビルドする拡張モジュール | distutils.core.Extension インスタンスのリスト |
classifiers | パッケージのカテゴリのリスト | 利用可能なカテゴリ一覧は http://cheeseshop.python.org/pypi?:action=list_classifiers にあります。 |
distclass | 使用する Distribution クラス | distutils.core.Distribution のサブクラス |
script_name | setup.pyスクリプトの名前 - デフォルトでは sys.argv[0] | 文字列 |
script_args | セットアップスクリプトの引数 | 文字列のリスト |
options | セットアップスクリプトのデフォルト引数 | 文字列 |
license | パッケージのライセンス | 文字列 |
keywords | 説明用メタデータ。 PEP 314 を参照してください | |
platforms | ||
cmdclass | コマンド名から Command サブクラスへのマッピング | 辞書 |
data_files | インストールするデータファイルのリスト | リスト |
package_dir | パッケージからディレクトリ名へのマッピング | 辞書 |
制御された環境でセットアップスクリプトを実行し、いろいろなものを操作する distutils.dist.Distribution クラスのインスタンスを返します。これはディストリビューションのメタデータ(キーワード引数 script として関数 setup() に渡される)を参照したり、設定ファイルやコマンドラインの内容を調べる時に便利です。
script_name は execfile() で実行されるファイルです。 sys.argv[0] は、呼び出しのために script_name と置換されます。 script_args は文字列のリストです。もし提供されていた場合、 sys.argv[1:] は、呼び出しのために script_args で置換されます。
stop_after はいつ動作を停止するか関数 setup() に伝えます。とりうる値は:
値 | 説明 |
---|---|
init | Distribution インスタンスを作成し、キーワード引数を setup() に渡したあとに停止する。 |
config | 設定ファイルをパーズしたあと停止する(そしてそのデータは Distribution インスタンスに保存される)。 |
commandline | コマンドライン (sys.argv[1:] または script_args) がパーズされたあとに停止する (そしてそのデータは Distribution インスタンスに保存される)。 |
run | 全てのコマンドを実行したあとに停止する(関数 setup() を通常の方法で呼び出した場合と同じ)。デフォルト値。 |
これに加えて、 distutils.core モジュールは他のモジュールにあるいくつかのクラスを公開しています。
それぞれの簡単な説明を以下に記します。完全な説明についてはそれぞれのモジュールをごらんください。
Extension クラスは、セットアップスクリプト中で C または C++拡張モジュールを表します。コンストラクタで以下のキーワード引数をとります。
引数名 | 値 | 型 |
---|---|---|
name | 拡張のフルネーム(パッケージを含む) — ファイル名やパス名では なく 、Pythonのピリオド区切りの名前 | 文字列 |
sources | ソースファイル名のリスト。配布物ルートディレクトリ (setupスクリプトのある場所) からの相対パス、プラットフォーム独立のため Unix 形式(スラッシュで区切る)で記述します。ソースファイルは C, C++, SWIG (.i)、特定プラットフォーム用のリソースファイル、その他 build_ext コマンドがソースファイルだと認識するどの形式でもありえます。 | 文字列 |
include_dirs | C/C++ヘッダファイルを検索するディレクトリのリスト(プラットフォーム独立のため Unix 形式で記述する) | 文字列 |
define_macros | 定義するマクロのリスト; それぞれのマクロは2要素のタプル (name, value) で定義されます。 value には定義しようとしている文字列、または内容なしで定義する場合は None (ソースコード中で #define FOO と書く、または Unix Cコンパイラのコマンドラインで -DFOO を指定するのと等価です)を指定します。 | (文字列, 文字列) または (文字列, None) のタプル |
undef_macros | 定義を消すマクロのリスト | 文字列 |
library_dirs | リンク時にC/C++ライブラリを検索するディレクトリのリスト | 文字列 |
libraries | リンクするライブラリ名のリスト (ファイル名やパスではない) | 文字列 |
runtime_library_dirs | 実行時(shared extensionでは、拡張が読み込まれる時)に C/C++ライブラリを探索するディレクトリのリスト | 文字列 |
extra_objects | 追加でリンクするファイル(‘sources’に対応するコードが含まれていないファイル、バイナリ形式のリソースファイルなど)のリスト | 文字列 |
extra_compile_args | ‘sources’のソースをコンパイルする時に追加するプラットフォーム特有またはコンパイラ特有の情報コマンドラインを利用できるプラットホームとコンパイラでは、これは通常コマンドライン引数のリストですが、他のプラットホームでも、それは何かに使えます。 | 文字列 |
extra_link_args | オブジェクトファイルをリンクして拡張(または新しいPythonインタプリタ)を作る時に追加するプラットフォーム特有またはコンパイラ特有の情報 ‘extra_compile_args’に似た実装です。 | 文字列 |
export_symbols | shared extensionからエクスポートされるシンボルのリスト。全てのプラットフォームでは使われず、 Python拡張(典型的には init + extension_name という1つのシンボルだけエクスポートする)に一般的に必要なものでもない。 | 文字列 |
depends | 拡張が依存するファイルのリスト | 文字列 |
language | 拡張の言語 (例: 'c', 'c++', 'objc')。指定しなければソースの拡張子で検出される。 | 文字列 |
Distribution はPythonソフトウェアパッケージをどのようにビルド、インストール、パッケージするかを定義する。
Distribution のコンストラクタが取りうるキーワード引数のリストに関しては、 setup() 関数を見てください。 setup() は Distribution のインスタンスを作ります。
このモジュールは CCompiler クラスの抽象ベースクラスを提供します。 CCompiler のインスタンスはプロジェクトにおける全てのコンパイルおよびリンクに使われます。コンパイラのオプションを設定するためのメソッドが提供されます — マクロ定義、includeディレクトリ、リンクパス、ライブラリなど。
このモジュールは以下の関数を提供します。
ライブラリを探索するディレクトリ、特定のライブラリとのリンクをするためのリンカオプションを生成します。 libraries と library_dirs はそれぞれライブラリ名(ファイル名ではありません!)のリストと、探索ディレクトリのリストです。 compilerで利用できるコマンドラインオプションのリスト(指定されたフォーマット文字列に依存します)を返します。
Cプリプロセッサオプション(-D, -U, -I)を生成します。これらは少なくとも2つのコンパイラで利用可能です。典型的な Unix のコンパイラと、VisualC++です。 macros は1または2要素のタプルで (name,) は name マクロの削除 (-U)を意味し、 (name,value) は name マクロを value として定義(-D)します。 include_dirs はディレクトリ名のリストで、ヘッダファイルのサーチパスに追加されます(-I)。 Unix のコンパイラと、Visual C++で利用できるコマンドラインオプションのリストを返します。
指定されたプラットフォームのデフォルトコンパイラを返します。
問い合わせの osname はPython標準のOS名(os.name で返されるもの)のひとつであるべきで、 platform は sys.platform で返される共通の値です。
パラメータが指定されていない場合のデフォルト値は os.name と sys.platform です。
指定されたプラットフォーム/コンパイラの組み合わせ向けに、 CCompilerサブクラスのインスタンスを生成するファクトリ関数です。 plat のデフォルト値は os.name (例: 'posix', 'nt'), compiler)、 compiler のデフォルト値はプラトフォームのデフォルトコンパイラです。現在は 'posix' と 'nt' だけがサポートされています、デフォルトのコンパイラは “traditional Unix interface” (UnixCCompiler クラス) と、 Visual C++ (MSVCCompiler クラス) です。 WindowsでUnixコンパイラオブジェクトを要求することも、UnixでMicrosoft コンパイラオブジェクトを要求することも可能です。 compiler 引数を与えると plat は無視されます。
利用可能なコンパイラのリストを表示します(build, build_ext, build_clib の、 --help-compiler オプションで使われます。)
抽象ベースクラス CCompiler は実際のコンパイラクラスで実装される必要のあるインタフェースを定義しています。このクラスはコンパイラクラスで利用されるユーティリティメソッドも定義しています。
コンパイラ抽象クラスの基本的な前提は、各インスタンスはあるプロジェクトをビルドするときの全コンパイル/リンクで利用できるということです。そこで、コンパイルとリンクステップで共通する属性 — インクルードディレクトリ、マクロ定義、リンクするライブラリなど — はコンパイラインスタンスの属性になります。どのように各ファイルが扱われるかを変更できるように、ほとんどの属性はコンパイルごと、またはリンクごとに与えることができます。
各サブクラスのコンストラクタは Compiler クラスのインスタンスを作ります。フラグは verbose (冗長な出力を表示します)、 dry_run (実際にはそのステップを実行しません)、そして force (依存関係を無視して全て再ビルドします)です。これらのフラグは全てデフォルト値が 0 (無効)になっています。 CCompiler またはサブクラスを直接インスタンス化したくない場合には、かわりに distutils.CCompiler.new_compiler() ファクトリ関数を利用してください。
以下のメソッドで、Compilerクラスのインスタンスが使うコンパイラオプションを手動で変更できます。
dir をヘッダファイル探索ディレクトリのリストに追加します。コンパイラは add_include_dir() を呼び出した順にディレクトリを探索するよう指定されます。
探索されるディレクトリのリストを dirs (文字列のリスト)に設定します。先に実行された add_include_dir() は上書きされます。後で実行する add_include_dir() は set_include_dirs() のリストにディレクトリを追加します。これはコンパイラがデフォルトで探索する標準インクルードディレクトリには影響しません。
libname をコンパイラオブジェクトによるリンク時に使われるライブラリのリストに追加します。 libname はライブラリを含むファイル名ではなく、ライブラリそのものの名前です: 実際のファイル名はリンカ、コンパイラ、またはコンパイラクラス(プラットフォームに依存します)から推測されます。
リンカは add_library() と set_library() で渡された順にライブラリをリンクしようとします。ライブラリ名が重なることは問題ありません。リンカは指定された回数だけライブラリとリンクしようとします。
コンパイラオブジェクトによるリンク時に使われるライブラリのリストを libnames (文字列のリスト)に設定します。これはリンカがデフォルトでリンクする標準のシステムライブラリには影響しません。
add_library() と set_libraries() で指定されたライブラリを探索するディレクトリのリストに dir を追加します。リンカは add_library_dir() と set_library_dirs() で指定された順にディレクトリを探索されます。
ライブラリを探索するディレクトリを dirs (文字列のリスト)に設定します。これはリンカがデフォルトで探索する標準ライブラリ探索パスには影響しません。
実行時に共有ライブラリを探索するディレクトリのリストに dir を追加します。
実行時に共有ライブラリを探索するディレクトリのリストを dir に設定します。これはランタイムリンカがデフォルトで利用する標準探索パスには影響しません。
このコンパイラオブジェクトで実行される全てのコンパイルで利用されるプリプロセッサのマクロを定義します。省略可能なパラメータ value は文字列であるべきです。省略された場合は、マクロは特定の値をとらずに定義され、具体的な結果は利用されるコンパイラに依存します。 (XXX 本当に? これについてANSIで言及されている?)
このコンパイラオブジェクトで実行される全てのコンパイルで利用されるプリプロセッサのマクロ定義を消します。同じマクロを define_macro() で定義し、 undefine_macro() で定義を削除した場合、後で呼び出されたものが優先される(複数の再定義と削除を含みます)。もしコンパイルごと(すなわち compile() の呼び出しごと)にマクロが再定義/削除される場合も後で呼び出されたものが優先されます。
このコンパイラオブジェクトによる全てのリンクで利用されるオブジェクトファイル(または類似のライブラリファイルや “リソースコンパイラ”の出力)のリストに object を追加します。
このコンパイラオブジェクトによる全てのリンクで利用されるオブジェクトファイル(または類似のもの)のリストを objects に設定します。これはリンカがデフォルト利用する標準オブジェクトファイル(システムライブラリなど)には影響しません。
以下のメソッドはコンパイラオプションの自動検出を実装しており、 GNU autoconf に似たいくつかの機能を提供します。
与えられたファイルまたはファイルのリストの言語を検出します。インスタンス属性 language_map (辞書)と、 language_order (リスト)を仕事に使います。
指定されたディレクトリのリストから、スタティックまたは共有ライブラリファイル lib を探し、そのファイルのフルパスを返します。もし debug が真なら、(現在のプラットフォームで意味があれば)デバッグ版を探します。指定されたどのディレクトリでも lib が見つからなければ None を返します。
funcname が現在のプラットフォームでサポートされているかどうかをブール値で返します。省略可能引数は追加のインクルードファイルやパス、ライブラリやパスを与えることでコンパイル環境を指定します。
dir をライブラリ探索ディレクトリに追加するコンパイラオプションを返します。
共有ライブラリまたは実行ファイルにリンクされるライブラリ一覧に lib を追加するコンパイラオプションを返します。
ランタイムライブラリを検索するディレクトリのリストに dir を追加するコンパイラオプションを返します。
コンパイルのいろいろなステージで実行される実行ファイル(とその引数)を定義します。コンパイラクラス(の ‘executables’ 属性)によって実行ファイルのセットは変わる可能性がありますが、ほとんどは以下のものを持っています:
attribute | description |
---|---|
compiler | C/C++ コンパイラ |
linker_so | シェアードオブジェクト、ライブラリを作るために使うリンカ |
linker_exe | バイナリ実行可能ファイルを作るために使うリンカ |
archiver | 静的ライブラリを作るアーカイバ |
コマンドラインをもつプラットフォーム(Unix, DOS/Windows)では、それぞれの文字列は実行ファイル名と(省略可能な)引数リストに分割されます。(文字列の分割は Unix のシェルが行うものに似ています: 単語はスペースで区切られますが、クォートとバックスラッシュでオーバーライドできます。 distutils.util.split_quoted() をごらんください。)
以下のメソッドはビルドプロセスのステージを呼び出します。
1つ以上のソースファイルをコンパイルします。オブジェクトファイルを生成 (たとえば .c ファイルを .o ファイルに変換)します。
sources はファイル名のリストである必要があります。おそらく C/C++ ファイルですが、実際にはコンパイラとコンパイラクラスで扱えるもの(例: MSVCCompiler はリソースファイルを sources にとることができます)なら何でも指定できます。 sources のソースファイルひとつずつに対応するオブジェクトファイル名のリストを返します。実装に依存しますが、全てのソースファイルがコンパイルされる必要はありません。しかし全ての対応するオブジェクトファイル名が返ります。
もし output_dir が指定されていれば、オブジェクトファイルはその下に、オリジナルのパスを維持した状態で置かれます。つまり、 foo/bar.c は通常コンパイルされて foo/bar.o になります (Unix実装の場合)が、もし output_dir が build であれば、 build/foo/bar.o になります。
macros は(もし指定されていれば)マクロ定義のリストである必要があります。マクロ定義は (name, value) という形式の2要素のタプル、または (name,) という形式の1要素のタプルのどちらかです。前者はマクロを定義します。もし value が None であれば、マクロは特定の値をもたないで定義されます。1要素のタプルはマクロ定義を削除します。後で実行された定義/再定義/削除が優先されます。
include_dirs は(もし指定されていれば)文字列のリストである必要があります。このコンパイルだけで有効な、デフォルトのインクルードファイルの検索ディレクトリに追加するディレクトリ群を指定します。
debug はブーリアン値です。もし真なら、コンパイラはデバッグシンボルをオブジェクトファイルに(または別ファイルに)出力します。
extra_postargs と extra_postargs は実装依存です。コマンドラインをもっているプラットフォーム(例 Unix, DOS/Windows)では、おそらく文字列のリスト: コンパイラのコマンドライン引数の前/後に追加するコマンドライン引数です。他のプラットフォームでは、実装クラスのドキュメントを参照してください。どの場合でも、これらの引数は抽象コンパイラフレームワークが期待に沿わない時の脱出口として意図されています。
depends は(もし指定されていれば)ターゲットが依存しているファイル名のリストです。ソースファイルが依存しているファイルのどれかより古ければ、ソースファイルは再コンパイルされます。これは依存関係のトラッキングをサポートしていますが、荒い粒度でしか行われません。
失敗すると CompileError を起こします。
静的ライブラリファイルを作るために元ファイル群をリンクします。「元ファイル群」は objects で指定されたオブジェクトファイルのリストを基礎にしています。追加のオブジェクトファイルを add_link_object() および/または set_link_objects() で指定し、追加のライブラリを add_library() および/または set_libraries() で指定します。そして libraries で指定されたライブラリです。
output_libname はライブラリ名で、ファイル名ではありません; ファイル名はライブラリ名から作られます。 output_dir はライブラリファイルが起かれるディレクトリです。 debug はブール値です。真なら、デバッグ情報がライブラリに含まれます(ほとんどのプラットフォームではコンパイルステップで意味をもちます: debug フラグは一貫性のためにここにもあります。)。
target_lang はオブジェクトがコンパイルされる対象になる言語です。これはその言語特有のリンク時の処理を可能にします。
失敗すると LibError を起こします。
実行ファイルまたは共有ライブラリファイルを作るために元ファイル群をリンクします。
「元ファイル群」は objects で指定されたオブジェクトファイルのリストを基礎にしています。 output_filename はファイル名です。もし output_dir が指定されていれば、それに対する相対パスとして output_filename は扱われます(必要ならば output_filename はディレクトリ名を含むことができます。)。
libraries はリンクするライブラリのリストです。これはファイル名ではなくライブラリ名で指定します。プラットフォーム依存の方式でファイル名に変換されます(例: foo はUnix では libfoo.a に、DOS/Windowsでは foo.lib になります。 )。ただしこれらはディレクトリ名を含むことができ、その場合はリンカは通常の場所全体を探すのではなく特定のディレクトリを参照します。
library_dirs はもし指定されるならば、修飾されていない(ディレクトリ名を含んでいない)ライブラリ名で指定されたライブラリを探索するディレクトリのリストです。これはシステムのデフォルトより優先され、 add_library_dir() と/または set_library_dirs() に渡されます。 runtime_library_dirs は共有ライブラリに埋め込まれるディレクトリのリストで、実行時にそれが依存する共有ライブラリのパスを指定します(これはUnixでだけ意味があるかもしれません。)。
export_symbols は共有ライブラリがエクスポートするシンボルのリストです。 (これはWindowsだけで意味があるようです。)
debug は compile() や create_static_lib() と同じですが、少しだけ違いがあり、(create_static_lib() では debug フラグは形式をあわせるために存在していたのに対して)ほとんどのプラットフォームで意識されます。
extra_preargs と extra_postargs は compile() と同じですが、コンパイラではなくリンカへの引数として扱われます。
target_lang は指定されたオブジェクトがコンパイルされた対象言語です。リンク時に言語特有の処理を行えるようにします。
失敗すると LinkError が起きます。
実行ファイルをリンクします。 output_progname は実行ファイルの名前です。 objects はリンクされるオブジェクトのファイル名のリストです。他の引数は link() メソッドと同じです。
共有ライブラリをリンクします。 output_libname は出力先のライブラリ名です。 objects はリンクされるオブジェクトのファイル名のリストです。他の引数は link() メソッドと同じです。
共有オブジェクトをリンクします。 output_filename は出力先の共有オブジェクト名です。 objects はリンクされるオブジェクトのファイル名のリストです。他の引数は link() メソッドと同じです。
source で指定されたひとつの C/C++ソースファイルをプリプロセスします。出力先のファイルは output_file か、もし output_file が指定されていなければ stdout になります。 macro は compile() と同様にマクロ定義のリストで、 define_macro() や undefine_macro() によって引数になります。 include_dirs はデフォルトのリストに追加されるディレクトリ名のリストで、 add_include_dir() と同じ方法で扱われます。
失敗すると PreprocessError が起きます。
以下のユーティリティメソッドは具体的なサブクラスで使うために、 CCompiler クラスで定義されています。
basename で指定された実行ファイルのファイル名を返します。 Windows以外の典型的なプラットフォームではbasenameそのままが、Windowsでは .exe が追加されたものが返ります。
現在のプラットフォームでのライブラリファイル名を返します。 Unixで lib_type が 'static' の場合、 liblibname.a の形式を返し、 lib_type が 'dynamic' の場合は liblibname.so の形式を返します。
指定されたソースファイルに対応するオブジェクトファイル名を返します。 source_filenames はファイル名のリストです。
basename に対応する共有オブジェクトファイルのファイル名を返します。
distutils.util.execute() を呼びだします。このメソッドはログを取り、 dry_run フラグを考慮にいれて、 Python関数 func に引数 args を与えて呼びだします。
distutils.util.spawn() を呼び出します。これは指定したコマンドを実行する外部プロセスを呼び出します。
distutils.dir_util.mkpath() を呼び出します。これは親ディレクトリ込みでディレクトリを作成します。
distutils.file_util.move_file() を呼び出します。 src を dst にリネームします。
distutils.log.debug() 関数を使ってメッセージを書き出します。
警告メッセージ msg を標準エラー出力に書き出します。
このモジュールは UnixCCompiler クラスを提供します。 CCompiler クラスのサブクラスで、典型的なUnixスタイルのコマンドラインCコンパイラを扱います:
このモジュールは MSVCCompiler クラスを提供します。抽象クラス CCompiler の具象クラスでMicrosoft Visual Studio向けのものです。一般的に、拡張モジュールはPythonをコンパイルしたのと同じコンパイラでコンパイルする必要があります。Python 2.3 やそれ以前では、コンパイラはVisual Studio 6でした。 Python 2.4 と Python 2.5 では、コンパイラは Visual Studio .NET 2003 です。 AMD64 と Itanium バイナリは Platform SDK を利用して作成されました。
MSVCCompiler は大体正しいコンパイラ、リンカその他を選びます。この選択を上書きするためには、環境変数 DISTUTILS_USE_SDK と MSSdk の両方を設定する必要があります。 MSSdk は現在の環境をセットアップした SetEnv.Cmd スクリプト、もしくは環境変数がSDKをインストールした時に登録されたものであることを示します。 DISTUTILS_USE_SDK はdistutilsのユーザーが明示的に MSVCCompiler が選んだコンパイラを上書きすることを示します。
このモジュールは BorlandCCompiler クラスを提供します。抽象クラス CCompiler の具象クラスでBorland C++ コンパイラ向けです。
このモジュールは CygwinCCompiler クラスを提供します。 UnixCCompiler のサブクラスで Cygwinに移植されたWindows用の GNU C コンパイラ向けです。さらに Mingw32CCompiler クラスを含んでおり、これは mingw32 向けに移植された GCC (cygwinの no-cygwin モードと同じ)向けです。
このモジュールは EMXCCompiler クラスを提供します。 UnixCCompiler のサブクラスで GNU C コンパイラの OS/2 向け EMX ポートを扱います。
このモジュールはアーカイブファイル(tarやzip)を作成する関数を提供します。
アーカイブファイル(例: zip や tar)を作成します。 base_name は作成するファイル名からフォーマットの拡張子を除いたものです。 format はアーカイブのフォーマットで zip, tar, ztar, gztar のいずれかです。 root_dir はアーカイブのルートディレクトリになるディレクトリです: つまりアーカイブを作成する前に root_dir に chdir します。 base_dir はアーカイブの起点となるディレクトリです: つまり base_dir はアーカイブ中の全ファイルおよびディレクトリの前につくディレクトリ名です。 root_dir と base_dir はともにカレントディレクトリがデフォルト値です。アーカイブファイル名を返します。
base_dir 以下の全ファイルから、tarファイルを作成(オプションで圧縮)します。 compress は 'gzip', 'compress', 'bzip2',または None である必要があります。 tar と compress で指定された圧縮ユーティリティにはパスが通っている必要があるので、これはおそらくUnix だけで有効です。出力tarファイルは base_dir.tar という名前になり、圧縮によって拡張子がつきます(.gz, .bz2 または .Z)。出力ファイル名が返ります。
このモジュールはシンプルなタイムスタンプを元にしたファイルやファイル群の依存関係を処理する関数を提供します。さらに、それらの依存関係解析を元にした関数を提供します。
source が存在して、 target より最近変更されている、または source が存在して、 target が存在していない場合は真を返します。両方が存在していて、 target のほうが source より新しいか同じ場合には偽を返します。 source が存在しない場合には DistutilsFileError を起こします。
ふたつのファイル名リストを並列に探索して、それぞれのソースが対応するターゲットより新しいかをテストします。 newer() の意味でターゲットよりソースが新しいペアのリスト(sources,*targets*)を返します。
target が source にリストアップされたどれかのファイルより古ければ真を返します。言い換えれば、 target が存在して sources の全てより新しいなら偽を返し、そうでなければ真を返します。 missing はソースファイルが存在しなかった時の振る舞いを決定します。デフォルト('error')は os.stat() で OSError 例外を起こします。もし 'ignore' なら、単に存在しないソースファイルを無視します。もし 'newer' なら、存在しないソースファイルについては target が古いとみなします(これは”dry-tun”モードで便利です: 入力がないのでコマンドは実行できませんが実際に実行しようとしていないので問題になりません)。
このモジュールはディレクトリとディレクトリツリーを操作する関数を提供します。
ディレクトリと、必要な親ディレクトリを作成します。もしディレクトリが既に存在している(name が空文字列の場合、カレントディレクトリを示すのでもちろん存在しています)場合、何もしません。ディレクトリを作成できなかった場合(例: ディレクトリと同じ名前のファイルが既に存在していた)、 DistutilsFileError を起こします。もし verbose が真なら、それぞれのmkdirについて1行、標準出力に出力します。実際に作成されたディレクトリのリストを返します。
files を置くために必要な空ディレクトリを base_dir 以下に作成します。 base_dir ディレクトリは存在している必要はありません。 files はファイル名のリストで base_dir からの相対パスとして扱われます。 base_dir + files のディレクトリ部分が(既に存在していなければ)作成されます。 mode, verbose と dry_run フラグは mkpath() と同じです。
src ディレクトリツリー全体を dst にコピーします。 src と dst はどちらもディレクトリ名である必要があります。もし src がディレクトリでなければ、 DistutilsFileError を起こします。もし dst が存在しなければ、 mkpath() で作成されます。実行結果は、 src 以下の全てのファイルが dst にコピーされ、 src 以下の全てのディレクトリが dst に再帰的にコピーされます。コピーされた(またはされるはず)のファイルのリストを返します。返り値は update または dry_run に影響されません: src 以下の全ファイルを単に dst 以下に改名したリストが返されます。
preserve_mode と preserve_times は distutils.file_util の copy_file() と同じです: 通常のファイルには適用されますが、ディレクトリには適用されません。 もし preserve_symlinks が真なら、シンボリックリンクは(サポートされているシステムでは)シンボリックリンクとしてコピーされます。そうでなければ(デフォルト)シンボリックリンクは参照されている実体ファイルがコピーされます。 update と verbose は copy_file() と同じです。
再帰的に directory とその下の全ファイルを削除します。エラーは無視されます(verbose が真の時は sys.stdout に出力されます)
このモジュールはそれぞれのファイルを操作するユーティリティ関数を提供します。
ファイル src を dst にコピーします。もし dst がディレクトリなら、 src はそこへ同じ名前でコピーされます; そうでなければ、ファイル名として扱われます。 (もしファイルが存在するなら、上書きされます。) mosil preserve_mode が真(デフォルト)なら、ファイルのモード (タイプやパーミッション、その他プラットフォームがサポートするもの)もコピーされます。もし preserve_times が真(デフォルト)なら、最終更新、最終アクセス時刻もコピーされます。もし update が真なら、 src は dst が存在しない場合か、 dst が src より古い時にだけコピーします。
link は値を 'hard' または 'sym' に設定することでコピーのかわりにハードリンク(os.link() を使います)またはシンボリックリンク(os.symlink() を使います)を許可します。 None (デフォルト)の時には、ファイルはコピーされます。 link をサポートしていないシステムで有効にしないでください。 copy_file() はハードリンク、シンボリックリンクが可能かチェックしていません。ファイルの内容をコピーするために _copy_file_contents() を利用しています。
(dest_name, copied) のタプルを返します: dest_name は出力ファイルの実際の名前、 copied はファイルがコピーされた(dry_run が真の時にはコピーされることになった)場合には真です。
ファイル src を dst に移動します。もし dst がディレクトリなら、ファイルはそのディレクトリに同じ名前で移動されます。そうでなければ、 src は dst に単にリネームされます。新しいファイルの名前を返します。
filename を作成し、 contents (行末文字がない文字列のシーケンス)を書き込みます。
このモジュールは他のユーティリティモジュールにあわないものを提供しています。
現在のプラットフォームを示す文字列を返します。これはプラットフォーム依存のビルドディレクトリやプラットフォーム依存の配布物を区別するために使われます。典型的には、(‘os.uname()’ のように) OSの名前とバージョン、アーキテクチャを含みますが、厳密にはOSに依存します。たとえば IRIXではアーキテクチャはそれほど重要ではありません(IRIXはSGIのハードウェアだけで動作する)が、 Linuxではカーネルのバージョンはそれほど重要ではありません。
返り値の例:
POSIX でないプラットフォームでは、今のところ単に sys.platform が返されます。
Mac OS X システムでは、 OS バージョンは、現在のOSバージョンではなく、実行するバイナリの最小バージョンを表しています。 (これは、Python をビルドするときの MACOSX_DEPLOYMENT_TARGET の値です。)
Mac OS X のユニバーサルバイナリビルドでは、アーキテクチャの値は現在のプロセッサではなく、ユニバーサルバイナリの状態を表しています。 32bit ユニバーサルバイナリではアーキテクチャは fat で、 64bit ユニバーサルバイナリではアーキテクチャは fat64 で、 4-way ユニバーサルバイナリではアーキテクチャは universal になります。 Python 2.7 と Python 3.2 から 3-way ユニバーサルバイナリ (ppc, i386, x86_64) には fat3 が i386 と x86_64 ユニバーサルバイナリには intel が使われるようになりました。
Mac OS X で返される値の例:
‘pathname’ をファイルシステムで利用できる名前にして返します。すなわち、’/’で分割し、現在のディレクトリセパレータで接続しなおします。セットアップスクリプト中のファイル名はUnixスタイルで提供され、実際に利用する前に変換する必要があるため、この関数が必要になります。もし pathname の最初または最後がスラッシュの場合、Unix的でないシステムでは ValueError が起きます。
pathname の前に new_root を追加したものを返します。もし pathname が相対パスなら、 os.path.join(new_root,pathname) と等価です。そうでなければ、 pathname を相対パスに変換したあと接続します。これはDOS/Windows ではトリッキーな作業になります。
‘os.environ’に、ユーザがconfigファイル、コマンドラインオプションなどで利用できることを保証している環境変数があることを確認します。現在は以下のものが含まれています:
shell/Perlスタイルの変数置換を s について行います。全ての $ に名前が続いたものは変数とみなされ、辞書 local_vars でみつかった値に置換されます。 local_vars で見つからなかった場合には os.environ で置換されます。 os.environ は最初にある値を含んでいることをチェックされます: check_environ() を参照。 local_vars or os.environ のどちらにも値が見つからなかった場合、 ValueError を起こします。
これは完全な文字列挿入関数ではないことに注意してください。 $variable の名前には大小英字、数字、アンダーバーだけを含むことができます。 { } や ( ) を使った引用形式は利用できません。
例外オブジェクト EnvironmentError (IOError または OSError) から、エラーメッセージを生成します。 Python 1.5.1 またはそれ以降の形式を扱い、ファイル名を含んでいない例外オブジェクトも扱います。このような状況はエラーが2つのファイルに関係する操作、たとえば rename() や link() で発生します。 prefix をプレフィクスに持つエラーメッセージを返します。
文字列をUnixのシェルのようなルール(引用符やバックスラッシュの扱い)で分割します。つまり、バックスラッシュでエスケープされるか、引用符で囲まれていなければ各語はスペースで区切られます。一重引用符と二重引用符は同じ意味です。引用符もバックスラッシュでエスケープできます。 2文字でのエスケープシーケンスに使われているバックスラッシュは削除され、エスケープされていた文字だけが残ります。引用符は文字列から削除されます。語のリストが返ります。
外部に影響するいくつかのアクション(たとえば、ファイルシステムへの書き込み)を実行します。そのようなアクションは dry_run フラグで無効にする必要があるので特別です。この関数はその繁雑な処理を行います。関数と引数のタプル、(実行する「アクション」をはっきりさせるための)表示に使われる任意のメッセージを渡してください。
真偽値をあらわす文字列を真(1)または偽(0)に変換します。
真の値は y, yes, t, true, on そして 1 です。偽の値は n, no, f, false, off そして 0 です。 val が上のどれでもない時は ValueError を起こします。
Pythonソースファイル群をバイトコンパイルして .pyc または .pyo ファイルを同じディレクトリに作成します。 py_files はコンパイルされるファイルのリストです。 .py で終わっていないファイルはスキップされます。 optimize は以下のどれかです:
もし force が真なら、全てのファイルがタイムスタンプに関係なく再コンパイルされます。
バイトコード(bytecode)ファイルにエンコードされるソースファイル名は、デフォルトでは py_files が使われます。これを prefix と base_dir で変更することができます。 prefix はそれぞれのソースファイル名から削除される文字列で、 base_dir は(prefix を削除したあと)先頭に追加されるディレクトリ名です。任意に prefix と base_dir のどちらか、両方を与える(与えない)ことができます。
もし dry_run が真なら、ファイルシステムに影響することは何もされません。
バイトコンパイルは現在のインタプリタプロセスによって標準の py_compile モジュールを使って直接行われるか、テンポラリスクリプトを書いて間接的に行われます。通常は byte_compile() に直接かそうでないかをまかせます (詳細についてはソースをごらんください)。 direct フラグは関節モードで作成されたスクリプトで使用されます。何をやっているか理解していない時は None のままにしておいてください。
このモジュールは Distribution クラスを提供します。これは構築/インストール/配布される配布物をあらわします。
このモジュールは Extension クラスを提供します。 C/C++拡張モジュールをセットアップスクリプトで表すために使われます。
このモジュールはDEBUGフラグを提供します。
distutilsのモジュールで使用される例外を提供します。 distutilsのモジュールは標準的な例外を起こします。特に、 SystemExit はエンドユーザによる失敗(コマンドライン引数の間違いなど)で起きます。
このモジュールは from ... import * で安全に使用することができます。このモジュールは Distutils ではじまり、 Error で終わるシンボルしかexportしません。
このモジュールは以下の機能を標準の getopt モジュールに追加するラッパを提供します:
ラッパ関数。 options は FancyGetopt のコンストラクタで説明されている (long_option, short_option, help_string) の3要素タプルのリストです。 negative_opt はオプション名からオプション名のマッピングになっている辞書で、キー、値のどちらも options リストに含まれている必要があります。 object は値を保存するオブジェクト(FancyGetopt クラスの getopt() メソッドを参照してください)です。 args は引数のリストです。 args として None を渡すと、 sys.argv[1:] が使われます。
text を width 以下の幅で折り返します。
option_table は 3つ組タプルのリストです。 (long_option, short_option, help_string)
もしオプションが引数を持つなら、 long_option に '=' を追加する必要があります。 short_option は一文字のみで、 ':' はどの場合にも不要です。 long_option に対応する short_option がない場合、 short_option は None にしてください。全てのオプションタプルは長い形式のオプションを持つ必要があります。
FancyGetopt クラスは以下のメソッドを提供します:
argsのコマンドラインオプションを解析します。 object に属性として保存します。
もし args が None もしくは与えられない場合には、 sys.argv[1:] を使います。もし object が None もしくは与えられない場合には、新しく OptionDummy インスタンスを作成し、オプションの値を保存したのち (args, object) のタプルを返します。もし object が提供されていれば、その場で変更され、 getopt() は args のみを返します。どちらのケースでも、返された args は渡された args リスト(これは変更されません)の変更されたコピーです。
直前に実行された getopt() が処理した (option, value) タプルのリストを返します。 getopt() がまだ呼ばれていない場合には RuntimeError を起こします。
この FancyGetopt オブジェクトのオプションテーブルからヘルプテキスト(出力の一行に対応する文字列のリスト)を生成します。
もし与えられていれば、 header をヘルプの先頭に出力します。
このモジュールはファイルシステムを見て、ファイルのリストを構築するために使われる FileList クラスを提供します。
このモジュールは spawn() 関数を提供します。これは様々なプラットフォーム依存の他プログラムをサブプロセスとして実行する関数に対するフロントエンドになっています。与えられた実行ファイルの名前からパスを探索する find_executable() 関数も提供しています。
distutils.sysconfig モジュールでは、 Python の低水準の設定情報へのアクセス手段を提供しています。アクセスできる設定情報変数は、プラットフォームと設定自体に大きく左右されます。また、特定の変数は、使っているバージョンの Python のビルドプロセスに左右されます; こうした変数は、 Unix システムでは、 Makefile や Python と一緒にインストールされる設定ヘッダから探し出されます。設定ファイルのヘッダは、2.2 以降のバージョンでは pyconfig.h 、それ以前のバージョンでは config.h です。
他にも、 distutils パッケージの別の部分を操作する上で便利な関数がいくつか提供されています。
os.path.normpath(sys.prefix) の結果です。
os.path.normpath(sys.exec_prefix) の結果です。
ある一つの設定変数に対する値を返します。 get_config_vars().get(name) と同じです。
定義されている変数のセットを返します。引数を指定しなければ、設定変数名を変数の値に対応付けるマップ型を返します。引数を指定する場合、引数の各値は文字列でなければならず、戻り値は引数に関連付けられた各設定変数の値からなるシーケンスになります。引数に指定した名前の設定変数に値がない場合、その変数に対する戻り値には None が入ります。
設定ヘッダのフルパス名を返します。 Unixの場合、このヘッダファイルは configure スクリプトによって生成されるヘッダファイル名です; 他のプラットフォームでは、ヘッダは Python ソース配布物中で直接与えられています。ファイルはプラットフォーム固有のテキストファイルです。
Python をビルドする際に用いる Makefile のフルパスを返します。 Unixの場合、このファイルは configure スクリプトによって生成されます; 他のプラットフォームでは、この関数の返す値の意味は様々です。有意なファイル名を返す場合、ファイルはプラットフォーム固有のテキストファイル形式です。この関数は POSIX プラットフォームでのみ有用です。
C インクルードファイルディレクトリについて、一般的なディレクトリ名か、プラットフォーム依存のディレクトリ名のいずれかを返します。 plat_specific が真であれば、プラットフォーム依存のインクルードディレクトリ名を返します; plat_specific が偽か、省略された場合には、プラットフォームに依存しないディレクトリを返します。 prefix が指定されていれば、 PREFIX の代わりに用いられます。また、 plat_specific が真の場合、 EXEC_PREFIX の代わりに用いられます。
ライブラリディレクトリについて、一般的なディレクトリ名か、プラットフォーム依存のディレクトリ名のいずれかを返します。 plat_specific が真であれば、プラットフォーム依存のライブラリディレクトリ名を返します; plat_specific が偽か、省略された場合には、プラットフォームに依存しないディレクトリを返します。 prefix が指定されていれば、 PREFIX の代わりに用いられます。また、 plat_specific が真の場合、 EXEC_PREFIX の代わりに用いられます。 standard_lib が真であれば、サードパーティ製の拡張モジュールをインストールするディレクトリの代わりに、標準ライブラリのディレクトリを返します。
以下の関数は、 distutils パッケージ内の使用だけを前提にしています。
distutils.ccompiler.CCompiler インスタンスに対して、プラットフォーム固有のカスタマイズを行います。
この関数は現在のところ、Unix だけで必要ですが、将来の互換性を考慮して一貫して常に呼び出されます。この関数は様々な Unix の変種ごとに異なる情報や、Python の Makefile に書かれた情報をインスタンスに挿入します。この情報には、選択されたコンパイラやコンパイラ/リンカのオプション、そして共有オブジェクトを扱うためにリンカに指定する拡張子が含まれます。
この関数はもっと特殊用途向けで、Python 自体のビルドプロセスでのみ使われるべきです。
distutils.sysconfig モジュールに、モジュールが Python のビルドプロセスの一部として使われることを知らせます。これによって、ファイルコピー先を示す相対位置が大幅に変更され、インストール済みの Python ではなく、ビルド作業領域にファイルが置かれるようになります。
このモジュールは TextFile クラスを提供します。これはテキストファイルへのインタフェースを提供し、コメントの削除、空行の無視、バックスラッシュでの行の連結を任意に行えます。
このクラスはファイルのようなオブジェクトを提供します。これは行指向のテキストファイルを処理する時に共通して必要となる処理を行います: (# がコメント文字なら)コメントの削除、空行のスキップ、 (行末のバックスラッシュでの)改行のエスケープによる行の連結、先頭/末尾の空白文字の削除。これらは全て独立して任意に設定できます。
クラスは warn() メソッドを提供しており、物理行つきの警告メッセージを生成することができます。この物理行は論理行が複数の物理行にまたがっていても大丈夫です。また unreadline() メソッドが一行先読みを実装するために提供されています。
TextFile のインスタンスは filename, file,またはその両方をとって作成されます。両方が None の場合 RuntimeError が起きます。 filename は文字列、 file はファイルオブジェクト(または readline() と close() のメソッドを提供する何か) である必要があります。 TextFile が生成する警告メッセージに含めることができるので、 filename を与えることが推奨されます、もし file が提供されなければ、 TextFile は組み込みの open() を利用して自分で作成します。
オプションは全て真偽値で、 readline() で返される値に影響します。
option name | 説明 | デフォルト値 |
---|---|---|
strip_comments | バックスラッシュでエスケープされていない限り、 '#' から行末までと、 '#' の先にある空白文字の並びを削除します。 | true |
lstrip_ws | 行を返す前に先頭の空白文字の並びを削除します。 | false |
rstrip_ws | 行を返す前に行末の空白文字(改行文字を含みます!)の並びを削除します。 | true |
skip_blanks | コメントと空白を除いた*あとで*内容がない行をスキップします。 (もし lstrip_ws と rstrip_ws がともに偽なら、空白文字だけの行があるかもしれません。これは skip_blanks が真でない限りスキップされません。) | true |
join_lines | もしコメントと空白文字を削除したあとで、バックスラッシュが最後の改行文字でない文字なら、次の行を接続して一つの論理行とします: N行の連続した行がバックスラッシュで終わる場合、N+1 行の物理行が1行の論理行として扱われます。 | false |
collapse_join | 前の行と接続するとき、行頭の空白文字を削除します。 (join_lines and not lstrip_ws) の時だけ意味をもちます。 | false |
rstrip_ws は行末の改行を削除するので、 readline() のセマンティクスが組み込みファイルオブジェクトの readline() メソッドとは変わってしまいます! 特に、 rstrip_ws が真で skip_blanks が偽のとき、 readline() はファイルの終端で None を返し、空文字列を返したときは空行(または全て空白文字の行)です。
新しいファイル filename を開きます。これはコンストラクタ引数の file と filename を上書きします。
現在のファイルを閉じ、(ファイル名や現在の行番号を含め)現在のファイルについての情報を全て消します。
標準エラー出力に現在のファイルの論理行に結びついた警告メッセージを出力します。もし現在の論理行が複数の物理行に対応するなら、警告メッセージは以下のように全体を参照します: "lines 3-5" 。もし line が与えられていれば、現在の行番号を上書きします; 物理行のレンジをあらわすリストまたはタプル、もしくはある物理行をあらわす整数のどれでも与えられます。
現在のファイル(または unreadline() で”unread”を直前に行っていればバッファ)から論理行を1行読み込んで返します。もし join_lines オプションが真なら、このメソッドは複数の物理行を読み込んで接続した文字列を返します。現在の行番号を更新します。そのため readline() のあとに warn() を呼ぶと丁度読んだ行についての警告を出します。 rstrip_ws が真で、 strip_blanks が偽のとき空文字列が返るので、ファイルの終端では None を返します。
現在のファイルで残っている全ての論理行のリストを読み込んで返します。行番号を、ファイルの最後の行に更新します。
line (文字列)を次の readline() 用に、内部バッファにpushします。行の先読みを必要とするパーサを実装する時に便利です。 unreadline() で”unread”された行は readline() で読み込む際に再度処理(空白の除去など)されません。もし unreadlinee() を、 readline() を呼ぶ前に複数回実行すると、最後にunreadした行から返されます。
このモジュールは抽象ベースクラス Command を提供します。
コマンドクラスを定義するための抽象ベースクラス — distutilsの「働きバチ」 — です。コマンドクラスは options とよばれるローカル変数を持ったサブルーチンと考えることができます。オプションは initialize_options() で宣言され、 finalize_options() で定義さ(最終的な値を与えら)れます。どちらも全てのコマンドクラスで実装する必要があります。この2つの区別は必要です。なぜならオプションの値は外部(コマンドライン、設定ファイルなど)から来るかもしれず、他のオプションに依存しているオプションは外部の影響を処理した後で計算される必要があるからです。そのため finalize_options() が存在します。サブルーチンの本体は全ての処理をオプションの値にもとづいて行う run() メソッドで、これも全てのコマンドクラスで実装される必要があります。
クラスのコンストラクタは Distribution のインスタンスである単一の引数 dist をとります。
このセクションではDistutilsの新しいコマンドを作成する手順の概要をしめします。
新しいコマンドは distutils.command パッケージ中のモジュールに作られます。 command_template というディレクトリにサンプルのテンプレートがあります。このファイルを実装しようとしているコマンドと同名の新しいモジュールにコピーしてください。このモジュールはモジュール(とコマンド)と同じ名前のクラスを実装する必要があります。そのため、 peel_banana コマンド(ユーザは setup.py peel_banana と実行できます)を実装する際には、 command_template を distutils/command/peel_banana.py にコピーし、 distutils.cmd.Command のサブクラス peel_banana クラスを実装するように編集してください。
Command のサブクラスは以下のメソッドを実装する必要があります。
このコマンドがサポートする全てのオプションのデフォルト値を設定します。これらのデフォルトは他のコマンドやセットアップスクリプト、設定ファイル、コマンドラインによって上書きされるかもしれません。そのためオプション間の依存関係を記述するには適切な場所ではありません。一般的に initialize_options() は単に self.foo = None のような定義だけを行います。
このコマンドがサポートする全てのオプションの最終的な値を設定します。これは可能な限り遅く呼び出されます。つまりコマンドラインや他のコマンドによるオプションの代入のあとに呼び出されます。そのため、オプション間の依存関係を記述するのに適した場所です。もし foo が bar に依存しており、かつまだ foo が initialize_options() で定義された値のままなら、 foo を bar から代入しても安全です。
コマンドの本体です。実行するべきアクションを実装しています。 initialize_options() で初期化され、他のコマンドされ、セットアップスクリプト、コマンドライン、設定ファイルでカスタマイズされ、 finalize_options() で設定されたオプションがアクションを制御します。端末への出力とファイルシステムとのやりとりは全て run() が行います。
sub_commands はコマンドの”ファミリー”を定式化したものです。たとえば install はサブコマンド install_lib install_headers などの親です。コマンドファミリーの親は sub_commands をクラス属性として持ちます。 sub_commands は2要素のタプル (command_name, predicate) のリストで、 command_name は文字列、 predicate は関数か文字列か None です。 predicate はには親コマンドのメソッドで、現在の状況がコマンド実行にふさわしいかどうか判断するものを指定します。 (例えば install_headers はインストールするべき Cヘッダファイルがある時だけ有効です。) もし predicate が None なら、そのコマンドは常に有効になります。
sub_commands は通常クラスの 最後 で定義されます。 これは predicate は bound されていないメソッドになるので、全て先に定義されている必要があるためです。標準的な例は install コマンドです。
Windows Installer (.msi) バイナリパッケージをビルドします。
多くの場合、 bdist_msi インストーラは Win64 のサポートが優れていて、管理者が非インタラクティブインストールできたり、グループポリシーを利用したインストールができるので、 bdist_wininst インストーラよりも良い選択です。
register コマンドはパッケージをPython Package Index に登録します。この詳細は PEP 301 に記述されています。
check コマンドはパッケージのメタデータに対していくつかのテストをします。例えば、要求される全てのメタデータが setup() 関数の引数に渡されているかを検証します。