pyproject.toml specification#
警告
This is a technical, formal specification. For a gentle,
user-friendly guide to pyproject.toml, see
pyproject.toml を書く.
The pyproject.toml file acts as a configuration file for packaging-related
tools (as well as other tools).
The pyproject.toml file is written in TOML. Three
tables are currently specified, namely
[build-system],
[project] and
[tool]. Other tables are reserved for future
use (tool-specific configuration should use the [tool] table).
Declaring build system dependencies: the [build-system] table#
The [build-system] table declares any Python level dependencies that
must be installed in order to run the project's build system
successfully.
The [build-system] table is used to store build-related data.
Initially, only one key of the table is valid and is mandatory
for the table: requires. This key must have a value of a list
of strings representing dependencies required to execute the
build system. The strings in this list follow the version specifier
specification.
An example [build-system] table for a project built with
setuptools is:
[build-system]
# Minimum requirements for the build system to execute.
requires = ["setuptools"]
Build tools are expected to use the example configuration file above as
their default semantics when a pyproject.toml file is not present.
Tools should not require the existence of the [build-system] table.
A pyproject.toml file may be used to store configuration details
other than build-related data and thus lack a [build-system] table
legitimately. If the file exists but is lacking the [build-system]
table then the default values as specified above should be used.
If the table is specified but is missing required fields then the tool
should consider it an error.
To provide a type-specific representation of the resulting data from the TOML file for illustrative purposes only, the following JSON Schema would match the data format:
{
"$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"
}
}
}
Declaring project metadata: the [project] table#
The [project] table specifies the project's core metadata.
メタデータにはふたつの種類があります: 静的 なものと 動的 なものです。静的なメタデータは pyproject.toml ファイルで直接指定されていて、ツール側では指定したり変更したりできません (これは、例えばメタデータが参照するファイルの内容のような、メタデータによって 参照 されるデータを含みます)。動的なメタデータは dynamic キー (この仕様内で後で定義します) を経由して一覧化されていて、ツール側が後から提供することになるでしょう。
The lack of a [project] table implicitly means the build backend
will dynamically provide all keys.
必ず静的に定義しなければならない必須のキーは次の通り:
名称
必須フィールドだが、静的に指定しても動的に指定しても いずれでも構わない キーは以下の通り:
version
他の全てのキーは必須ではないものと解釈され、これらは静的に指定しても動的にリストしても未指定のままにしていても構いません。
[project] テーブルで許容されるキーの完全なリストは次のとおりです:
著者 <authors>分類詞 <classifiers>依存関係 <dependencies説明 <description>dynamicentry-pointsgui スクリプト <gui-scripts>keywordsライセンス保守者 <maintainers>名称optional-dependenciesreadmerequires-pythonscriptsurlsversion
名称#
TOML 型: 文字列
コアとなるメタデータ フィールドに対応する: 名前 フィールド
プロジェクトの名前。
内部的な一貫性を保つために、ツール側では読み取ったらすぐに、この名前を 正規化 するべきです。
version#
TOML 型: 文字列
コアとなるメタデータ に対応する: バージョン
The version of the project, as defined in the Version specifier specification.
ユーザは正規化済みのバージョンを指定するようにするべきです。
説明 <description>#
TOML 型: 文字列
コアとなるメタデータ フィールドに対応する: 要約
The summary description of the project in one line. Tools MAY error if this includes multiple lines.
readme#
TOML 型: 文字列またはテーブル
対応する コアとなるメタデータ フィールド: Description and Description-Content-Type
プロジェクトの説明全体 (すなわち README)。
このキーは文字列かテーブルを受け付けます。もし文字列なら、完全な説明を含むテキストファイルの位置を pyproject.toml からの相対パスで示したものです。ツールの側ではこのファイルが UTF-8 でエンコードされているものと想定しなければなりません。ファイルパスが大文字小文字を問わず .md 拡張子で終わっている場合は、ツールはそのファイルの content-type が text/markdown であるものと仮定しなければなりません。ファイルパスが大文字小文字を問わず .rst で終わっている場合は、ツールは content-type が text/x-rst であるものと仮定しなければなりません。この PEP で指定するよりも多くの拡張子をツールが認識するなら、そのようなツールは、このキーを dynamic であると指定していなくても、ユーザのために content-type を推測しても構いません。content-type が与えられていない場合には、全ての認識できない拡張子についてツールはエラーを発生させなければなりません。
readme キーはその値がテーブルでも構いません。 file キーは、完全な説明を含むファイルへの pyproject.toml ファイルからの相対パスを表現する文字列を値として持ちます。 text キーは、完全な説明そのものである文字列を値に持ちます。これらのキーは排他的にいずれかひとつしか使えないので、もしメタデータがこれら両方のキーを同時に指定していたらツールはエラーを発生させなければなりません。
readme キーに指定されたテーブルには、完全な説明の content-type を指定する文字列を値とする content-type キーも含まれています。メタデータがこのキーをテーブルの中で指定していない場合には、ツールはエラーを発生させなければなりません。メタデータで charset パラメータが指定されていない場合には、 UTF-8 であるものと想定されます。ツールは各ツールが独自に選択した他のエンコーディングをサポートしても構いません。 コアとなるメタデータ によってサポートされている content-type に変換することができるのであれば、ツールはそのような代替 content-type をサポートしても構いません。そうでなければ、ツールはサポートしていない content-type に対してエラーを発生させなければなりません。
requires-python#
TOML 型: 文字列
コアとなるメタデータ フィールドに対応する: Requires-Python
プロジェクトが要求する Python のバージョン。
ライセンス#
TOML 型: テーブル
対応する コアとなるメタデータ フィールド: License
テーブルには二つのキーのうちのいずれか一つを書くことができます。 file キーは、 pyproject.toml からプロジェクトのライセンス情報を含むファイルへの相対パスを値とする文字列です。ツールの側では、そのファイルのエンコーディングが UTF-8 であるものと仮定しなければなりません。 text キーは、プロジェクトのライセンス条項そのものである文字列を値に取ります。これらのキーは相互に排他的で、従って、両方のキーが指定されているメタデータについてツールの側ではエラーを発生させなければなりません。
keywords#
TOML 型: 文字列の配列
対応する コアとなるメタデータ フィールド: Keywords <core-metadata-keywords
プロジェクトに関するキーワード。
分類詞 <classifiers>#
TOML 型: 文字列の配列
対応する コアとなるメタデータ フィールド: Classifier
プロジェクトに適合する Trove 分類子。
urls#
TOML 型: 文字列のキー・バリューを伴うテーブル
対応する コアとなるメタデータ フィールド: Project-URL
URL のテーブルで、 URL に付けられたラベルがキーで URL そのものが値になっているもの。
エントリポイント#
TOML 型: table (
[project.scripts]・[project.gui-scripts]・[project.entry-points])
みっつのテーブルがエントリポイントに関係しています。 [project.scripts] テーブルは、 エントリポイント仕様 の中の console_scripts グループに対応しています。テーブル内のキーはエントリポイントの名前であり、値は参照されるオブジェクトです。
[project.gui-scripts] テーブルは、 エントリポイント仕様 の中の gui_scripts グループに対応します。そのフォーマットは [project.scripts] と同じです。
[project.entry-points] テーブルは、テーブルの集合体です。それぞれのサブテーブルの名前は、ひとつのエントリポイントグループです。キーと値の意味するところは [project.scripts] と同じです。ユーザはネストしたサブテーブルを作ってはならず、代わりにエントリポイントグループを１段階の深さに保つようにしなければなりません。
メタデータの中に [project.entry-points.console_scripts] もしくは [project.entry-points.gui_scripts] というテーブルが定義されている場合は、それぞれ [project.scripts] や [project.gui-scripts] と混同してしまうといけないので、ビルド時のバックエンドがエラーを発生させなければなりません。
dependencies/optional-dependencies#
TOML 型: PEP 508 の文字列 (
dependencies) の配列、および、 PEP 508 の文字列 (optional-dependencies) の配列の値を伴ったテーブル対応する コアとなるメタデータ フィールド: Requires-Dist および Provides-Extra
(必須ではない) プロジェクトの依存関係。
dependencies には、文字列の配列が値であるようなキーです。それぞれの文字列がそのプロジェクトの依存関係を表現していて、正当な PEP 508 の文字列としてフォーマットされていなければなりません。それぞれの文字列は、 Requires-Dist エントリに直接にマップしています。
optional-dependencies は、それぞれのキーが追加物で、その値が文字列の配列であるようなテーブルです。文字列の配列は正当な PEP 508 の文字列でなければなりません。キーは Provides-Extra としてみた時に正当な値でなければなりません。従って、配列の中のそれぞれの値は、一致する Provides-Extra メタデータに対応する Requires-Dist のエントリになります。
dynamic#
TOML 型: 文字列の配列
コアとなるメタデータ フィールドに対応する: ダイナミック フィールド
この PEP に列挙されたキーのどれを意図的に指定しないままにすることで他のツールが動的にそのようなメタデータを準備することができる/しようとするかを規定します。後述するツールによる設定に比較して、どのメタデータが目的を持って未指定にされていて未指定のままであることを期待されているのかについて明確に描き出します。
ビルド用のバックエンドは、静的に指定されたメタデータ (つまり
dynamic内に列挙されたキーではないメタデータ) を尊重しなければなりません。メタデータで
dynamic内にnameが指定されている場合には、ビルド用バックエンドがエラーを発生させなければなりません。コアとなるメタデータ の仕様において、あるキーが "必須である" ものとして挙げられている場合には、メタデータはそのキーを静的に指定するか、または、
dynamic内に指定するかしなければなりません (どちらでもない場合にはビルドバックエンドがエラーを発生させなければなりません、すなわち、必須のフィールドが[project]テーブルの中にどんな形でも存在していないということは不可能であるべきです)。コアとなるメタデータ の仕様で、あるキーを "必須ではない" ものとして挙げている場合には、後でビルド用バックエンドがそのキー用のデータを提供するという期待が持てるのであればメタデータではそのキーを
dynamicの中に挙げても構いません。メタデータ内で、あるキーが静的に指定されていて、かつ、
dynamicにも挙げてある場合には、ビルド用バックエンドはエラーを発生させなければなりません。メタデータ内で、あるキーを
dynamicの中に挙げなかった場合は、ビルド用バックエンドがユーザに代わって必要なメタデータを挿入することはできません (すなわち、ツールがメタデータを挿入できるのはdynamicの中だけであり、かつ、ユーザがそうするようにオプトインしていなければならないということです) 。あるキーが
dynamicの中で指定されたメタデータで、しかし、ビルド用バックエンドがそこに挿入するべきデータを決定することができない時は、ビルド用バックエンドはエラーを発生させなければなりません (正確な値であると判断した場合はデータを省略することが許容されます) 。
Arbitrary tool configuration: the [tool] table#
The [tool] table is where any tool related to your Python
project, not just build tools, can have users specify configuration
data as long as they use a sub-table within [tool], e.g. the
flit tool would store its
configuration in [tool.flit].
A mechanism is needed to allocate names within the tool.*
namespace, to make sure that different projects do not attempt to use
the same sub-table and collide. Our rule is that a project can use
the subtable tool.$NAME if, and only if, they own the entry for
$NAME in the Cheeseshop/PyPI.