9. API リファレンス¶

参考

setuptools で新規追加または変更された setup.py の引数: setuptools プロジェクトは setup 関数や他の API に新しい機能を追加したり、異なる Python バージョンの間で API に一貫性を持たせているため、 distutils の代替として推奨されています。

注釈

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

9.1. `distutils.core` --- Distutils のコア機能¶

Distutilsを使うためにインストールする必要がある唯一のモジュールが distutils.core モジュールです。 setup() 関数 (セットアップスクリプトから呼び出されます)を提供します。間接的に distutils.dist.Distribution クラスと distutils.cmd.Command クラスを提供します。

distutils.core.setup(arguments)¶

全てを実行する基本的な関数で、Distutilsでできるほとんどのことを実行します。

setup関数はたくさんの引数をとります。以下のテーブルにまとめます。

引数名	value	type
name	パッケージの名前	文字列
version	パッケージのバージョン番号。 `distutils.version` を参照	文字列
description	1行で書いたパッケージ解説	文字列
long_description	パッケージの長い解説	文字列
author	パッケージ作者の名前	文字列
author_email	パッケージ作者のemailアドレス	文字列
maintainer	作者と違う場合の、現在のメンテナーの名前です。 maintainer 引数が与えられた場合、 distutils は `PKG-INFO` で作者として使用します	文字列
maintainer_email	現在のメンテナのemailアドレス(パッケージ作者と異なる場合)	文字列
url	パッケージのURL(ホームページ)	文字列
download_url	パッケージダウンロード用URL	文字列
packages	distutilsが操作するPythonパッケージのリスト	文字列のリスト
py_modules	distutilsが操作するPythonモジュールのリスト	文字列のリスト
scripts	ビルドおよびインストールする単体スクリプトファイルのリスト	文字列のリスト
ext_modules	ビルドする拡張モジュール	`distutils.core.Extension` のインスタンスのリスト
classifiers	パッケージのカテゴリのリスト	文字列のリスト。有効な classifier のリストは PyPI を参照。
distclass	使用する `Distribution` クラス	`distutils.core.Distribution` のサブクラス
script_name	setup.pyスクリプトの名前 - デフォルトでは `sys.argv[0]`	文字列
script_args	setup スクリプトの引数	文字列のリスト
options	セットアップスクリプトのデフォルト引数	辞書
license	パッケージのライセンス	文字列
keywords	説明用メタデータ。 PEP 314 を参照してください	文字列のリスト、またはカンマ区切り文字列
platforms		文字列のリスト、またはカンマ区切り文字列
cmdclass	コマンド名から `Command` サブクラスへのマッピング	辞書
data_files	インストールするデータファイルのリスト	リスト
package_dir	パッケージからディレクトリ名へのマッピング	辞書

distutils.core.run_setup(script_name[, script_args=None, stop_after='run'])¶

制御された環境でセットアップスクリプトを実行し、いろいろなものを操作する distutils.dist.Distribution クラスのインスタンスを返します。これはディストリビューションのメタデータ(キーワード引数 script として関数 setup() に渡される)を参照したり、設定ファイルやコマンドラインの内容を調べる時に便利です。

script は exec() で読み込まれるファイルです。 sys.argv[0] は、呼び出しのために script_name と置換されます。 script_args は文字列のリストです。もし提供されていた場合、 sys.argv[1:] は、呼び出しのために script_args で置換されます。

stop_after はいつ動作を停止するか関数 setup() に伝えます。とりうる値は:

value	description
init	`Distribution` インスタンスを作成し、キーワード引数を `setup()` に渡したあとに停止する。
config	設定ファイルをパーズしたあと停止する(そしてそのデータは `Distribution` インスタンスに保存される)。
commandline	コマンドライン (`sys.argv[1:]` または script_args) がパーズされたあとに停止する (そしてそのデータは `Distribution` インスタンスに保存される)。
run	全てのコマンドを実行したあとに停止する(関数 `setup()` を通常の方法で呼び出した場合と同じ)。デフォルト値。

これに加えて、 distutils.core モジュールは他のモジュールにあるいくつかのクラスを公開しています。

distutils.extension から Extension
distutils.cmd から Command
distutils.dist から Distribution

それぞれの簡単な説明を以下に記します。完全な説明についてはそれぞれのモジュールをごらんください。

class distutils.core.Extension¶

Extension クラスは、セットアップスクリプト中で C または C++ 拡張モジュールを表します。コンストラクタで以下のキーワード引数をとります:

引数名	value	type
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` を指定するのと等価です) を指定します	タプルのリスト
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'`)。指定しなければソースの拡張子で検出される。	文字列
optional	拡張で起きたビルド失敗によってビルドプロセスを中断せず、単にその拡張を無視して処理を進めるように指定します。	ブール値

バージョン 3.8 で変更: Android と Cygwin を除き、 Unix では C 拡張モジュールは libpython とリンクされなくなりました。

class distutils.core.Distribution¶

Distribution はPythonソフトウェアパッケージをどのようにビルド、インストール、パッケージするかを定義する。

Distribution のコンストラクタが取りうるキーワード引数のリストに関しては、 setup() 関数を見てください。 setup() は Distribution のインスタンスを作ります。

バージョン 3.7 で変更: classifiers, keywords, platforms のフィールドがリストもしくは文字列で指定されていなかった場合、 Distribution が警告を出すようになりました。

class distutils.core.Command¶: Command クラス(そのサブクラスのインスタンス)はdistutilsのあるコマンドを実装します。

9.2. `distutils.ccompiler` --- CCompiler ベースクラス¶

このモジュールは CCompiler クラスの抽象ベースクラスを提供します。 CCompiler のインスタンスはプロジェクトにおける全てのコンパイルおよびリンクに使われます。コンパイラのオプションを設定するためのメソッドが提供されます --- マクロ定義、includeディレクトリ、リンクパス、ライブラリなど。

このモジュールは以下の関数を提供します。

distutils.ccompiler.gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)¶: ライブラリを探索するディレクトリ、特定のライブラリとのリンクをするためのリンカオプションを生成します。 libraries と library_dirs はそれぞれライブラリ名(ファイル名ではありません!)のリストと、探索ディレクトリのリストです。 compilerで利用できるコマンドラインオプションのリスト(指定されたフォーマット文字列に依存します)を返します。

distutils.ccompiler.gen_preprocess_options(macros, include_dirs)¶: Cプリプロセッサオプション(-D, -U, -I)を生成します。これらは少なくとも2つのコンパイラで利用可能です。典型的な Unix のコンパイラと、VisualC++です。 macros は1または2要素のタプルで (name,) は name マクロの削除 (-U)を意味し、 (name, value) は name マクロを value として定義(-D)します。 include_dirs はディレクトリ名のリストで、ヘッダファイルのサーチパスに追加されます(-I)。 Unix のコンパイラと、Visual C++で利用できるコマンドラインオプションのリストを返します。

distutils.ccompiler.get_default_compiler(osname, platform)¶

指定されたプラットフォームのデフォルトコンパイラを返します。

