メタデータ内のよく知られたプロジェクト URL¶
重要
この説明文書は、一義的にはメタデータの コンシューマ 、コンシューマはPython エコシステムを通じて一貫性のある形でプロジェクト URL を提示させるために標準化ルールや後述のよく知られたリストを使用するべきですが、そのコンシューマに着目しています。
(ビルドツール類や個々のパッケージ保守者のような) メタデータの プロデューサ は、全体的な Project-URL の長さ制限の範囲内であれば、好きなラベルを使用し続けても構いません。しかしながら、可能であるときには、ユーザは理解しやすいラベルでよく知られたラベルに標準化されたものを選択することを 推奨されています 。
注釈
パッケージのメタデータの中のプロジェクト URL ラベルを選択することについてのユーザ指向のガイダンスについては、 pyproject.toml を書く- urls を見てください。
注釈
この仕様は、元々は PEP 753 で定義されました。
PEP 753 は、 Project-URL (複数回の使用可) に従って Home-page と Download-URL のメタデータフィールドを非推奨とし、 Project-URL が "よく知られた" ものであるかどうか、つまり、 Home-page ・ Download-URL やその他の一般的なプロジェクト URL に指定されるセマンティクスを持っているかどうかを決定するための、正規化とルックアップの手続きを定義しました。
これによって、 (Python Package Index のような) インデックスや他のダウンストリーム側メタデータコンシューマが首尾一貫したやり方でプロジェクト URL を提示することができます。
ラベルの正規化¶
注釈
ラベル正規化は、メタデータの コンシューマ によって行われるのであって、メタデータプロデューサによってではありません。
Project-URL ラベルが "よく知られた" ものであるかどうかを決定するためには、メタデータのコンシューマは、そのラベルを よく知られたラベルのリスト と比較する前に、そのラベルを正規化するべきです。
Project-URL ラベルの正規化の手続きは、次に示す Python 関数で定義されています:
import string
def normalize_label(label: str) -> str:
chars_to_remove = string.punctuation + string.whitespace
removal_map = str.maketrans("", "", chars_to_remove)
return label.translate(removal_map).lower()
プレーンな言語では: ラベルは、 ASCII の句読点と空白文字をすべて取り除き、その結果を小文字に変換することで 正規化 されます。
次に示すテーブルでは、ラベルの正規化の前 (生) と後の例をお見せします:
生 |
正規化後 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
よく知られたラベル¶
注釈
よく知られたラベルのリストは、成長し続ける標準で、この説明文書の一部として維持管理されます。
以下のテーブルでは、 Project-URL メタデータの表示を特別なものにする目的のためによく知られたラベルを列挙します:
ラベル (人間が読む時用の同等物) |
説明 |
別名 |
|---|---|---|
|
プロジェクトのホームページ |
(none) |
|
プロジェクトのホストされたソースコードまたはリポジトリ |
|
|
最新の配布物のダウンロード URL で、 |
(none) |
|
プロジェクトの網羅的な変更履歴 |
|
|
プロジェクトの精査されたリリースノート |
(none) |
|
プロジェクトのオンライン説明文書 |
|
|
プロジェクトのバグ追跡システム |
|
|
財政支援のための情報 |
|
パッケージメタデータのコンシューマは、別名で表現されたラベルをその "親" のよく知られたラベルと同様に展開することや、または、それらをさらに詳しく指定することを選択しても構いません。
振る舞いの例¶
以下では、 pyproject.toml からのプロジェクト URL メタデータを コアとなるメタデータへ、さらに潜在的なインデックスへと表現する流れを示します:
[project.urls]
"Home Page" = "https://example.com"
DOCUMENTATION = "https://readthedocs.org"
Repository = "https://upstream.example.com/me/spam.git"
GitHub = "https://github.com/example/spam"
Project-URL: Home page, https://example.com
Project-URL: DOCUMENTATION, https://readthedocs.org
Project-URL: Repository, https://upstream.example.com/me/spam.git
Project-URL: GitHub, https://github.com/example/spam
Homepage: https://example.com
Documentation: https://readthedocs.org
Source Code: https://upstream.example.com/me/spam.git
Source Code (GitHub): https://github.com/example/spam
(メタデータの プロデューサ は正規化を実行しないので) コアとなるメタデータがユーザによって提供されたフォームの中に出現したことを観測し、しかし、メタデータの コンシューマ が正規化し、正規化すみフォームに基づいて適切な人間の読める形の同等物を特定する:
Home pageはhomepageとなり、それはHomepageに展開されるDOCUMENTATIONはdocumentationとなり、それはDocumentationに展開されるRepositoryはrepositoryとなり、Source Codeとして展開されますGitHubはgithubとなり、 (Source Codeの特定の形として)Source Code (GitHub)に展開される