ファイル形式

ビルドシステムの依存関係は、TOML 形式 [6] で記述された pyproject.toml という名前のファイルに保存されます。

この形式は、人間が使用しやすい（JSON [7] とは異なり）、柔軟性がある（configparser [9] とは異なり）、標準に基づいている（configparser [9] とは異なり）、複雑すぎない（YAML [8] とは異なり）ために選ばれました。TOML 形式は、Rust コミュニティによって Cargo パッケージマネージャー [14] の一部としてすでに使用されており、彼らは TOML の選択に非常に満足していると述べています。さまざまな代替案が選ばれなかった理由についての詳細な議論は、他のファイル形式 セクションで読むことができます。著者は、構成ファイル形式の選択は最終的には主観的であり、選択を行う必要があることを認識していますが、この状況では TOML を好みます。

以下に、ツールが認識/尊重することが期待されるテーブルをリストします。この PEP で指定されていないテーブルは、他の PEP による将来の使用のために予約されています。

build-system テーブル

[build-system] テーブルは、ビルドに関連するデータを保存するために使用されます。最初は、このテーブルの1つのキーのみが有効であり、必須です：requires。このキーは、ビルドシステムを実行するために必要な PEP 508 依存関係を表す文字列のリストの値を持つ必要があります（現在は setup.py ファイルを実行するために必要な依存関係を意味します）。

setuptools に依存する大多数の Python プロジェクトでは、pyproject.toml ファイルは次のようになります:

[build-system]
# ビルドシステムを実行するための最小要件。
requires = ["setuptools", "wheel"]  # PEP 508 仕様。

現在コミュニティで setuptools と wheel の使用が非常に広範であるため、ビルドツールは上記の例の構成ファイルを pyproject.toml ファイルが存在しない場合のデフォルトのセマンティクスとして使用することが期待されます。

ツールは [build-system] テーブルの存在を要求してはなりません。pyproject.toml ファイルは、ビルドに関連するデータ以外の構成詳細を保存するために使用される場合があり、正当な理由で [build-system] テーブルが欠けていることがあります。ファイルが存在するが [build-system] テーブルが欠けている場合は、上記で指定されたデフォルト値を使用する必要があります。テーブルが指定されているが、必須フィールドが欠けている場合は、ツールはそれをエラーと見なすべきです。

tool テーブル

[tool] テーブルは、ビルドツールに限らず、Python プロジェクトに関連する任意のツールが、[tool] 内のサブテーブルを使用してユーザーが構成データを指定できる場所です。例えば、flit ツールは、[tool.flit] に構成を保存します。

tool.* 名前空間内の名前を割り当てるためのメカニズムが必要です。異なるプロジェクトが同じサブテーブルを使用しようとして衝突するのを防ぐためです。私たちのルールは、プロジェクトが Cheeseshop/PyPI に $NAME のエントリを所有している場合にのみ、tool.$NAME サブテーブルを使用できるというものです。

JSON スキーマ

TOML ファイルからの結果データの型固有の表現を提供するために、以下の JSON スキーマ [15] がデータ形式に一致します:

{
    "$schema": "http://json-schema.org/schema#",

    "type": "object",
    "additionalProperties": false,

    "properties": {
        "build-system": {
            "type": "object",
            "additionalProperties": false,

            "properties": {
                "requires": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": ["requires"]
        },

        "tool": {
            "type": "object"
        }
    }
}

セマンティックバージョンキー

構成ファイルの構造を将来にわたって保護するために、semantics-version キーが最初に提案されました。デフォルトは 1 で、以前に定義されたキーやテーブルのセマンティクスが後方互換性のない変更を受けた場合に、semantics-version が新しい番号にインクリメントされるというアイデアです。

しかし、最終的には、これは時期尚早の最適化であると判断されました。構成ファイルで事前に定義されたセマンティクスの変更は、かなり保守的であると予想されます。そして、後方互換性のない変更が発生する場合には、新しいセマンティクスのために異なる名前を使用して、古いツールを壊さないようにすることができます。

よりネストされた名前空間

この PEP の初期のドラフトには、トップレベルの [package] テーブルがありました。これは、セマンティックバージョニングスキームのスコープを設定するためのアイデアでした（なぜそのアイデアが却下されたかについては、セマンティックバージョンキー を参照してください）。スコープの必要性がなくなったため、トップレベルのテーブルを持つことの意味がなくなりました。

他のテーブル名

[build-system] テーブルの別の名前として [build] が提案されました。代替名は短いですが、テーブルに保存される情報の意図をあまり伝えません。distutils-sig メーリングリストでの投票の結果、現在の名前が選ばれました。

他のファイル形式

いくつかの他のファイル形式が検討されましたが、さまざまな理由で却下されました。主な要件は、形式が人間によって編集可能であり、プロジェクトによって簡単にベンダリングできる実装があることです。これにより、XML のような形式は人間にとって使いやすくないため、真剣に議論されることはありませんでした。

{
    "build": {
        "requires": [
            "setuptools",
            "wheel>=0.27"
        ]
    }
}

build:
    requires:
        - setuptools
        - wheel>=0.27

[build]
requires =
    setuptools
    wheel>=0.27

# ビルド構成
{"build": {"requires": ["setuptools",
                        "wheel>=0.27", # 末尾のカンマに注意
                        # "numpy>=1.10" # コメントアウトされたデータ行
                        ]
# ここに任意のコメントがあります。
           }
 }

setup.cfg を使用し続ける

setuptools によって一般的な形式として使用される setup.cfg には2つの問題があります。1つは、configparser の議論で述べたように、.ini ファイルであることです。もう1つは、そのファイルのスキーマが厳密に定義されたことがなく、将来的にどの形式が安全に使用できるかが不明であり、setuptools のインストールを混乱させる可能性があることです。

他のファイル名

いくつかの他のファイル名が検討され、却下されました（これは非常にバイクシェディングなトピックであり、決定は主に好みによるものです）。

pysettings.toml

最も合理的な代替案。

pypa.toml

PyPA [11] を参照するのは理にかなっていますが、ややニッチな用語です。ドメイン固有の知識がなくてもファイル名が意味を持つ方が良いです。

pybuild.toml

この PEP の制限的な視点からはこのファイル名は理にかなっていますが、将来的にビルド以外のメタデータがファイルに追加されると、名前が意味をなさなくなります。

pip.toml

ツール固有すぎます。

meta.toml

あまりにも一般的です。プロジェクトは独自のメタデータファイルを持ちたいかもしれません。

setup.toml

setup.py に感謝しつつも、将来的にファイルに含まれる可能性のある内容と一致しないかもしれません（例：プロジェクトの名前を知ることは本質的にそのセットアップの一部ですか？）。

pymeta.toml

プログラミングや Python に不慣れな人には明らかではありません。

pypackage.toml & pypackaging.toml

「パッケージ」という名前の混同（プロジェクトと名前空間の違い）。

pydevelop.toml

ファイルには開発に特化しない詳細が含まれる可能性があります。

pysource.toml

ソースコードに直接関連していません。

pytools.toml

ファイルは（現在）プロジェクト管理を目的としているため、誤解を招きます。

dstufft.toml

個人固有すぎます。 ;)