問い合わせの osname はPython標準のOS名(os.name で返されるもの)のひとつであるべきで、 platform は sys.platform で返される共通の値です。

パラメータが指定されていない場合のデフォルト値は os.name と sys.platform です。

distutils.ccompiler.new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)¶: 指定されたプラットフォーム/コンパイラの組み合わせ向けに、 CCompilerサブクラスのインスタンスを生成するファクトリ関数です。 plat のデフォルト値は os.name (例: 'posix', 'nt'), compiler)、 compiler のデフォルト値はプラトフォームのデフォルトコンパイラです。現在は 'posix' と 'nt' だけがサポートされています、デフォルトのコンパイラは "traditional Unix interface" (UnixCCompiler クラス) と、 Visual C++ (MSVCCompiler クラス) です。 WindowsでUnixコンパイラオブジェクトを要求することも、UnixでMicrosoft コンパイラオブジェクトを要求することも可能です。 compiler 引数を与えると plat は無視されます。

distutils.ccompiler.show_compilers()¶: 利用可能なコンパイラのリストを表示します (build, build_ext, build_clib の、 --help-compiler オプションで使われます)。

class distutils.ccompiler.CCompiler([verbose=0, dry_run=0, force=0])¶

抽象ベースクラス CCompiler は実際のコンパイラクラスで実装される必要のあるインターフェースを定義しています。このクラスはコンパイラクラスで利用されるユーティリティメソッドも定義しています。

コンパイラ抽象クラスの基本的な前提は、各インスタンスはあるプロジェクトをビルドするときの全コンパイル/リンクで利用できるということです。そこで、コンパイルとリンクステップで共通する属性 --- インクルードディレクトリ、マクロ定義、リンクするライブラリなど --- はコンパイラインスタンスの属性になります。どのように各ファイルが扱われるかを変更できるように、ほとんどの属性はコンパイルごと、またはリンクごとに与えることができます。

各サブクラスのコンストラクタは Compiler クラスのインスタンスを作ります。フラグは verbose (冗長な出力を表示します)、 dry_run (実際にはそのステップを実行しません)、そして force (依存関係を無視して全て再ビルドします)です。これらのフラグは全てデフォルト値が 0 (無効)になっています。 CCompiler またはサブクラスを直接インスタンス化したくない場合には、かわりに distutils.CCompiler.new_compiler() ファクトリ関数を利用してください。

以下のメソッドで、Compilerクラスのインスタンスが使うコンパイラオプションを手動で変更できます。

add_include_dir(dir)¶: dir をヘッダファイル探索ディレクトリのリストに追加します。コンパイラは add_include_dir() を呼び出した順にディレクトリを探索するよう指定されます。

set_include_dirs(dirs)¶: 探索されるディレクトリのリストを dirs (文字列のリスト)に設定します。先に実行された add_include_dir() は上書きされます。後で実行する add_include_dir() は set_include_dirs() のリストにディレクトリを追加します。これはコンパイラがデフォルトで探索する標準インクルードディレクトリには影響しません。

add_library(libname)¶

libname をコンパイラオブジェクトによるリンク時に使われるライブラリのリストに追加します。 libname はライブラリを含むファイル名ではなく、ライブラリそのものの名前です: 実際のファイル名はリンカ、コンパイラ、またはコンパイラクラス(プラットフォームに依存します)から推測されます。

リンカは add_library() と set_libraries() で渡された順にライブラリをリンクしようとします。ライブラリ名が重なることは問題ありません。リンカは指定された回数だけライブラリとリンクしようとします。

set_libraries(libnames)¶: コンパイラオブジェクトによるリンク時に使われるライブラリのリストを libnames (文字列のリスト)に設定します。これはリンカがデフォルトでリンクする標準のシステムライブラリには影響しません。

add_library_dir(dir)¶: add_library() と set_libraries() で指定されたライブラリを探索するディレクトリのリストに dir を追加します。リンカは add_library_dir() と set_library_dirs() で指定された順にディレクトリを探索されます。

set_library_dirs(dirs)¶: ライブラリを探索するディレクトリを dirs (文字列のリスト)に設定します。これはリンカがデフォルトで探索する標準ライブラリ探索パスには影響しません。

add_runtime_library_dir(dir)¶: 実行時に共有ライブラリを探索するディレクトリのリストに dir を追加します。

set_runtime_library_dirs(dirs)¶: 実行時に共有ライブラリを探索するディレクトリのリストを dirs (文字列のリスト)に設定します。これはランタイムリンカがデフォルトで利用する標準探索パスには影響しません。

define_macro(name[, value=None])¶: このコンパイラオブジェクトで実行される全てのコンパイルで利用されるプリプロセッサのマクロ定義を行います。オプション引数 value は文字列でなければなりません; それが指定されない場合は、特定の値を持たないマクロが定義され、実際の値は使っているコンパイラに依存します。

undefine_macro(name)¶: このコンパイラオブジェクトで実行される全てのコンパイルで利用されるプリプロセッサのマクロ定義を消します。同じマクロを define_macro() で定義し、 undefine_macro() で定義を削除した場合、後で呼び出されたものが優先される(複数の再定義と削除を含みます)。もしコンパイルごと(すなわち compile() の呼び出しごと)にマクロが再定義/削除される場合も後で呼び出されたものが優先されます。

add_link_object(object)¶: このコンパイラオブジェクトによる全てのリンクで利用されるオブジェクトファイル(または類似のライブラリファイルや "リソースコンパイラ"の出力)のリストに object を追加します。

set_link_objects(objects)¶: このコンパイラオブジェクトによる全てのリンクで利用されるオブジェクトファイル(または類似のもの)のリストを objects に設定します。これはリンカがデフォルト利用する標準オブジェクトファイル(システムライブラリなど)には影響しません。

以下のメソッドはコンパイラオプションの自動検出を実装しており、 GNU autoconf に似たいくつかの機能を提供します。

detect_language(sources)¶: 与えられたファイルまたはファイルのリストの言語を検出します。インスタンス属性 language_map (辞書)と、 language_order (リスト)を仕事に使います。

find_library_file(dirs, lib[, debug=0])¶: 指定されたディレクトリのリストから、スタティックまたは共有ライブラリファイル lib を探し、そのファイルのフルパスを返します。もし debug が真なら、(現在のプラットフォームで意味があれば)デバッグ版を探します。指定されたどのディレクトリでも lib が見つからなければ None を返します。

has_function(funcname[, includes=None, include_dirs=None, libraries=None, library_dirs=None])¶: funcname が現在のプラットフォームでサポートされているかどうかをブール値で返します。省略可能引数は追加のインクルードファイルやパス、ライブラリやパスを与えることでコンパイル環境を指定します。

library_dir_option(dir)¶: dir をライブラリ探索ディレクトリに追加するコンパイラオプションを返します。

library_option(lib)¶: 共有ライブラリまたは実行ファイルにリンクされるライブラリ一覧に lib を追加するコンパイラオプションを返します。

runtime_library_dir_option(dir)¶: ランタイムライブラリを検索するディレクトリのリストに dir を追加するコンパイラオプションを返します。

set_executables(**args)¶

