10. API リファレンス¶
10.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 パッケージのカテゴリのリスト a list of strings; valid classifiers are listed on 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 拡張で起きたビルド失敗によってビルドプロセスを中断せず、単にその拡張を無視して処理を進めるように指定します。 ブール値
-
class
distutils.core.
Distribution
¶ Distribution
はPythonソフトウェアパッケージをどのようにビルド、インストール、パッケージするかを定義する。Distribution
のコンストラクタが取りうるキーワード引数のリストに関しては、setup()
関数を見てください。setup()
はDistribution
のインスタンスを作ります。
10.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()
メソッドと同じです。
共有ライブラリをリンクします。 output_libname は出力先のライブラリ名です。 objects はリンクされるオブジェクトのファイル名のリストです。他の引数は
link()
メソッドと同じです。
共有オブジェクトをリンクします。 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 はファイル名のリストです。
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 を標準エラー出力に書き出します。
-
10.3. distutils.unixccompiler
— Unix C コンパイラ¶
このモジュールは UnixCCompiler
クラスを提供します。 CCompiler
クラスのサブクラスで、典型的なUnixスタイルのコマンドラインCコンパイラを扱います:
- マクロは
-Dname[=value]
で定義されます - マクロは
-Uname
で削除されます - インクルードファイルの探索ディレクトリは
-Idir
で指定されます - ライブラリは
-llib
で指定されます - ライブラリの探索ディレクトリは
-Ldir
で指定されます - コンパイルは cc (またはそれに似た) 実行ファイルに、
-c
オプションをつけて実行します:.c
を.o
にコンパイルします - 静的ライブラリは ar コマンドで処理されます (ranlib を使うかもしれません)
- 共有ライブラリのリンクは cc
-shared
で処理されます
10.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 です。 AMD64 と Itanium バイナリは Platform SDK を利用して作成されました。
MSVCCompiler
は大体正しいコンパイラ、リンカその他を選びます。この選択を上書きするためには、環境変数 DISTUTILS_USE_SDK と MSSdk の両方を設定する必要があります。 MSSdk は現在の環境をセットアップした SetEnv.Cmd
スクリプト、もしくは環境変数がSDKをインストールした時に登録されたものであることを示します。 DISTUTILS_USE_SDK はdistutilsのユーザーが明示的に MSVCCompiler
が選んだコンパイラを上書きすることを示します。
10.5. distutils.bcppcompiler
— Borland コンパイラ¶
このモジュールは BorlandCCompiler
クラスを提供します。抽象クラス CCompiler
の具象クラスでBorland C++ コンパイラ向けです。
10.6. distutils.cygwincompiler
— Cygwin コンパイラ¶
このモジュールは CygwinCCompiler
クラスを提供します。 UnixCCompiler
のサブクラスで Cygwinに移植されたWindows用の GNU C コンパイラ向けです。さらに Mingw32CCompiler
クラスを含んでおり、これは mingw32 向けに移植された GCC (cygwinの no-cygwin モードと同じ)向けです。
10.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
形式のサポートが追加されました。
10.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"モードで便利です: 入力がないのでコマンドは実行できませんが実際に実行しようとしていないので問題になりません)。
10.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()
のものと同じです。src にあるファイルで
.nfs
から始まるものは対象から外されます (これらのファイルについての情報は NFS FAQ page の回答 D2 にあります) 。バージョン 3.3.1 で変更: NFS ファイルは無視されます。
-
distutils.dir_util.
remove_tree
(directory[, verbose=0, dry_run=0])¶ 再帰的に directory とその下の全ファイルを削除します。エラーは無視されます (verbose が真の時は
sys.stdout
に出力されます)。
10.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 (行末文字がない文字列のシーケンス)を書き込みます。
10.11. distutils.util
— その他のユーティリティ関数¶
このモジュールは他のユーティリティモジュールにあわないものを提供しています。
-
distutils.util.
get_platform
()¶ 現在のプラットフォームを示す文字列を返します。これはプラットフォーム依存のビルドディレクトリやプラットフォーム依存の配布物を区別するために使われます。典型的には、('os.uname()' のように) OSの名前とバージョン、アーキテクチャを含みますが、厳密にはOSに依存します。たとえば IRIXではアーキテクチャはそれほど重要ではありません(IRIXはSGIのハードウェアだけで動作する)が、 Linuxではカーネルのバージョンはそれほど重要ではありません。
返される値の例:
linux-i586
linux-alpha
solaris-2.6-sun4u
irix-5.3
irix64-6.2
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 で返される値の例:
macosx-10.3-ppc
macosx-10.3-fat
macosx-10.5-universal
macosx-10.6-intel
-
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 oros.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 が真なら、全てのファイルがタイムスタンプに関係なく再コンパイルされます。
バイトコード(bytecode)ファイルにエンコードされるソースファイル名は、デフォルトでは 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
ファイルを作成します。
10.12. distutils.dist
— Distribution クラス¶
このモジュールは、ビルド/インストール/配布するモジュールディストリビューションを表す Distribution
クラスを提供します。
10.13. distutils.extension
— Extension クラス¶
このモジュールは Extension
クラスを提供します。 C/C++拡張モジュールをセットアップスクリプトで表すために使われます。
10.14. distutils.debug
— Distutils デバッグモード¶
このモジュールはDEBUGフラグを提供します。
10.15. distutils.errors
— Distutils 例外¶
distutilsのモジュールで使用される例外を提供します。 distutilsのモジュールは標準的な例外を起こします。特に、 SystemExit はエンドユーザによる失敗(コマンドライン引数の間違いなど)で起きます。
このモジュールは from ... import *
で安全に使用することができます。このモジュールは Distutils
ではじまり、 Error
で終わるシンボルしかexportしません。
10.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 をヘルプの先頭に出力します。
10.17. distutils.filelist
— FileList クラス¶
このモジュールはファイルシステムを見て、ファイルのリストを構築するために使われる FileList
クラスを提供します。
10.18. distutils.log
— シンプルな PEP 282 スタイルのロギング¶
10.19. distutils.spawn
— サブプロセスの生成¶
このモジュールは spawn()
関数を提供します。これは様々なプラットフォーム依存の他プログラムをサブプロセスとして実行する関数に対するフロントエンドになっています。与えられた実行ファイルの名前からパスを探索する find_executable()
関数も提供しています。
10.20. distutils.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 プラットフォームでのみ有用です。
-
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 ではなく、ビルド作業領域にファイルが置かれるようになります。
10.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した行から返されます。
-
10.22. distutils.version
— バージョン番号クラス¶
10.23. distutils.cmd
— Distutils コマンドの抽象クラス¶
このモジュールは抽象ベースクラス Command
を提供します。
-
class
distutils.cmd.
Command
(dist)¶ コマンドクラスを定義するための抽象ベースクラス — distutilsの「働きバチ」 — です。コマンドクラスは options とよばれるローカル変数を持ったサブルーチンと考えることができます。オプションは
initialize_options()
で宣言され、finalize_options()
で定義さ(最終的な値を与えら)れます。どちらも全てのコマンドクラスで実装する必要があります。この2つの区別は必要です。なぜならオプションの値は外部(コマンドライン、設定ファイルなど)から来るかもしれず、他のオプションに依存しているオプションは外部の影響を処理した後で計算される必要があるからです。そのためfinalize_options()
が存在します。サブルーチンの本体は全ての処理をオプションの値にもとづいて行うrun()
メソッドで、これも全てのコマンドクラスで実装される必要があります。このクラスのコンストラクタは、
Distribution
インスタンス dist 1 つを引数に取ります。
10.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 コマンドです。
10.25. distutils.command
— Distutils 各コマンド¶
10.26. distutils.command.bdist
— バイナリインストーラの構築¶
10.27. distutils.command.bdist_packager
— パッケージの抽象ベースクラス¶
10.28. distutils.command.bdist_dumb
— "ダム"インストーラを構築¶
10.29. distutils.command.bdist_msi
— Microsoft Installer バイナリパッケージをビルドする¶
-
class
distutils.command.bdist_msi.
bdist_msi
¶ Windows Installer (.msi) バイナリパッケージをビルドします。
多くの場合、
bdist_msi
インストーラは Win64 のサポートが優れていて、管理者が非インタラクティブインストールできたり、グループポリシーを利用したインストールができるので、bdist_wininst
インストーラよりも良い選択です。
10.30. distutils.command.bdist_rpm
— Redhat RPMとSRPM形式のバイナリディストリビューションを構築¶
10.31. distutils.command.bdist_wininst
— Windowsインストーラの構築¶
10.32. distutils.command.sdist
— ソース配布物の構築¶
10.33. distutils.command.build
— パッケージ中の全ファイルを構築¶
10.34. distutils.command.build_clib
— パッケージ中のCライブラリを構築¶
10.35. distutils.command.build_ext
— パッケージ中の拡張を構築¶
10.36. 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() の呼び出しに追加してください。
10.37. distutils.command.build_scripts
— パッケージ中のスクリプトを構築¶
10.38. distutils.command.clean
— パッケージのビルドエリアを消去¶
このコマンドは build とそのサブコマンドによって作られた、中間コンパイルオブジェクトファイルのような一時ファイルを削除します。 --all
オプションとともに使うと、 build ディレクトリ全体を削除します。
in place でビルドしたモジュールは、それは build ディレクトリにいないので、削除されません。
10.39. distutils.command.config
— パッケージの設定¶
10.40. distutils.command.install
— パッケージのインストール¶
10.41. distutils.command.install_data
— パッケージ中のデータファイルをインストール¶
10.42. distutils.command.install_headers
— パッケージから C/C++ ヘッダファイルをインストール¶
10.43. distutils.command.install_lib
— パッケージからライブラリファイルをインストール¶
10.44. distutils.command.install_scripts
— パッケージからスクリプトファイルをインストール¶
10.45. distutils.command.register
— モジュールをPython Package Indexに登録する¶
register
コマンドはパッケージをPython Package Index に登録します。この詳細は PEP 301 に記述されています。
10.46. distutils.command.check
— パッケージのメタデータをチェックする¶
check
コマンドは、パッケージのメタデータに対していくつかのテストを行ないます。例えば、すべての必要なメタデータが setup()
関数に渡された引数として提供されることを確認します。