pyproject.toml¶
バージョン10.0で追加。
現代のPythonパッケージには、pyproject.tomlファイルを含めることができます。このファイルは、PEP 518で最初に導入され、その後PEP 517、PEP 621、PEP 660で拡張されました。このファイルには、パッケージのビルドに使用されるビルドシステムの要件と情報が含まれています。
ビルドプロセス¶
パッケージをビルドするための全体的なプロセスは次のとおりです。
分離されたビルド環境を作成します。
ビルド環境にビルド依存関係を取り込みます。
必要に応じて、パッケージのメタデータを生成します。
パッケージのホイールを生成します。
ホイールは、必要に応じてインストールを実行するために使用できます。
ビルドの分離¶
このインターフェースを使用してパッケージをビルドするために、pipは分離された環境を使用します。つまり、pipはビルド時のPython依存関係を一時ディレクトリにインストールし、ビルドコマンドのためにsys.pathに追加します。これにより、ビルド要件がユーザーのランタイム環境とは独立して処理されるようになります。
たとえば、ビルドに古いバージョンのsetuptoolsが必要なプロジェクトでも、ユーザーが新しいバージョンをインストールしている場合でも（そして、そのバージョンを黙って置き換えることなく）インストールできます。
ビルド時の依存関係¶
PEP 518で導入された、pyproject.tomlファイルのbuild-system.requiresキーは、パッケージのビルド時の依存関係の要件指定子のリストです。
[build-system]
requires = ["setuptools ~= 58.0", "cython ~= 0.29.0"]
また、ビルドバックエンドが、PEP 517のget_requires_for_build_wheelフックを使用して、動的に計算されたビルド依存関係を提供することもできます。このフックはpipによって呼び出され、このフックが記述する依存関係もビルド環境にインストールされます。たとえば、新しいバージョンのsetuptoolsは、このフックを介してsetup_requiresの内容をpipに公開します。
ビルド時の要件指定子はPEP 508に従うため、URLを使用してパッケージを参照できます。例えば
[build-system]
requires = ["setuptools @ git+https://github.com/pypa/setuptools.git@main"]
メタデータ生成¶
バージョン19.0で追加。
ビルド環境が作成され、ビルド時の依存関係が取り込まれると、pipは通常、パッケージに関するメタデータ（名前、バージョン、依存関係など）を必要とします。
PEP 517のprepare_metadata_for_build_wheelフックがビルドバックエンドによって提供されている場合、それがパッケージのメタデータの生成に使用されます。それ以外の場合は、（以下で説明するように）ホイールが生成され、そのようなホイールに含まれるメタデータが使用されます。
ホイールの生成¶
バージョン19.0で追加。
ホイールを生成するために、pipは、ビルドバックエンドによって提供される必要があるPEP 517のbuild_wheelフックを使用します。ビルドバックエンドはホイールを生成します。これには、C / C ++（または他の言語）で記述された拡張コードのコンパイルが含まれる場合があります。
このメカニズムを使用して生成されたホイールは、将来のインストールを高速化するために、再利用のためにキャッシュできます。
編集可能なインストール¶
バージョン21.3で追加。
編集可能なインストールを実行するために、pipは、ビルドバックエンドによって提供される必要があるPEP 660のbuild_wheel_for_editableフックを使用します。このメカニズムを使用して生成されたホイールはキャッシュされません。
バックエンド構成¶
ビルドバックエンドは、ビルドの処理方法を変更できる構成設定を受け入れる機能があります。これらの設定は、一連のkey=valueペアの形式を取ります。ユーザーは、--config-settingsコマンドラインオプション（複数の設定を指定するために複数回指定できます）を使用して構成設定を提供できます。
提供された構成設定は、すべてのバックエンドフック呼び出しに渡されます。
--config-settingsコマンドラインオプション（または同等の環境変数または構成ファイルエントリ）を介して提供される構成設定は、pipコマンドライン引数として明示的に提供される要件のビルドに渡されます。それらは、依存関係のビルド、または要件ファイルで提供される要件のビルドには渡されません。
ビルド出力¶
PEP 517で説明されているように、出力が正しいエンコーディングになっていることを保証するのはビルドバックエンドの責任です。これには、pipがレガシービルドで抱えているのと同じ課題に対処することが含まれる可能性があります。
フォールバック動作¶
警告
次のスニペットは、フォールバック動作についてのみ説明しています。setuptoolsで使用するpyproject.tomlの有効な例については、setuptoolsのドキュメントを参照してください。
プロジェクトにbuild-systemセクションを含むpyproject.tomlファイルがない場合、次のバックエンド設定があると見なされます。
[build-system]
requires = ["setuptools>=40.8.0"]
build-backend = "setuptools.build_meta:__legacy__"
プロジェクトにbuild-systemセクションがあるが、build-backendがない場合、
setuptoolsをビルド要件として含めることが期待されます。setuptoolsの利用可能なバージョンが十分な新しさでない場合はエラーが報告されます。setuptools.build_meta:__legacy__ビルドバックエンドが使用されます。
ビルド分離の無効化¶
--no-build-isolation フラグを使用することで、これを無効化できます。このフラグを使用するユーザーは、必要なすべてのビルド時依存関係がインストールされていることを含め、ビルド環境が適切に管理されていることを保証する責任があります。pipはこのフラグが渡された場合、ビルド時依存関係を管理しないためです。
歴史的な注記¶
この機能が段階的に導入されたため、いくつかの注目すべき変更と改善がありました。
setuptools 40.8.0 は、PEP 517 バックエンドを最初に提供する setuptools のバージョンです。このバックエンドは、
setup.pyを直接実行する動作をほぼ模倣しています。pip 18.0 より前の pip は、ホイールからのビルド要件のインストールのみをサポートしており、環境マーカーとエクストラの使用をサポートしていません（バージョン指定子のみが尊重されます）。
pip 18.1 より前のバージョンでは、
.pthファイルを使用したビルド依存関係は適切にサポートされていませんでした。その結果、名前空間パッケージは Python 3.2 以前では動作しませんでした。