コンパイルのいろいろなステージで実行される実行ファイル(とその引数)を定義します。コンパイラクラス(の 'executables' 属性)によって実行ファイルのセットは変わる可能性がありますが、ほとんどは以下のものを持っています:

属性	description
compiler	C/C++ コンパイラ
linker_so	シェアードオブジェクト、ライブラリを作るために使うリンカ
linker_exe	バイナリ実行可能ファイルを作るために使うリンカ
archiver	静的ライブラリを作るアーカイバ

コマンドラインをもつプラットフォーム(Unix, DOS/Windows)では、それぞれの文字列は実行ファイル名と(省略可能な)引数リストに分割されます。(文字列の分割は Unix のシェルが行うものに似ています: 単語はスペースで区切られますが、クォートとバックスラッシュでオーバーライドできます。 distutils.util.split_quoted() をごらんください。)

以下のメソッドはビルドプロセスのステージを呼び出します。

compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])¶

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_preargs と extra_postargs は実装依存です。コマンドラインをもっているプラットフォーム(例 Unix, DOS/Windows)では、おそらく文字列のリスト: コンパイラのコマンドライン引数の前/後に追加するコマンドライン引数です。他のプラットフォームでは、実装クラスのドキュメントを参照してください。どの場合でも、これらの引数は抽象コンパイラフレームワークが期待に沿わない時の脱出口として意図されています。

depends は(もし指定されていれば)ターゲットが依存しているファイル名のリストです。ソースファイルが依存しているファイルのどれかより古ければ、ソースファイルは再コンパイルされます。これは依存関係のトラッキングをサポートしていますが、荒い粒度でしか行われません。

失敗すると CompileError を起こします。

create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])¶

静的ライブラリファイルを作るために元ファイル群をリンクします。「元ファイル群」は objects で指定されたオブジェクトファイルのリストを基礎にしています。追加のオブジェクトファイルを add_link_object() および/または set_link_objects() で指定し、追加のライブラリを add_library() および/または set_libraries() で指定します。そして libraries で指定されたライブラリです。

output_libname はファイル名ではなく、ライブラリ名でなければなりません; ファイル名はライブラリ名から推測されます。output_dir はライブラリファイルが置かれるディレクトリです。

debug はブーリアン値です。もし真なら、デバッグ情報はライブラリに含められます (ほとんどのプラットフォームにおいて、これが重要なのはコンパイルステップであることに注意してください: debug フラグは、ここでは単に一貫性のために含められます)。

target_lang はオブジェクトがコンパイルされる対象言語です。リンク時に言語特有の処理を行えるようにします。

失敗すると LibError を起こします。

link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])¶

実行ファイルまたは共有ライブラリファイルを作るために元ファイル群をリンクします。

「元ファイル群」は 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 が起きます。

link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])¶: 実行ファイルをリンクします。 output_progname は実行ファイルの名前です。 objects はリンクされるオブジェクトのファイル名のリストです。他の引数は link() メソッドと同じです。

link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])¶: 共有ライブラリをリンクします。 output_libname は出力先のライブラリ名です。 objects はリンクされるオブジェクトのファイル名のリストです。他の引数は link() メソッドと同じです。

link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])¶: 共有オブジェクトをリンクします。 output_filename は出力先の共有オブジェクト名です。 objects はリンクされるオブジェクトのファイル名のリストです。他の引数は link() メソッドと同じです。

preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])¶

source で指定されたひとつの C/C++ソースファイルをプリプロセスします。出力先のファイルは output_file か、もし output_file が指定されていなければ stdout になります。 macros は compile() と同様にマクロ定義のリストで、 define_macro() や undefine_macro() によって引数になります。 include_dirs はデフォルトのリストに追加されるディレクトリ名のリストで、 add_include_dir() と同じ方法で扱われます。

失敗すると PreprocessError が起きます。

以下のユーティリティメソッドは具体的なサブクラスで使うために、 CCompiler クラスで定義されています。

executable_filename(basename[, strip_dir=0, output_dir=''])¶: basename で指定された実行ファイルのファイル名を返します。 Windows以外の典型的なプラットフォームではbasenameそのままが、Windowsでは .exe が追加されたものが返ります。

library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])¶: 現在のプラットフォームでのライブラリファイル名を返します。 Unixで lib_type が 'static' の場合、 liblibname.a の形式を返し、 lib_type が 'dynamic' の場合は liblibname.so の形式を返します。

object_filenames(source_filenames[, strip_dir=0, output_dir=''])¶: 指定されたソースファイルに対応するオブジェクトファイル名を返します。 source_filenames はファイル名のリストです。

shared_object_filename(basename[, strip_dir=0, output_dir=''])¶: basename に対応する共有オブジェクトファイルのファイル名を返します。

execute(func, args[, msg=None, level=1])¶: distutils.util.execute() を実行します。このメソッドは、ロギング処理をし dry_run フラグを考慮に入れた上で、 Python 関数の func を与えられた引数 args で実行します。

spawn(cmd)¶: distutils.util.spawn() を実行します。これは与えられたコマンドを走らせる別プロセスを起動します。

mkpath(name[, mode=511])¶: distutils.dir_util.mkpath() を実行します。ディレクトリと、そこまでの不足している親ディレクトリを作成します。

move_file(src, dst)¶: distutils.file_util.move_file() を実行します。 src を dst に名前変更します。

announce(msg[, level=1])¶: distutils.log.debug() を使用してメッセージを書き出します。

warn(msg)¶: 警告メッセージ msg を標準エラー出力に書き出します。

debug_print(msg)¶: もしこの CCompiler インスタンスで debug フラグが指定されていれば msg を標準出力に出力し、そうでなければ何も出力しません。

9.3. `distutils.unixccompiler` --- Unix C コンパイラ¶

このモジュールは UnixCCompiler クラスを提供します。 CCompiler クラスのサブクラスで、典型的なUnixスタイルのコマンドラインCコンパイラを扱います:

マクロは -Dname[=value] で定義されます
マクロは -Uname で削除されます
インクルードファイルの探索ディレクトリは -Idir で指定されます
ライブラリは -llib で指定されます
ライブラリの探索ディレクトリは -Ldir で指定されます
コンパイルは cc (またはそれに似た) 実行ファイルに、 -c オプションをつけて実行します: .c を .o にコンパイルします
静的ライブラリは ar コマンドで処理されます (ranlib を使うかもしれません)
共有ライブラリのリンクは cc -shared で処理されます

9.4. `distutils.msvccompiler` --- Microsoft コンパイラ¶

このモジュールは MSVCCompiler クラスを提供します。抽象クラス CCompiler の具象クラスでMicrosoft Visual Studio向けのものです。一般的に、拡張モジュールはPythonをコンパイルしたのと同じコンパイラでコンパイルする必要があります。Python 2.3 やそれ以前では、コンパイラはVisual Studio 6でした。 Python 2.4 と Python 2.5 では、コンパイラは Visual Studio .NET 2003 です。

