概要

distutils / setuptools は私たちを長い道のりに連れて行ってくれましたが、3つの重大な問題を抱えています。 (a) 使いやすいビルド時の依存関係の宣言、自動構成、さらには DRY 準拠のバージョン番号管理などの基本的なエルゴノミクスの欠如などの重要な機能が欠けていること、 (b) 拡張が難しいため、上記の問題に対するさまざまな解決策が存在するものの、それらはしばしば風変わりで壊れやすく、維持するのに高価であること、そして (c) distutils/setuptools がユーザーや pip のようなインストールツールによって期待される標準インターフェースを提供しているため、他のものを使用することが非常に難しいことです。

以前の取り組み（例：distutils2 や setuptools 自体）は、問題 (a) および/または (b) を解決しようとしました。この提案は (c) を解決することを目指しています。

この PEP の目標は、distutils-sig を Python ビルドシステムのゲートキーパーの役割から解放することです。distutils を使用したい場合はそれで良いですし、他のものを使用したい場合は、標準化された方法を使用して簡単に行えるようにする必要があります。distutils と連携することの難しさから、現在はそのようなシステムはあまり存在しませんが、私たちが考えていることを理解するために、flit や bento を参照してください。幸いなことに、ホイールはここでの多くの難しい問題をすでに解決しており、たとえば、ビルドシステムがすべての可能なインストール構成についても知っている必要がなくなったため、ビルドシステムに必要なのは、標準に準拠したホイールと sdists を出力する方法を持つことだけです。

したがって、パッケージソースツリーおよびソースディストリビューションと対話するための新しい、比較的最小限のインターフェースをインストールツール（例：pip）に提案します。

用語と目標

ソースツリー とは、VCS チェックアウトのようなものです。この形式からインストールするための標準インターフェースが必要です。たとえば、pip install some-directory/ のような使用法をサポートするためです。

ソースディストリビューション とは、特定のソースコードのリリースを表す静的なスナップショットであり、たとえば lxml-3.4.4.tar.gz のようなものです。ソースディストリビューションは多くの目的を果たします。リリースのアーカイブ記録を提供し、大規模なコードコーパスを取り込んで処理するための事実上の標準を提供し、さまざまな言語で書かれたコード（例：コード検索）を提供し、Debian/Fedora/Conda/… などの下流のパッケージングシステムの入力として機能します。Python エコシステムでは、ソースディストリビューションは特に重要な役割を果たします。たとえば、foo.whl というディストリビューションが bar に依存していると宣言している場合、pip install bar や pip install foo が自動的に bar の sdist を見つけてダウンロードし、ビルドして結果のパッケージをインストールするケースをサポートする必要があります。

ソースディストリビューションは短縮して sdists とも呼ばれます。

ビルドフロントエンド とは、ユーザーが実行するツールであり、任意のソースツリーまたはソースディストリビューションを受け取り、それらからホイールをビルドします。実際のビルドは各ソースツリーの ビルドバックエンド によって行われます。たとえば、pip wheel some-directory/ というコマンドでは、pip がビルドフロントエンドとして機能しています。

統合フロントエンド とは、パッケージの要件セット（例：requirements.txt ファイル）を受け取り、それらの要件を満たすように作業環境を更新しようとするツールです。これには、ホイールと sdists の組み合わせを見つけてビルドし、インストールすることが含まれる場合があります。たとえば、pip install lxml==2.4.0 というコマンドでは、pip が統合フロントエンドとして機能しています。

ソースツリー

setup.py を含む既存のレガシーソースツリーフォーマットがあります。これをさらに指定することは試みません。その事実上の仕様は、distutils、setuptools、pip、およびその他のツールのソースコードとドキュメントにエンコードされています。これを setup.py スタイルと呼びます。

ここでは、PEP 518 で定義された pyproject.toml ファイルを中心とした新しいスタイルのソースツリーを定義し、そのファイルの [build-system] テーブルに build-backend という追加のキーを拡張します。以下はその例です:

[build-system]
# PEP 518 で定義されています:
requires = ["flit"]
# この PEP で定義されています:
build-backend = "flit.api:main"

build-backend は、ビルドを実行するために使用される Python オブジェクトを名前で指定する文字列です（詳細は後述します）。これは、setuptools エントリポイントと同じ module:object 構文に従ってフォーマットされています。たとえば、文字列が上記の例のように "flit.api:main" である場合、このオブジェクトは次のように実行して検索されます:

import flit.api
backend = flit.api.main

:object 部分を省略することも合法です。たとえば:

build-backend = "flit.api"

これは次のように動作します:

import flit.api
backend = flit.api

正式には、文字列は次の文法に従う必要があります:

identifier = (letter | '_') (letter | '_' | digit)*
module_path = identifier ('.' identifier)*
object_path = identifier ('.' identifier)*
entry_point = module_path (':' object_path)?

そして、module_path をインポートし、次に module_path.object_path を検索します（または object_path が欠落している場合は module_path のみ）。

モジュールパスをインポートする際には、ソースツリーを含むディレクトリを sys.path に含めない限り、検索しません（たとえば、PYTHONPATH で指定されている場合など）。Python は特定の状況で作業ディレクトリを自動的に sys.path に追加しますが、バックエンドを解決するコードはこれに影響されるべきではありません。

pyproject.toml ファイルが存在しない場合、または build-backend キーが欠落している場合、ソースツリーはこの仕様を使用しておらず、ツールは setup.py を実行するレガシー動作に戻るべきです（直接実行するか、暗黙的に setuptools.build_meta:__legacy__ バックエンドを呼び出すかのいずれかです）。

build-backend キーが存在する場合、これが優先され、ソースツリーは指定されたバックエンドの形式と慣例に従います（したがって、バックエンドが必要としない限り setup.py は不要です）。プロジェクトは、ツールがこの仕様を使用しない場合に互換性を保つために setup.py を含めることを検討するかもしれません。

この PEP は、pyproject.toml で使用する backend-path キーも定義しています。詳細は「インツリービルドバックエンド」セクションを参照してください。このキーは次のように使用されます:

[build-system]
# PEP 518 で定義されています:
requires = ["flit"]
# この PEP で定義されています:
build-backend = "local_backend"
backend-path = ["backend"]

ビルドバックエンドインターフェース

ビルドバックエンドオブジェクトは、次のフックの一部またはすべてを提供する属性を持つことが期待されます。共通の config_settings 引数については、個々のフックの後に説明します。

def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
    ...

def build_sdist(sdist_directory, config_settings=None):
    ...

def get_requires_for_build_wheel(config_settings=None):
    ...

def get_requires_for_build_wheel(config_settings):
    return ["wheel >= 0.25", "setuptools"]

def prepare_metadata_for_build_wheel(metadata_directory, config_settings=None):
    ...

def get_requires_for_build_sdist(config_settings=None):
    ...

config_settings

pip install                                           \
  --package-config CC=gcc                             \
  --global-option="--some-global-option"              \
  --build-option="--build-option1"                    \
  --build-option="--build-option2"

{
 "CC": "gcc",
 "--global-option": ["--some-global-option"],
 "--build-option": ["--build-option1", "--build-option2"],
}

ソースディストリビューション

レガシー sdist フォーマットを引き続き使用し、新しい制限を追加します。 この形式はほとんど定義されていませんが、基本的には次のようになります。 {NAME}-{VERSION}.{EXT} という名前のファイルで、{NAME}-{VERSION}/ というビルド可能なソースツリーに展開されます。従来、これらには常に setup.py スタイルのソースツリーが含まれていましたが、pyproject.toml スタイルのソースツリーも含めることができます。

統合フロントエンドは、{NAME}-{VERSION}.{EXT} という名前の sdist が {NAME}-{VERSION}-{COMPAT-INFO}.whl という名前のホイールを生成することを要求します。

PEP 517 バックエンドによってビルドされた sdists の新しい制限は次のとおりです。

• それらは .tar.gz 拡張子を持つ gzipped tar アーカイブになります。現在は zip アーカイブや他の圧縮形式の tarball は許可されていません。
• Tar アーカイブは、UTF-8 ベースのファイル名を使用する最新の POSIX.1-2001 pax tar 形式で作成する必要があります。
• sdist に含まれるソースツリーには pyproject.toml ファイルが含まれていることが期待されます。

進化的なメモ

