PEP 753: Updates

peps/pep-0753.rst

@@ -190,15 +190,30 @@ normalization:
     "``Change_Log``", "``changelog``"
     "``What's New?``", "``whatsnew``"
 
-Metadata producers **SHOULD** emit the normalized form of a user
-specified label, but **MAY** choose to emit the un-normalized form so
-long as it adheres to the existing 32 character constraint.
+If the normalized form of a user-specified label is a
+:ref:`well-known label <well-known>` then the metadata producer **SHOULD**
+emit the normalized form, but **MAY** choose to emit the un-normalized
+form so long as it adheres to the existing 32 character constraint.
+
+If the normalized form is not well-known, then the metadata producer
+**MUST NOT** emit the normalized form.
 
 Package indices **SHOULD NOT** use the normalized labels belonging to the set
 of well-known labels directly as UI elements (instead replacing them with
 appropriately capitalized text labels). Labels not belonging to the well-known
 set **MAY** be used directly as UI elements.
 
+Normalization does **not** change pre-existing semantics around duplicated
+``Project-URL`` labels. In other words, normalization may result in duplicate
+labels in the project's metadata, but only in the same manner that was already permitted
+(since the :ref:`core metadata specification <packaging:core-metadata>` does
+not stipulate that labels are unique).
+
+Excerpted examples of normalized metadata fields are provided in
+:ref:`Appendix A <appendix-a>`.
+
+.. _well-known:
+
 Well-known labels
 -----------------
 
@@ -264,12 +279,9 @@ for documentation hosting or issue tracking).
 
 This PEP recognizes that the list of well-known labels is unlikely to remain
 static, and that subsequent additions to it should not require the overhead
-associated with a formal PEP process or new metadata version. As the primary
-expected use case for this information is to control the way project URLs are
-displayed on the Python Package Index, this PEP proposes that the list above
-become a "living" list within PyPI's documentation (at time of writing, the
-documentation for influencing PyPI's URL display can be found
-`here <https://docs.pypi.org/project_metadata/#icons>`__).
+associated with a formal PEP process or new metadata version. As such,
+this PEP proposes that the list above become a "living" list within
+the :ref:`PyPA specifications <packaging:packaging-specifications>`.
 
 Backwards Compatibility
 =======================
@@ -349,6 +361,44 @@ already contains an informal description of PyPI's URL handling behavior.
 If this PEP is accepted, the authors of this PEP will coordinate to update
 and cross-link the resources mentioned above.
 
+.. _appendix-a:
+
+Appendix A: Label normalization examples
+========================================
+
+This appendix provides an illustrative excerpt of a distribution's
+metadata, before and after label normalization.
+
+Before:
+
+.. code-block::
+
+    Project-URL: Home-page, https://example.com
+    Project-URL: Homepage, https://another.example.com
+    Project-URL: Source, https://github.com/example/example
+    Project-URL: GitHub, https://github.com/example/example
+    Project-URL: Another Service, https://custom.example.com
+
+
+After:
+
+.. code-block::
+
+  Project-URL: homepage, https://example.com
+  Project-URL: homepage, https://another.example.com
+  Project-URL: source, https://github.com/example/example
+  Project-URL: github, https://github.com/example/example
+  Project-URL: Another Service, https://custom.example.com
+
+In particular, observe:
+
+* Normalized duplicates are preserved (both ``Home-page`` and ``Homepage``
+  become ``homepage``);
+* ``Source`` and ``GitHub`` are both normalized into their respective forms,
+  but ``github`` is **not** transformed into ``source``.
+* ``Another Service`` is **not** normalized, since its normal form
+  (``anotherservice``) is not a :ref:`well-known label <well-known>`.
+
 Copyright
 =========