MSVCCompiler は大体正しいコンパイラ、リンカその他を選びます。この選択を上書きするためには、環境変数 DISTUTILS_USE_SDK と MSSdk の両方を設定する必要があります。 MSSdk は現在の環境をセットアップした SetEnv.Cmd スクリプト、もしくは環境変数がSDKをインストールした時に登録されたものであることを示します。 DISTUTILS_USE_SDK はdistutilsのユーザーが明示的に MSVCCompiler が選んだコンパイラを上書きすることを示します。

9.5. `distutils.bcppcompiler` --- Borland コンパイラ¶

このモジュールは BorlandCCompiler クラスを提供します。抽象クラス CCompiler の具象クラスでBorland C++ コンパイラ向けです。

9.6. `distutils.cygwincompiler` --- Cygwin コンパイラ¶

このモジュールは CygwinCCompiler クラスを提供します。 UnixCCompiler のサブクラスで Cygwinに移植されたWindows用の GNU C コンパイラ向けです。さらに Mingw32CCompiler クラスを含んでおり、これは mingw32 向けに移植された GCC (cygwinの no-cygwin モードと同じ)向けです。

9.7. `distutils.archive_util` --- アーカイブユーティリティ¶

このモジュールはアーカイブファイル(tarやzip)を作成する関数を提供します。

distutils.archive_util.make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])¶: アーカイブファイル(例: zip や tar)を作成します。 base_name は作成するファイル名からフォーマットの拡張子を除いたものです。 format はアーカイブのフォーマットで zip, tar, gztar, bztar, xztar, ztar のいずれかです。 root_dir はアーカイブのルートディレクトリになるディレクトリです: つまりアーカイブを作成する前に root_dir に chdir します。 base_dir はアーカイブの起点となるディレクトリです: つまり base_dir はアーカイブ中の全ファイルおよびディレクトリの前につくディレクトリ名です。 root_dir と base_dir はともにカレントディレクトリがデフォルト値です。アーカイブファイル名を返します。

バージョン 3.5 で変更: xztar 形式のサポートが追加されました。

distutils.archive_util.make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])¶: base_dir 以下の全ファイルから、 tar ファイルを作成 (オプションで圧縮) します。 compress は 'gzip' (デフォルト), 'xz', 'compress', 'bzip2' または None である必要があります。 'compress' メソッドについては、 compress で指定される圧縮ユーティリティにパスが通っている必要があるので、おそらくこれは Unix だけで有効でしょう。出力 tar ファイルは base_dir.tar という名前になり、圧縮によって拡張子が付きます(.gz, .bz2, .xz または .Z)。出力ファイル名が返ります。

バージョン 3.5 で変更: xz 形式のサポートが追加されました。

distutils.archive_util.make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])¶: base_dir 以下の全ファイルから、zipファイルを作成します。出力されるzipファイルは base_name + .zip という名前になります。 zipfile Pythonモジュール(利用可能なら)またはInfoZIP zip ユーティリティ(インストールされていてパスが通っているなら)を使います。もしどちらも利用できなければ、 DistutilsExecError が起きます。出力zipファイル名が返ります。

9.8. `distutils.dep_util` --- 依存関係のチェック¶

このモジュールはシンプルなタイムスタンプを元にしたファイルやファイル群の依存関係を処理する関数を提供します。さらに、それらの依存関係解析を元にした関数を提供します。

distutils.dep_util.newer(source, target)¶: source が存在して、 target より最近変更されている、または source が存在して、 target が存在していない場合は真を返します。両方が存在していて、 target のほうが source より新しいか同じ場合には偽を返します。 source が存在しない場合には DistutilsFileError を起こします。

distutils.dep_util.newer_pairwise(sources, targets)¶: ふたつのファイル名リストを並列に探索して、それぞれのソースが対応するターゲットより新しいかをテストします。 newer() の意味でターゲットよりソースが新しいペアのリスト(sources, targets)を返します。

distutils.dep_util.newer_group(sources, target[, missing='error'])¶: target が、 sources にリストアップされたどれかのファイルより古ければ真を返します。言い換えれば、 target が存在して sources にある全てのファイルより新しいなら偽を返し、そうでなければ真を返します。 missing はソースファイルが存在しなかった時の振る舞いを決定します。デフォルト('error')は os.stat() 関数の内部で発生した OSError 例外を投げます。 'ignore' の場合は、単に存在しないソースファイルを無視します。 'newer' の場合は、存在しないソースファイルについては target が古いとみなします(これは "dry-run" モードで便利です: 入力がないのでコマンドは実行できませんが実際に実行しようとしていないので問題になりません)。

9.9. `distutils.dir_util` --- ディレクトリツリーの操作¶

このモジュールはディレクトリとディレクトリツリーを操作する関数を提供します。

distutils.dir_util.mkpath(name[, mode=0o777, verbose=0, dry_run=0])¶: ディレクトリと、必要な親ディレクトリを作成します。もしディレクトリが既に存在している(name が空文字列の場合、カレントディレクトリを示すのでもちろん存在しています)場合、何もしません。ディレクトリを作成できなかった場合(例: ディレクトリと同じ名前のファイルが既に存在していた)、 DistutilsFileError を起こします。もし verbose が真なら、それぞれのmkdirについて1行、標準出力に出力します。実際に作成されたディレクトリのリストを返します。

distutils.dir_util.create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])¶: files を置くために必要な空ディレクトリを base_dir 以下に作成します。 base_dir ディレクトリは存在している必要はありません。 files はファイル名のリストで base_dir からの相対パスとして扱われます。 base_dir + files のディレクトリ部分が(既に存在していなければ)作成されます。 mode, verbose と dry_run フラグは mkpath() と同じです。

distutils.dir_util.copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])¶

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() のものと同じです。

Files in src that begin with .nfs are skipped (more information on these files is available in answer D2 of the NFS FAQ page).

バージョン 3.3.1 で変更: NFS ファイルは無視されます。

distutils.dir_util.remove_tree(directory[, verbose=0, dry_run=0])¶: 再帰的に directory とその下の全ファイルを削除します。エラーは無視されます (verbose が真の時は sys.stdout に出力されます)。

9.10. `distutils.file_util` --- 1ファイルの操作¶

このモジュールはそれぞれのファイルを操作するユーティリティ関数を提供します。

distutils.file_util.copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])¶

ファイル src を dst にコピーします。 dst がディレクトリの場合、 src はそこへ同じ名前でコピーされます; そうでない場合は、ファイル名として扱われます。(もしファイルが存在するなら、容赦無く上書きされます。) 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 が真の時にはコピーされることになった)場合には真です。

distutils.file_util.move_file(src, dst[, verbose, dry_run])¶: ファイル src を dst に移動します。もし dst がディレクトリなら、ファイルはそのディレクトリに同じ名前で移動されます。そうでなければ、 src は dst に単にリネームされます。新しいファイルの名前を返します。

警告

Unix ではデバイスをまたがる移動は copy_file() を利用して扱っています。他のシステムではどうでしょう？

distutils.file_util.write_file(filename, contents)¶: filename を作成し、 contents (行末文字がない文字列のシーケンス)を書き込みます。

9.11. `distutils.util` --- その他のユーティリティ関数¶

このモジュールは他のユーティリティモジュールにあわないものを提供しています。