ここでの目標の1つは、古いスタイルの sdists を新しいスタイルの sdists に変換することをできるだけ簡単にすることです。 （例：これは動的ビルド要件をサポートする1つの動機です）。理想的には、任意の「バージョン0」VCS チェックアウトにドロップして新しいものに変換できる単一の静的な pyproject.toml が存在することです。これはおそらく100％可能ではありませんが、近づくことができ、どれだけ近づいているかを追跡することが重要です…したがって、このセクションがあります。

大まかな計画は次のようになります。フック言語を理解し、setup.py への呼び出しに変換するビルドシステムパッケージ（setuptools_pypackage など）を作成します。これは、おそらく setup_requires= 引数を抽出する方法を提供するために setuptools にフックまたはモンキーパッチを提供し、sdist コマンドの新しいバージョンを提供して新しいスタイルの形式を生成する必要があります。これはすべて実行可能であり、多くのパッケージにとって十分です（ただし、ここで何かを最終決定する前に、そのようなシステムをプロトタイプ化することをお勧めします）。 （あるいは、これらの変更を setuptools 自体に加えることもできます）。

しかし、プロジェクトを新しい形式に自動的にアップグレードできない2つの障害が残っています。

1. 現在、setup.py が実行される前に特定のパッケージが環境に存在することを主張するパッケージが存在します。これにより、ビルドスクリプトを分離された virtualenv のような環境で実行することを決定した場合、プロジェクトはこれをチェックし、新しいシステムにアップグレードする際にこれらの依存関係を明示的に宣言し始める必要があります（setup_requires= または pyproject.toml での静的宣言を通じて）。
2. 現在、一貫したメタデータを宣言しないパッケージが存在します（例：egg_info と bdist_wheel が異なる install_requires= を取得する場合があります）。新しいシステムにアップグレードする際に、プロジェクトはこれが適用されるかどうかを評価し、適用される場合はそれを停止する必要があります。

却下されたオプション

• ホイールおよび sdist フックがそれぞれのアーカイブと同じ内容を含むアンパックされたディレクトリをビルドするというアイデアを議論しました。場合によっては、アーカイブをパックおよびアンパックする必要がなくなる可能性がありますが、これは時期尚早の最適化のように思えます。ツールがアーカイブを標準的な交換形式として扱うのは有利です（特にホイールの場合、アーカイブ形式はすでに標準化されています）。アーカイブの作成を厳密に制御することは、再現可能なビルドにとって重要です。そして、アンパックされたディストリビューションを必要とするタスクがアーカイブを必要とするタスクよりも一般的であるとは限りません。
• build_wheel にビルドディレクトリを渡す追加のフックを検討しました。既存のビルドシステムを調べた結果、ファイルをビルドディレクトリに事前にコピーするよりも、build_wheel にビルドディレクトリを渡す方が多くのツールにとって理にかなっていることがわかりました。
• 次に、build_wheel にビルドディレクトリを渡すというアイデアも不要な複雑化と見なされました。ビルドツールは一時ディレクトリやキャッシュディレクトリを使用してビルド中に中間ファイルを保存できます。フロントエンドが制御するキャッシュディレクトリが必要な場合は、将来的に追加することができます。
• 予想される理由で失敗を示すために build_sdist が使用するフックについて、さまざまなオプションが長時間議論されました。たとえば、NotImplementedError をスローする、NotImplemented または None を返すなどです。この議論を再開しようとしないでください。非常に良い理由がない限り、私たちはこの議論に非常に疲れています。
• バックエンドをソースツリー内のファイルからインポートすることを許可することは、Python のインポートが通常どのように機能するかとより一貫性があります。ただし、これを許可しないことで、モジュール名の競合による混乱を防ぐことができます。この PEP の初期バージョンでは、ソースツリー内のファイルからバックエンドをインポートする手段を提供していませんでしたが、次のリビジョンで backend-path キーが追加され、プロジェクトが必要に応じてこの動作をオプトインできるようになりました。

PEP 517 への変更の概要

この PEP に対して、最初のリファレンス実装が pip 19.0 でリリースされた後に行われた変更は次のとおりです。

• ビルド要件のサイクルが明示的に禁止されました。
• [build-system] テーブルに backend-path キーを追加することで、インツリーバックエンドおよびバックエンドのセルフホスティングのサポートが追加されました。
• build-backend を明示的に指定しないソースツリーに対して、setup.py を直接呼び出す代わりに setuptools.build_meta:__legacy__ PEP 517 バックエンドを使用することが許容されることが明確にされました。

