プロジェクトのメタデータを宣言する#
PEP 621 では、パッケージング関連のツールが使用するために、あるプロジェクトの コアとなるメタデータ を pyproject.toml ファイルにどのように書けば良いかを指定しています。使われるファイルフォーマットの基準となる仕様として、以下のようなものを定義しています。
警告
This is a technical, formal specification. For a gentle,
user-friendly guide to pyproject.toml, see
Writing your pyproject.toml.
仕様#
メタデータにはふたつの種類があります: 静的 なものと 動的 なものです。静的なメタデータは pyproject.toml ファイルで直接指定されていて、ツール側では指定したり変更したりできません (これは、例えばメタデータが参照するファイルの内容のような、メタデータによって 参照 されるデータを含みます)。動的なメタデータは dynamic キー (この仕様内で後で定義します) を経由して一覧化されていて、ツール側が後から提供することになるでしょう。
The keys defined in this specification MUST be in a table named
[project] in pyproject.toml. No tools may add keys to this
table which are not defined by this specification. For tools wishing
to store their own settings in pyproject.toml, they may use the
[tool] table as defined in the
build dependency declaration specification.
The lack of a [project] table implicitly means the build backend
will dynamically provide all keys.
必ず静的に定義しなければならない必須のキーは次の通り:
名称
必須フィールドだが、静的に指定しても動的に指定しても いずれでも構わない キーは以下の通り:
version
他の全てのキーは必須ではないものと解釈され、これらは静的に指定しても動的にリストしても未指定のままにしていても構いません。
[project] テーブルで許容されるキーの完全なリストは次のとおりです:
著者 <authors>分類詞 <classifiers>依存関係 <dependencies説明dynamicentry-pointsgui スクリプト <gui-scripts>keywordsライセンス保守者 <maintainers>名称optional-dependenciesreadmerequires-pythonscriptsurlsversion
名称#
TOML 型: 文字列
コアとなるメタデータ フィールドに対応する: 名前 フィールド
プロジェクトの名前。
内部的な一貫性を保つために、ツール側では読み取ったらすぐに、この名前を 正規化 するべきです。
version#
TOML 型: 文字列
コアとなるメタデータ に対応する: バージョン
The version of the project, as defined in the Version specifier specification.
ユーザは正規化済みのバージョンを指定するようにするべきです。
説明#
TOML 型: 文字列
コアとなるメタデータ フィールドに対応する: 要約
プロジェクトを要約する記述。
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の中で指定されたメタデータで、しかし、ビルド用バックエンドがそこに挿入するべきデータを決定することができない時は、ビルド用バックエンドはエラーを発生させなければなりません (正確な値であると判断した場合はデータを省略することが許容されます) 。