distutils.util.get_platform()¶

現在のプラットフォームを示す文字列を返します。これはプラットフォーム依存のビルドディレクトリやプラットフォーム依存の配布物を区別するために使われます。典型的には、('os.uname()' のように) OSの名前とバージョン、アーキテクチャを含みますが、厳密にはOSに依存します。例えば Linux ではカーネルのバージョンはそれほど重要ではありません。

返される値の例:

linux-i586
linux-alpha
solaris-2.6-sun4u

POSIX でないプラットフォームでは、今のところ単に sys.platform が返されます。

macOS システムでは、 OS バージョンは、現在のOSバージョンではなく、実行するバイナリの最小バージョンを表しています。 (これは、Python をビルドするときの MACOSX_DEPLOYMENT_TARGET の値です。)

macOS のユニバーサルバイナリビルドでは、アーキテクチャの値は現在のプロセッサではなく、ユニバーサルバイナリの状態を表しています。32bit ユニバーサルバイナリではアーキテクチャは fat で、64bit ユニバーサルバイナリではアーキテクチャは fat64 で、4-way ユニバーサルバイナリではアーキテクチャは universal になります。Python 2.7 と Python 3.2 から 3-way ユニバーサルバイナリ (ppc, i386, x86_64) には fat3 が i386 と x86_64 ユニバーサルバイナリには intel が使われるようになりました

macOS で返される値の例:

macosx-10.3-ppc
macosx-10.3-fat
macosx-10.5-universal
macosx-10.6-intel

AIX の場合、 Python 3.9 以降のバージョンでは "aix" に続く追加のフィールド ('-' で連結されます) として AIX のバージョン、リリースおよびテクノロジー・レベル (第1フィールド)、ビルド作成日 (第2フィールド)、ビットサイズ (第3フィールド) を含む文字列を返します。 Python 3.8 以前のバージョンでは追加のフィールドとして AIX のバージョンとリリースの1つだけを含む文字列を返していました。

AIX における戻り値の例:

aix-5307-0747-32 # AIX oslevel -s: 5300-07-00-0000 の32ビットビルド
aix-7105-1731-64 # AIX oslevel -s: 7100-05-01-1731 の64ビットビルド
aix-7.2 # Python 3.8 以前のレガシー形式

バージョン 3.9 で変更: AIX プラットフォームの文字列形式はバージョンとリリース情報に加えて、テクノロジー・レベル、ビルド作成日、および ABI のビットサイズを含むようになりました。

distutils.util.convert_path(pathname)¶: 'pathname' をファイルシステムで利用できる名前にして返します。すなわち、'/'で分割し、現在のディレクトリセパレータで接続しなおします。セットアップスクリプト中のファイル名はUnixスタイルで提供され、実際に利用する前に変換する必要があるため、この関数が必要になります。もし pathname の最初または最後がスラッシュの場合、Unix的でないシステムでは ValueError が起きます。

distutils.util.change_root(new_root, pathname)¶: pathname の前に new_root を追加したものを返します。もし pathname が相対パスなら、 os.path.join(new_root,pathname) と等価です。そうでなければ、 pathname を相対パスに変換したあと接続します。これはDOS/Windows ではトリッキーな作業になります。

distutils.util.check_environ()¶

'os.environ'に、ユーザがconfigファイル、コマンドラインオプションなどで利用できることを保証している環境変数があることを確認します。現在は以下のものが含まれています:

HOME - ユーザのホームディレクトリ (Unix のみ)
PLAT - ハードウェアとOSを含む現在のプラットフォームの説明。 (get_platform() を参照)

distutils.util.subst_vars(s, local_vars)¶

shell/Perlスタイルの変数置換を s について行います。全ての $ に名前が続いたものは変数とみなされ、辞書 local_vars でみつかった値に置換されます。 local_vars で見つからなかった場合には os.environ で置換されます。 os.environ は最初にある値を含んでいることをチェックされます: check_environ() を参照。 local_vars or os.environ のどちらにも値が見つからなかった場合、 ValueError を起こします。

これは完全な文字列挿入関数ではないことに注意してください。 $variable の名前には大小英字、数字、アンダーバーだけを含むことができます。 { } や ( ) を使った引用形式は利用できません。

distutils.util.split_quoted(s)¶: 文字列をUnixのシェルのようなルール(引用符やバックスラッシュの扱い)で分割します。つまり、バックスラッシュでエスケープされるか、引用符で囲まれていなければ各語はスペースで区切られます。一重引用符と二重引用符は同じ意味です。引用符もバックスラッシュでエスケープできます。 2文字でのエスケープシーケンスに使われているバックスラッシュは削除され、エスケープされていた文字だけが残ります。引用符は文字列から削除されます。語のリストが返ります。

distutils.util.execute(func, args[, msg=None, verbose=0, dry_run=0])¶: 外部に影響するいくつかのアクション(たとえば、ファイルシステムへの書き込み)を実行します。そのようなアクションは dry_run フラグで無効にする必要があるので特別です。この関数はその繁雑な処理を行います。関数と引数のタプル、(実行する「アクション」をはっきりさせるための)表示に使われる任意のメッセージを渡してください。

distutils.util.strtobool(val)¶

真偽値をあらわす文字列を真(1)または偽(0)に変換します。

真の値は y, yes, t, true, on そして 1 です。偽の値は n, no, f, false, off そして 0 です。 val が上のどれでもない時は ValueError を起こします。

distutils.util.byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])¶

Python ソースファイル群をバイトコンパイルして __pycache__ サブディレクトリ内に .pyc ファイルを出力します。(PEP 3147 と PEP 488 を参照) py_files はコンパイルするファイルのリストです; .py で終わらないファイルは単にスキップされます。 optimize は次のうちの 1 つでなければなりません:

0 - 最適化しない
1 - 通常の最適化 (python -O のように)
2 - さらに最適化 (python -OO のように)

もし force が真なら、全てのファイルがタイムスタンプに関係なく再コンパイルされます。

バイトコードファイルにエンコードされるソースファイル名は、デフォルトでは py_files が使われます。これを prefix と basedir で変更することができます。 prefix はそれぞれのソースファイル名から削除される文字列で、 base_dir は(prefix を削除したあと)先頭に追加されるディレクトリ名です。任意に prefix と base_dir のどちらか、両方を与える(与えない)ことができます。

もし dry_run が真なら、ファイルシステムに影響することは何もされません。

バイトコンパイルは現在のインタプリタプロセスによって標準の py_compile モジュールを使って直接行われるか、テンポラリスクリプトを書いて間接的に行われます。通常は byte_compile() に直接かそうでないかをまかせます (詳細についてはソースをごらんください)。 direct フラグは関節モードで作成されたスクリプトで使用されます。何をやっているか理解していない時は None のままにしておいてください。

バージョン 3.2.3 で変更: カレントディレクトリにタグなしでファイルを作る代わりに、 __pycache__ サブディレクトリに import magic tag を使ってその名前で .pyc ファイルを作成します。

バージョン 3.5 で変更: PEP 488 に従って .pyc ファイルを作成します。