付録 A: PEP 516 との比較

PEP 516 は、ビルドシステムインターフェースを指定するための競合する提案であり、現在はこの PEP に対して却下されています。主な違いは、ビルドバックエンドがコマンドラインベースのインターフェースではなく、Python フックベースのインターフェースを介して定義されていることです。

この付録では、この PEP が PEP 516 に対して提案された理由を文書化しています。

Python フックではなくコマンドラインインターフェースを指定することが、バックエンドへの呼び出しの複雑さを自体で減らすとは期待していません。なぜなら、ビルドフロントエンドはフックを子プロセス内で実行することを望むからです。これは、ビルドフロントエンド自体をバックエンドコードから分離し、ビルドバックエンドの実行環境をよりよく制御するために重要です。したがって、両方の提案では、pip にサブプロセスを生成し、何らかのコマンドライン/IPC インターフェースと通信するコードが必要であり、サブプロセス内にはこれらのコマンドライン引数を解析し、実際のビルドバックエンド実装を呼び出す方法を知っているコードが必要です。したがって、この図はすべての提案に等しく適用されます:

+-----------+          +---------------+           +----------------+
| frontend  | -spawn-> | child cmdline | -Python-> |    backend     |
|   (pip)   |          |   interface   |           | implementation |
+-----------+          +---------------+           +----------------+

2つのアプローチの主な違いは、これらのインターフェース境界がプロジェクト構造にどのようにマッピングされるかです:

.-= この PEP =-.

+-----------+          +---------------+    |      +----------------+
| frontend  | -spawn-> | child cmdline | -Python-> |    backend     |
|   (pip)   |          |   interface   |    |      | implementation |
+-----------+          +---------------+    |      +----------------+
                                            |
|______________________________________|    |
   Owned by pip, updated in lockstep        |
                                            |
                                            |
                                 PEP-defined interface boundary
                               Changes here require distutils-sig


.-= 代替案 =-.

+-----------+    |     +---------------+           +----------------+
| frontend  | -spawn-> | child cmdline | -Python-> |    backend     |
|   (pip)   |    |     |   interface   |           | implementation |
+-----------+    |     +---------------+           +----------------+
                 |
                 |     |____________________________________________|
                 |      Owned by build backend, updated in lockstep
                 |
    PEP-defined interface boundary
  Changes here require distutils-sig

PEP 定義のインターフェース境界を Python コードに移動することで、3つの重要な利点が得られます。

第一に、ビルドフロントエンドが少数（pip など）であるのに対し、カスタムビルドバックエンドの長い尾が存在する可能性が高いため（これらは各パッケージが特定のビルド要件に合わせて選択するため）、実際の図は次のようになります:

.-= この PEP =-.

+-----------+          +---------------+           +----------------+
| frontend  | -spawn-> | child cmdline | -Python+> |    backend     |
|   (pip)   |          |   interface   |        |  | implementation |
+-----------+          +---------------+        |  +----------------+
                                                |
                                                |  +----------------+
                                                +> |    backend     |
                                                |  | implementation |
                                                |  +----------------+
                                                :
                                                :

.-= 代替案 =-.

+-----------+          +---------------+           +----------------+
| frontend  | -spawn+> | child cmdline | -Python-> |    backend     |
|   (pip)   |       |  |   interface   |           | implementation |
+-----------+       |  +---------------+           +----------------+
                    |
                    |  +---------------+           +----------------+
                    +> | child cmdline | -Python-> |    backend     |
                    |  |   interface   |           | implementation |
                    |  +---------------+           +----------------+
                    :
                    :

つまり、この PEP は全体のエコシステム内のコードの量を減らします。そして特に、新しいビルドシステムを作成するための障壁を低くします。たとえば、これは完全な動作するビルドバックエンドです:

# mypackage_custom_build_backend.py
import os.path
import pathlib
import shutil
import tarfile

SDIST_NAME = "mypackage-0.1"
SDIST_FILENAME = SDIST_NAME + ".tar.gz"
WHEEL_FILENAME = "mypackage-0.1-py2.py3-none-any.whl"

#################
# sdist creation
#################

