プロジェクトのメタデータを宣言する¶
PEP 621 では、パッケージング関連のツールが使用するために、あるプロジェクトの コアとなるメタデータ を pyproject.toml
ファイルにどのように書けば良いかを指定しています。使われるファイルフォーマットの基準となる仕様として、以下のようなものを定義しています。
仕様¶
メタデータにはふたつの種類があります: 静的 なものと 動的 なものです。静的なメタデータは pyproject.toml
ファイルで直接指定されていて、ツール側では指定したり変更したりできません (これは、例えばメタデータが参照するファイルの内容のような、メタデータによって 参照 されるデータを含みます)。動的なメタデータは dynamic
キー (この仕様内で後で定義します) を経由して一覧化されていて、ツール側が後から提供することになるでしょう。
この仕様で定義されるキーは、 pyproject.toml
ファイルの中の [project]
という名前のテーブルに収容されていなければなりません。いかなるツールもこのテーブルにこの仕様で定義されていないキーを追加してはなりません。自身の設定を pyproject.toml
ファイルに記録しておきたいと願うツールは、 ビルド時の依存関係を宣言するための仕様 で定義されている通りに [tool]
テーブルを使うことができます。 [project]
テーブルが欠落している場合は、ビルド用のバックエンドがすべてのキーを動的に提供するであろうということを暗黙理に意味しています。
必ず静的に定義しなければならない必須のキーは次の通り:
名称
必須フィールドだが、静的に指定しても動的に指定しても いずれでも構わない キーは以下の通り:
version
他の全てのキーは必須ではないものと解釈され、これらは静的に指定しても動的にリストしても未指定のままにしていても構いません。
[project]
テーブルで許容されるキーの完全なリストは次のとおりです:
著者 <authors>
分類詞 <classifiers>
依存関係 <dependencies
説明
dynamic
entry-points
gui スクリプト <gui-scripts>
keywords
ライセンス
保守者 <maintainers>
名称
optional-dependencies
readme
requires-python
scripts
urls
version
名称
¶
TOML 型: 文字列
コアとなるメタデータ フィールドに対応する: 名前 フィールド
プロジェクトの名前。
内部的な一貫性を保つために、ツール側では読み取ったらすぐに、この名前を 正規化 するべきです。
[project]
name = "spam"
version
¶
TOML 型: 文字列
コアとなるメタデータ に対応する: バージョン
PEP 440 でサポートされた通りのプロジェクトのバージョン。
ユーザは正規化済みのバージョンを指定するようにするべきです。
[project]
version = "2020.0.0"
説明
¶
TOML 型: 文字列
コアとなるメタデータ フィールドに対応する: 要約
プロジェクトを要約する記述。
[project]
description = "Lovely Spam! Wonderful Spam!"
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 に対してエラーを発生させなければなりません。
[project]
# A single pyproject.toml file can only have one of the following.
readme = "README.md"
readme = "README.rst"
readme = {file = "README.txt", content-type = "text/markdown"}
requires-python
¶
TOML 型: 文字列
コアとなるメタデータ フィールドに対応する: Requires-Python
プロジェクトが要求する Python のバージョン。
[project]
requires-python = ">=3.8"
ライセンス
¶
TOML 型: テーブル
対応する コアとなるメタデータ フィールド: License
テーブルには二つのキーのうちのいずれか一つを書くことができます。 file
キーは、 pyproject.toml
からプロジェクトのライセンス情報を含むファイルへの相対パスを値とする文字列です。ツールの側では、そのファイルのエンコーディングが UTF-8 であるものと仮定しなければなりません。 text
キーは、プロジェクトのライセンス条項そのものである文字列を値に取ります。これらのキーは相互に排他的で、従って、両方のキーが指定されているメタデータについてツールの側ではエラーを発生させなければなりません。
[project]
# A single pyproject.toml file can only have one of the following.
license = {file = "LICENSE"}
license = {text = "MIT License"}
keywords
¶
TOML 型: 文字列の配列
対応する コアとなるメタデータ フィールド: Keywords <core-metadata-keywords
プロジェクトに関するキーワード。
[project]
keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
分類詞 <classifiers>
¶
TOML 型: 文字列の配列
対応する コアとなるメタデータ フィールド: Classifier
プロジェクトに適合する Trove 分類子。
classifiers = [
"Development Status :: 4 - Beta",
"Programming Language :: Python"
]
urls
¶
TOML 型: 文字列のキー・バリューを伴うテーブル
対応する コアとなるメタデータ フィールド: Project-URL
URL のテーブルで、 URL に付けられたラベルがキーで URL そのものが値になっているもの。
[project.urls]
Homepage = "https://example.com"
Documentation = "https://readthedocs.org"
Repository = "https://github.com/me/spam.git"
Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
エントリポイント¶
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]
と同じです。ユーザはネストしたサブテーブルを作ってはならず、代わりにエントリポイントグループを1段階の深さに保つようにしなければなりません。
メタデータの中に [project.entry-points.console_scripts]
もしくは [project.entry-points.gui_scripts]
というテーブルが定義されている場合は、それぞれ [project.scripts]
や [project.gui-scripts]
と混同してしまうといけないので、ビルド時のバックエンドがエラーを発生させなければなりません。
[project.scripts]
spam-cli = "spam:main_cli"
[project.gui-scripts]
spam-gui = "spam:main_gui"
[project.entry-points."spam.magical"]
tomatoes = "spam:main_tomatoes"
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 のエントリになります。
[project]
dependencies = [
"httpx",
"gidgethub[httpx]>4.0.0",
"django>2.1; os_name != 'nt'",
"django>2.0; os_name == 'nt'",
]
[project.optional-dependencies]
gui = ["PyQt5"]
cli = [
"rich",
"click",
]
dynamic
¶
TOML 型: 文字列の配列
コアとなるメタデータ フィールドに対応する: ダイナミック フィールド
この PEP に列挙されたキーのどれを意図的に指定しないままにすることで他のツールが動的にそのようなメタデータを準備することができる/しようとするかを規定します。後述するツールによる設定に比較して、どのメタデータが目的を持って未指定にされていて未指定のままであることを期待されているのかについて明確に描き出します。
ビルド用のバックエンドは、静的に指定されたメタデータ (つまり
dynamic
内に列挙されたキーではないメタデータ) を尊重しなければなりません。メタデータで
dynamic
内にname
が指定されている場合には、ビルド用バックエンドがエラーを発生させなければなりません。コアとなるメタデータ の仕様において、あるキーが "必須である" ものとして挙げられている場合には、メタデータはそのキーを静的に指定するか、または、
dynamic
内に指定するかしなければなりません (どちらでもない場合にはビルドバックエンドがエラーを発生させなければなりません、すなわち、必須のフィールドが[project]
テーブルの中にどんな形でも存在していないということは不可能であるべきです)。コアとなるメタデータ の仕様で、あるキーを "必須ではない" ものとして挙げている場合には、後でビルド用バックエンドがそのキー用のデータを提供するという期待が持てるのであればメタデータではそのキーを
dynamic
の中に挙げても構いません。メタデータ内で、あるキーが静的に指定されていて、かつ、
dynamic
にも挙げてある場合には、ビルド用バックエンドはエラーを発生させなければなりません。メタデータ内で、あるキーを
dynamic
の中に挙げなかった場合は、ビルド用バックエンドがユーザに代わって必要なメタデータを挿入することはできません (すなわち、ツールがメタデータを挿入できるのはdynamic
の中だけであり、かつ、ユーザがそうするようにオプトインしていなければならないということです) 。あるキーが
dynamic
の中で指定されたメタデータで、しかし、ビルド用バックエンドがそこに挿入するべきデータを決定することができない時は、ビルド用バックエンドはエラーを発生させなければなりません (正確な値であると判断した場合はデータを省略することが許容されます) 。
dynamic = ["version", "description", "optional-dependencies"]
例¶
[project]
name = "spam"
version = "2020.0.0"
description = "Lovely Spam! Wonderful Spam!"
readme = "README.rst"
requires-python = ">=3.8"
license = {file = "LICENSE.txt"}
keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
authors = [
{name = "Pradyun Gedam", email = "pradyun@example.com"},
{name = "Tzu-Ping Chung", email = "tzu-ping@example.com"},
{name = "Another person"},
{email = "different.person@example.com"},
]
maintainers = [
{name = "Brett Cannon", email = "brett@python.org"}
]
classifiers = [
"Development Status :: 4 - Beta",
"Programming Language :: Python"
]
dependencies = [
"httpx",
"gidgethub[httpx]>4.0.0",
"django>2.1; os_name != 'nt'",
"django>2.0; os_name == 'nt'",
]
# dynamic = ["version", "description"]
[project.optional-dependencies]
gui = ["PyQt5"]
cli = [
"rich",
"click",
]
[project.urls]
Homepage = "https://example.com"
Documentation = "https://readthedocs.org"
Repository = "https://github.com/me/spam.git"
Changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
[project.scripts]
spam-cli = "spam:main_cli"
[project.gui-scripts]
spam-gui = "spam:main_gui"
[project.entry-points."spam.magical"]
tomatoes = "spam:main_tomatoes"