distutils.util.rfc822_escape(header)¶: RFC 822 ヘッダに含められるよう加工した header を返します。改行のあとには8つのスペースが追加されます。この関数は文字列に他の変更はしません。

9.12. `distutils.dist` --- Distribution クラス¶

このモジュールは、ビルド/インストール/配布するモジュールディストリビューションを表す Distribution クラスを提供します。

9.13. `distutils.extension` --- Extension クラス¶

このモジュールは Extension クラスを提供します。 C/C++拡張モジュールをセットアップスクリプトで表すために使われます。

9.14. `distutils.debug` --- Distutils デバッグモード¶

このモジュールはDEBUGフラグを提供します。

9.15. `distutils.errors` --- Distutils 例外¶

distutilsのモジュールで使用される例外を提供します。 distutilsのモジュールは標準的な例外を起こします。特に、 SystemExit はエンドユーザによる失敗(コマンドライン引数の間違いなど)で起きます。

このモジュールは from ... import * で安全に使用することができます。このモジュールは Distutils ではじまり、 Error で終わるシンボルしかexportしません。

9.16. `distutils.fancy_getopt` --- 標準 getopt モジュールのラッパ¶

このモジュールは以下の機能を標準の getopt モジュールに追加するラッパを提供します:

短いオプションと長いオプションを関連づけます
オプションはヘルプ文字列なので、 fancy_getopt() に完全な利用方法サマリを作らせることもできます
オプションは渡されたオブジェクトの属性を設定します。
真偽値をとるオプションは "負のエイリアス" を持ちます。--- たとえば --quiet の "負のエイリアス" が --verbose の場合、コマンドラインで --quiet を指定すると verbose は偽になります。

distutils.fancy_getopt.fancy_getopt(options, negative_opt, object, args)¶: ラッパ関数。 options は FancyGetopt のコンストラクタで説明されている (long_option, short_option, help_string) の3要素タプルのリストです。 negative_opt はオプション名からオプション名のマッピングになっている辞書で、キー、値のどちらも options リストに含まれている必要があります。 object は値を保存するオブジェクト(FancyGetopt クラスの getopt() メソッドを参照してください)です。 args は引数のリストです。 args として None を渡すと、 sys.argv[1:] が使われます。

distutils.fancy_getopt.wrap_text(text, width)¶: text を width 以下の幅で折り返します。

class distutils.fancy_getopt.FancyGetopt([option_table=None])¶

option_table は 3つ組タプルのリストです。 (long_option, short_option, help_string)

もしオプションが引数を持つなら、 long_option に '=' を追加する必要があります。 short_option は一文字のみで、 ':' はどの場合にも不要です。 long_option に対応する short_option がない場合、 short_option は None にしてください。全てのオプションタプルは長い形式のオプションを持つ必要があります。

FancyGetopt クラスは以下のメソッドを提供します:

FancyGetopt.getopt([args=None, object=None])¶

argsのコマンドラインオプションを解析します。 object に属性として保存します。

もし args が None もしくは与えられない場合には、 sys.argv[1:] を使います。もし object が None もしくは与えられない場合には、新しく OptionDummy インスタンスを作成し、オプションの値を保存したのち (args, object) のタプルを返します。もし object が提供されていれば、その場で変更され、 getopt() は args のみを返します。どちらのケースでも、返された args は渡された args リスト(これは変更されません)の変更されたコピーです。

FancyGetopt.get_option_order()¶: 直前に実行された getopt() が処理した (option, value) タプルのリストを返します。 getopt() がまだ呼ばれていない場合には RuntimeError を起こします。

FancyGetopt.generate_help([header=None])¶

この FancyGetopt オブジェクトのオプションテーブルからヘルプテキスト(出力の一行に対応する文字列のリスト)を生成します。

もし与えられていれば、 header をヘルプの先頭に出力します。

9.17. `distutils.filelist` --- FileList クラス¶

このモジュールはファイルシステムを見て、ファイルのリストを構築するために使われる FileList クラスを提供します。

9.18. `distutils.log` --- シンプルな PEP 282 形式のロギング¶

9.19. `distutils.spawn` --- サブプロセスの生成¶

このモジュールは spawn() 関数を提供します。これは様々なプラットフォーム依存の他プログラムをサブプロセスとして実行する関数に対するフロントエンドになっています。与えられた実行ファイルの名前からパスを探索する find_executable() 関数も提供しています。

9.20. `distutils.sysconfig` --- システム設定情報¶

バージョン 3.10 で非推奨: distutils.sysconfig has been merged into sysconfig.

distutils.sysconfig モジュールでは、 Python の低水準の設定情報へのアクセス手段を提供しています。アクセスできる設定情報変数は、プラットフォームと設定自体に大きく左右されます。また、特定の変数は、使っているバージョンの Python のビルドプロセスに左右されます; こうした変数は、 Unix システムでは、 Makefile や Python と一緒にインストールされる設定ヘッダから探し出されます。設定ファイルのヘッダは、2.2 以降のバージョンでは pyconfig.h 、それ以前のバージョンでは config.h です。

他にも、 distutils パッケージの別の部分を操作する上で便利な関数がいくつか提供されています。

distutils.sysconfig.PREFIX¶: os.path.normpath(sys.prefix) の返り値です。

distutils.sysconfig.EXEC_PREFIX¶: os.path.normpath(sys.exec_prefix) の返り値です。

distutils.sysconfig.get_config_var(name)¶: ある一つの設定変数に対する値を返します。 get_config_vars().get(name) と同じです。

distutils.sysconfig.get_config_vars(...)¶: 定義されている変数のセットを返します。引数を指定しなければ、設定変数名を変数の値に対応付けるマップ型を返します。引数を指定する場合、引数の各値は文字列でなければならず、戻り値は引数に関連付けられた各設定変数の値からなるシーケンスになります。引数に指定した名前の設定変数に値がない場合、その変数に対する戻り値には None が入ります。

distutils.sysconfig.get_config_h_filename()¶: 設定ヘッダのフルパス名を返します。 Unixの場合、このヘッダファイルは configure スクリプトによって生成されるヘッダファイル名です; 他のプラットフォームでは、ヘッダは Python ソース配布物中で直接与えられています。ファイルはプラットフォーム固有のテキストファイルです。

distutils.sysconfig.get_makefile_filename()¶: Python をビルドする際に用いる Makefile のフルパスを返します。 Unixの場合、このファイルは configure スクリプトによって生成されます; 他のプラットフォームでは、この関数の返す値の意味は様々です。有意なファイル名を返す場合、ファイルはプラットフォーム固有のテキストファイル形式です。この関数は POSIX プラットフォームでのみ有用です。

The following functions are deprecated together with this module and they have no direct replacement.

distutils.sysconfig.get_python_inc([plat_specific[, prefix]])¶: C インクルードファイルディレクトリについて、一般的なディレクトリ名か、プラットフォーム依存のディレクトリ名のいずれかを返します。 plat_specific が真であれば、プラットフォーム依存のインクルードディレクトリ名を返します; plat_specific が偽か、省略された場合には、プラットフォームに依存しないディレクトリを返します。 prefix が指定されていれば、 PREFIX の代わりに用いられます。また、 plat_specific が真の場合、 EXEC_PREFIX の代わりに用いられます。