def _exclude_hidden_and_special_files(archive_entry):
    """Tarfile filter to exclude hidden and special files from the archive"""
    if archive_entry.isfile() or archive_entry.isdir():
        if not os.path.basename(archive_entry.name).startswith("."):
            return archive_entry

def _make_sdist(sdist_dir):
    """Make an sdist and return both the Python object and its filename"""
    sdist_path = pathlib.Path(sdist_dir) / SDIST_FILENAME
    sdist = tarfile.open(sdist_path, "w:gz", format=tarfile.PAX_FORMAT)
    # Tar up the whole directory, minus hidden and special files
    sdist.add(os.getcwd(), arcname=SDIST_NAME,
              filter=_exclude_hidden_and_special_files)
    return sdist, SDIST_FILENAME

def build_sdist(sdist_dir, config_settings):
    """PEP 517 sdist creation hook"""
    sdist, sdist_filename = _make_sdist(sdist_dir)
    return sdist_filename

#################
# wheel creation
#################

def get_requires_for_build_wheel(config_settings):
    """PEP 517 wheel building dependency definition hook"""
    # As a simple static requirement, this could also just be
    # listed in the project's build system dependencies instead
    return ["wheel"]

def build_wheel(wheel_directory,
                metadata_directory=None, config_settings=None):
    """PEP 517 wheel creation hook"""
    from wheel.archive import archive_wheelfile
    path = os.path.join(wheel_directory, WHEEL_FILENAME)
    archive_wheelfile(path, "src/")
    return WHEEL_FILENAME

もちろん、これは ひどい ビルドバックエンドです。ユーザーが手動で src/mypackage-0.1.dist-info/ にホイールメタデータを設定する必要があります。バージョン番号が変更されると、複数の場所で手動で更新する必要があります…しかし、これは機能し、より多くの機能を段階的に追加することができます。多くの経験から、大規模な成功したプロジェクトはしばしば迅速なハックとして始まることが示されています（例：Linux – 「ただの趣味、大きくてプロフェッショナルにはならない」; IPython/Jupyter – 大学院生の $PYTHONSTARTUP ファイル）、したがって、私たちの目標が優れたビルドツールの活気に満ちたエコシステムの成長を奨励することである場合、新しいビルドシステムの作成の障壁を最小限に抑えることが重要です。

第二に、Python はインターフェースを記述するためのよりシンプルで豊富な構造を提供するため、仕様から不要な複雑さを取り除きます。仕様は最悪の場所であり、仕様の変更には多くの利害関係者間での痛みを伴う合意形成が必要です。コマンドラインインターフェースアプローチでは、複数の異なる種類の入力を単一の線形コマンドラインにマッピングするためのアドホックな方法を考え出す必要があります（例：ユーザーが指定した構成引数と PEP 定義の引数の衝突をどのように回避するか？オプションの引数をどのように指定するか？Python インターフェースを使用する場合、これらの質問にはシンプルで明確な回答があります）。サブプロセスを生成および管理する際には、多くの細かい詳細を正しく処理する必要があり、微妙なクロスプラットフォームの違いがあり、最も明白なアプローチのいくつか（例：build_requires 操作のデータを標準出力で返す）は予期しない落とし穴を作成する可能性があります（例：ビルド要件を計算するために子プロセスを生成する必要があり、これらの子プロセスが時折エラーメッセージを標準出力に出力する場合はどうなりますか？慎重なビルドバックエンド作成者はこの問題を回避できますが、Python インターフェースを定義する最も明白な方法は、この可能性を完全に排除します。なぜなら、フックの戻り値は明確に区別されているからです）。

一般に、ビルドバックエンドを独自のプロセスに分離する必要があるため、IPC の複雑さを完全に排除することはできませんが、IPC インターフェースの両側を単一のプロジェクトの制御下に置くことで、IPC インターフェースのバグを修正するコストを大幅に削減できます。

第三に、そして最も重要なことに、Python フックアプローチは、将来的にこの仕様を進化させるためのより強力なオプションを提供します。

具体的な例として、来年、新しい build_sdist_from_vcs フックを追加し、フロントエンドがバージョン管理追跡メタデータをバックエンドに渡す責任を負う代替の build_sdist フックを提供することを想像してください（ディスク上のすべてのファイルが追跡されていることを示すことを含む）。これにより、個々のバックエンドがそれらの情報をクエリする必要がなくなります。この移行を管理するために、ビルドフロントエンドが build_sdist_from_vcs を利用可能な場合に透過的に使用し、そうでない場合は build_sdist にフォールバックすることができるようにし、ビルドバックエンドが両方のメソッドを定義して、古いビルドフロントエンドと新しいビルドフロントエンドの両方と互換性を持つことができるようにする必要があります。

さらに、私たちのメカニズムは次の2つの目標も達成する必要があります。（a）たとえば、pip と flit の新しいバージョンが両方とも新しいインターフェースをサポートするように更新された場合、これを使用するために十分である必要があります。特に、flit を使用するすべてのプロジェクトが個々の pyproject.toml ファイルを更新する必要はありません。（b）交渉を行うために追加のプロセスを生成する必要はありません。プロセスの生成は、一部のプラットフォームで大規模なマルチパッケージスタックをデプロイする際にボトルネックになる可能性があるためです（Windows）。

ここで説明するインターフェースでは、これらの目標をすべて簡単に達成できます。なぜなら、pip が子プロセス内で実行されるコードを制御できるため、次のように簡単に書くことができるからです:

command, backend, args = parse_command_line_args(...)
if command == "build_sdist":
   if hasattr(backend, "build_sdist_from_vcs"):
       backend.build_sdist_from_vcs(...)
   elif hasattr(backend, "build_sdist"):
       backend.build_sdist(...)
   else:
       # error handling

代替案では、公開インターフェースの境界がサブプロセス呼び出しに配置されるため、これは不可能です。インターフェースがサポートされているかどうかをクエリするために追加のプロセスを生成する必要があります（PEP 516 の以前のドラフトに含まれていた代替案の1つ）、または自動交渉を完全に放棄する必要があります（現在のバージョンの PEP では）、インターフェースの変更がライブになる前に N 個の個々のパッケージが pyproject.toml ファイルを更新する必要があり、変更は新しいリリースに制限されます。

この PEP では、prepare_metadata_for_build_wheel コマンドをオプションにすることができます。私たちの設計では、ビルドフロントエンドが次のようなコードをサブプロセスランナーに配置することで簡単に処理できます:

def dump_wheel_metadata(backend, working_dir):
    """Dumps wheel metadata to working directory.

       Returns absolute path to resulting metadata directory
    """
    if hasattr(backend, "prepare_metadata_for_build_wheel"):
        subdir = backend.prepare_metadata_for_build_wheel(working_dir)
    else:
        wheel_fname = backend.build_wheel(working_dir)
        already_built = os.path.join(working_dir, "ALREADY_BUILT_WHEEL")
        with open(already_built, "w") as f:
            f.write(wheel_fname)
        subdir = unzip_metadata(os.path.join(working_dir, wheel_fname))
    return os.path.join(working_dir, subdir)

def ensure_wheel_is_built(backend, output_dir, working_dir, metadata_dir):
    """Ensures built wheel is available in output directory

       Returns absolute path to resulting wheel file
    """
    already_built = os.path.join(working_dir, "ALREADY_BUILT_WHEEL")
    if os.path.exists(already_built):
        with open(already_built, "r") as f:
            wheel_fname = f.read().strip()
        working_path = os.path.join(working_dir, wheel_fname)
        final_path = os.path.join(output_dir, wheel_fname)
        os.rename(working_path, final_path)
        os.remove(already_built)
    else:
        wheel_fname = backend.build_wheel(output_dir, metadata_dir=metadata_dir)
    return os.path.join(output_dir, wheel_fname)

したがって、フロントエンドの残りの部分に対して完全に一貫したインターフェースを公開できます。追加のサブプロセス呼び出しや重複したビルドなどはありません。しかし、これはプロジェクト内のプライベートなインターフェースの一部としてのみ書きたい種類のコードです（例：与えられた例では、作業ディレクトリが2つの呼び出し間で共有される必要がありますが、他のホイールビルドとは共有されません。メタデータヘルパー関数からの戻り値がホイールビルド関数に渡されることを前提としています）。

（そしてもちろん、メタデータコマンドをオプションにすることは、新しいバックエンドの開発の障壁を低くするための1つの部分です。上記で説明したように。）

著作権

このドキュメントはパブリックドメインに置かれています。