distutils.sysconfig.get_python_lib([plat_specific[, standard_lib[, prefix]]])¶: ライブラリディレクトリについて、一般的なディレクトリ名か、プラットフォーム依存のディレクトリ名のいずれかを返します。 plat_specific が真であれば、プラットフォーム依存のライブラリディレクトリ名を返します; plat_specific が偽か、省略された場合には、プラットフォームに依存しないディレクトリを返します。 prefix が指定されていれば、 PREFIX の代わりに用いられます。また、 plat_specific が真の場合、 EXEC_PREFIX の代わりに用いられます。 standard_lib が真であれば、サードパーティ製の拡張モジュールをインストールするディレクトリの代わりに、標準ライブラリのディレクトリを返します。

以下の関数は、 distutils パッケージ内の使用だけを前提にしています。

distutils.sysconfig.customize_compiler(compiler)¶

distutils.ccompiler.CCompiler インスタンスに対して、プラットフォーム固有のカスタマイズを行います。

この関数は現在のところ、Unix だけで必要ですが、将来の互換性を考慮して一貫して常に呼び出されます。この関数は様々な Unix の変種ごとに異なる情報や、Python の Makefile に書かれた情報をインスタンスに挿入します。この情報には、選択されたコンパイラやコンパイラ/リンカのオプション、そして共有オブジェクトを扱うためにリンカに指定する拡張子が含まれます。

この関数はもっと特殊用途向けで、Python 自体のビルドプロセスでのみ使われるべきです。

distutils.sysconfig.set_python_build()¶: distutils.sysconfig モジュールに、モジュールが Python のビルドプロセスの一部として使われることを知らせます。これによって、ファイルコピー先を示す相対位置が大幅に変更され、インストール済みの Python ではなく、ビルド作業領域にファイルが置かれるようになります。

9.21. `distutils.text_file` --- TextFile クラス¶

このモジュールは TextFile クラスを提供します。これはテキストファイルへのインターフェースを提供し、コメントの削除、空行の無視、バックスラッシュでの行の連結を任意に行えます。

class distutils.text_file.TextFile([filename=None, file=None, **options])¶

このクラスはファイルのようなオブジェクトを提供します。これは行指向のテキストファイルを処理する時に共通して必要となる処理を行います: (# がコメント文字なら)コメントの削除、空行のスキップ、 (行末のバックスラッシュでの)改行のエスケープによる行の連結、先頭/末尾の空白文字の削除。これらは全て独立して任意に設定できます。

クラスは warn() メソッドを提供しており、物理行つきの警告メッセージを生成することができます。この物理行は論理行が複数の物理行にまたがっていても大丈夫です。また unreadline() メソッドが一行先読みを実装するために提供されています。

TextFile のインスタンスは filename, file,またはその両方をとって作成されます。両方が None の場合 RuntimeError が起きます。 filename は文字列、 file はファイルオブジェクト(または readline() と close() のメソッドを提供する何か) である必要があります。 TextFile が生成する警告メッセージに含めることができるので、 filename を与えることが推奨されます、もし file が提供されなければ、 TextFile は組み込みの open() を利用して自分で作成します。

オプションは全て真偽値で、 readline() で返される値に影響します。

オプション名	description	default
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 を返し、空文字列を返したときは空行(または全て空白文字の行)です。

open(filename)¶: 新しいファイル filename を開きます。これはコンストラクタ引数の file と filename を上書きします。

close()¶: 現在のファイルを閉じ、(ファイル名や現在の行番号を含め)現在のファイルについての情報を全て消します。

warn(msg[, line=None])¶: 標準エラー出力に現在のファイルの論理行に結びついた警告メッセージを出力します。もし現在の論理行が複数の物理行に対応するなら、警告メッセージは以下のように全体を参照します: "lines 3-5" 。もし line が与えられていれば、現在の行番号を上書きします; 物理行のレンジをあらわすリストまたはタプル、もしくはある物理行をあらわす整数のどれでも与えられます。

readline()¶: 現在のファイル(または unreadline() で"unread"を直前に行っていればバッファ)から論理行を1行読み込んで返します。もし join_lines オプションが真なら、このメソッドは複数の物理行を読み込んで接続した文字列を返します。現在の行番号を更新します。そのため readline() のあとに warn() を呼ぶと丁度読んだ行についての警告を出します。 rstrip_ws が真で、 strip_blanks が偽のとき空文字列が返るので、ファイルの終端では None を返します。

readlines()¶: 現在のファイルで残っている全ての論理行のリストを読み込んで返します。行番号を、ファイルの最後の行に更新します。

unreadline(line)¶: line (文字列)を次の readline() 用に、内部バッファにpushします。行の先読みを必要とするパーサを実装する時に便利です。 unreadline() で"unread"された行は readline() で読み込む際に再度処理(空白の除去など)されません。もし unreadline() を、 readline() を呼ぶ前に複数回実行すると、最後にunreadした行から返されます。

9.22. `distutils.version` --- バージョン番号クラス¶

9.23. `distutils.cmd` --- Distutils コマンドの抽象クラス¶

このモジュールは抽象ベースクラス Command を提供します。

class distutils.cmd.Command(dist)¶

コマンドクラスを定義するための抽象ベースクラス --- distutilsの「働きバチ」 --- です。コマンドクラスは options とよばれるローカル変数を持ったサブルーチンと考えることができます。オプションは initialize_options() で宣言され、 finalize_options() で定義さ(最終的な値を与えら)れます。どちらも全てのコマンドクラスで実装する必要があります。この2つの区別は必要です。なぜならオプションの値は外部(コマンドライン、設定ファイルなど)から来るかもしれず、他のオプションに依存しているオプションは外部の影響を処理した後で計算される必要があるからです。そのため finalize_options() が存在します。サブルーチンの本体は全ての処理をオプションの値にもとづいて行う run() メソッドで、これも全てのコマンドクラスで実装される必要があります。

このクラスのコンストラクタは、 Distribution インスタンス dist 1 つを引数に取ります。

9.24. 新しいDistutilsコマンドの作成¶

このセクションではDistutilsの新しいコマンドを作成する手順の概要をしめします。

新しいコマンドは distutils.command パッケージ中のモジュールに作られます。 command_template というディレクトリにサンプルのテンプレートがあります。このファイルを実装しようとしているコマンドと同名の新しいモジュールにコピーしてください。このモジュールはモジュール(とコマンド)と同じ名前のクラスを実装する必要があります。そのため、 peel_banana コマンド(ユーザは setup.py peel_banana と実行できます)を実装する際には、 command_template を distutils/command/peel_banana.py にコピーし、 distutils.cmd.Command のサブクラス peel_banana クラスを実装するように編集してください。

Command のサブクラスは以下のメソッドを実装する必要があります。

Command.initialize_options()¶: このコマンドがサポートする全てのオプションのデフォルト値を設定します。これらのデフォルトは他のコマンドやセットアップスクリプト、設定ファイル、コマンドラインによって上書きされるかもしれません。そのためオプション間の依存関係を記述するには適切な場所ではありません。一般的に initialize_options() は単に self.foo = None のような定義だけを行います。

Command.finalize_options()¶: このコマンドがサポートする全てのオプションの最終的な値を設定します。これは可能な限り遅く呼び出されます。つまりコマンドラインや他のコマンドによるオプションの代入のあとに呼び出されます。そのため、オプション間の依存関係を記述するのに適した場所です。もし foo が bar に依存しており、かつまだ foo が initialize_options() で定義された値のままなら、 foo を bar から代入しても安全です。

Command.run()¶: コマンドの本体です。実行するべきアクションを実装しています。 initialize_options() で初期化され、他のコマンドされ、セットアップスクリプト、コマンドライン、設定ファイルでカスタマイズされ、 finalize_options() で設定されたオプションがアクションを制御します。端末への出力とファイルシステムとのやりとりは全て run() が行います。

Command.sub_commands¶

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 コマンドです。

9.25. `distutils.command` --- Distutils 各コマンド¶

9.26. `distutils.command.bdist` --- バイナリインストーラの構築¶

9.27. `distutils.command.bdist_packager` --- パッケージの抽象ベースクラス¶

9.28. `distutils.command.bdist_dumb` --- "ダム"インストーラを構築¶

9.29. `distutils.command.bdist_rpm` --- Redhat RPMとSRPM形式のバイナリディストリビューションを構築¶

9.30. `distutils.command.sdist` --- ソース配布物の構築¶

9.31. `distutils.command.build` --- パッケージ中の全ファイルを構築¶

9.32. `distutils.command.build_clib` --- パッケージ中のCライブラリを構築¶

9.33. `distutils.command.build_ext` --- パッケージ中の拡張を構築¶

9.34. `distutils.command.build_py` --- パッケージ中の.py/.pyc ファイルを構築¶

class distutils.command.build_py.build_py¶

class distutils.command.build_py.build_py_2to3¶

インストールされる各 .py ファイル上で 2to3 変換ライブラリをさらに実行する build_py の代替実装。Python 2.x と 3.x の両方で動くことを意図した配布物において setup.py ファイルの中でこれを使用するためには、setup.py に次のように付け加えてください:

try:
    from distutils.command.build_py import build_py_2to3 as build_py
except ImportError:
    from distutils.command.build_py import build_py

そして:

cmdclass = {'build_py': build_py}

を setup() の呼び出しに追加してください。

9.35. `distutils.command.build_scripts` --- パッケージ中のスクリプトを構築¶

9.36. `distutils.command.clean` --- パッケージのビルドエリアを消去¶

このコマンドは build とそのサブコマンドによって作られた、中間コンパイルオブジェクトファイルのような一時ファイルを削除します。 --all オプションとともに使うと、 build ディレクトリ全体を削除します。

in place でビルドしたモジュールは、それは build ディレクトリにいないので、削除されません。

9.37. `distutils.command.config` --- パッケージの設定¶

9.38. `distutils.command.install` --- パッケージのインストール¶

9.39. `distutils.command.install_data` --- パッケージ中のデータファイルをインストール¶

9.40. `distutils.command.install_headers` --- パッケージから C/C++ ヘッダファイルをインストール¶

9.41. `distutils.command.install_lib` --- パッケージからライブラリファイルをインストール¶

9.42. `distutils.command.install_scripts` --- パッケージからスクリプトファイルをインストール¶

9.43. `distutils.command.register` --- モジュールをPython Package Indexに登録する¶

register コマンドはパッケージをPython Package Index に登録します。この詳細は PEP 301 に記述されています。

9.44. `distutils.command.check` --- パッケージのメタデータをチェックする¶

check コマンドは、パッケージのメタデータに対していくつかのテストを行ないます。例えば、すべての必要なメタデータが setup() 関数に渡された引数として提供されることを確認します。

9. API リファレンス¶

9.1. distutils.core --- Distutils のコア機能¶

9.2. distutils.ccompiler --- CCompiler ベースクラス¶

9.3. distutils.unixccompiler --- Unix C コンパイラ¶

9.4. distutils.msvccompiler --- Microsoft コンパイラ¶

9.5. distutils.bcppcompiler --- Borland コンパイラ¶

9.6. distutils.cygwincompiler --- Cygwin コンパイラ¶

9.7. distutils.archive_util --- アーカイブユーティリティ¶

9.8. distutils.dep_util --- 依存関係のチェック¶

9.9. distutils.dir_util --- ディレクトリツリーの操作¶

9.10. distutils.file_util --- 1ファイルの操作¶

9.11. distutils.util --- その他のユーティリティ関数¶

9.12. distutils.dist --- Distribution クラス¶

9.13. distutils.extension --- Extension クラス¶

9.14. distutils.debug --- Distutils デバッグモード¶

9.15. distutils.errors --- Distutils 例外¶

9.16. distutils.fancy_getopt --- 標準 getopt モジュールのラッパ¶

9.17. distutils.filelist --- FileList クラス¶

9.18. distutils.log --- シンプルな PEP 282 形式のロギング¶

9.19. distutils.spawn --- サブプロセスの生成¶

9.20. distutils.sysconfig --- システム設定情報¶

9.21. distutils.text_file --- TextFile クラス¶

9.22. distutils.version --- バージョン番号クラス¶

9.23. distutils.cmd --- Distutils コマンドの抽象クラス¶

9.24. 新しいDistutilsコマンドの作成¶

9.25. distutils.command --- Distutils 各コマンド¶

9.26. distutils.command.bdist --- バイナリインストーラの構築¶

9.27. distutils.command.bdist_packager --- パッケージの抽象ベースクラス¶

9.28. distutils.command.bdist_dumb --- "ダム"インストーラを構築¶

9.29. distutils.command.bdist_rpm --- Redhat RPMとSRPM形式のバイナリディストリビューションを構築¶

9.30. distutils.command.sdist --- ソース配布物の構築¶

9.31. distutils.command.build --- パッケージ中の全ファイルを構築¶

9.32. distutils.command.build_clib --- パッケージ中のCライブラリを構築¶

9.33. distutils.command.build_ext --- パッケージ中の拡張を構築¶

9.34. distutils.command.build_py --- パッケージ中の.py/.pyc ファイルを構築¶

9.35. distutils.command.build_scripts --- パッケージ中のスクリプトを構築¶

9.36. distutils.command.clean --- パッケージのビルドエリアを消去¶

9.37. distutils.command.config --- パッケージの設定¶

9.38. distutils.command.install --- パッケージのインストール¶

9.39. distutils.command.install_data --- パッケージ中のデータファイルをインストール¶

9.40. distutils.command.install_headers --- パッケージから C/C++ ヘッダファイルをインストール¶

9.41. distutils.command.install_lib --- パッケージからライブラリファイルをインストール¶

9.42. distutils.command.install_scripts --- パッケージからスクリプトファイルをインストール¶

9.43. distutils.command.register --- モジュールをPython Package Indexに登録する¶

9.44. distutils.command.check --- パッケージのメタデータをチェックする¶