Skip to content

Commit

Permalink
PEP 753: remove metadata producer prescriptions
Browse files Browse the repository at this point in the history
Label normalization is now entirely prescriptive on the consumer
side.

Signed-off-by: William Woodruff <[email protected]>
  • Loading branch information
woodruffw committed Oct 2, 2024
1 parent 4931b81 commit d0c848a
Showing 1 changed file with 28 additions and 35 deletions.
63 changes: 28 additions & 35 deletions peps/pep-0753.rst
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,14 @@ Post-History: `26-Aug-2024 <https://discuss.python.org/t/core-metadata-should-ho
Abstract
========

This PEP recommends two discrete changes to handling of core metadata by
indices, such as PyPI:
This PEP recommends two discrete changes to the processing of core metadata by
indices (such as PyPI) and other core metadata consumers:

* Deprecation of the ``Home-page`` and ``Download-URL`` fields in favor of
their ``Project-URL`` equivalents;
* A set of conventions for normalizing and assigning semantics to
``Project-URL`` labels.
* A set of :ref:`conventions <conventions-for-labels>` for normalizing and
assigning semantics to ``Project-URL`` labels during consumer-side metadata
processing.

Rationale and Motivation
========================
Expand All @@ -35,21 +36,21 @@ for expressing a package's relationship to external resources, via URLs:
1. Metadata 1.0 introduced ``Home-page``, a single-use field containing
a URL to the distribution's home page.

.. code-block::
.. code-block:: email
Home-page: https://example.com/sampleproject
2. Metadata 1.1 introduced ``Download-URL``, a complementary single-use field
containing a URL suitable for downloading the current distribution.

.. code-block::
.. code-block:: email
Download-URL: https://example.com/sampleproject/sampleproject-1.2.3.tar.gz
3. Metadata 1.2 introduced ``Project-URL``, a **multiple-use** field containing
a label-and-URL pair. Each label is free text conveying the URL's semantics.

.. code-block::
.. code-block:: email
Project-URL: Homepage, https://example.com/sampleproject
Project-URL: Download, https://example.com/sampleproject/sampleproject-1.2.3.tar.gz
Expand Down Expand Up @@ -93,9 +94,6 @@ This PEP stipulates the following for metadata producers:
* When generating metadata 1.2 or later, producers **SHOULD** emit only
``Project-URL``, and **SHOULD NOT** emit ``Home-page`` or ``Download-URL``
fields.
* When generating ``Project-URL`` equivalents for ``Home-page`` and
``Download-URL``, producers **SHOULD** use the
:ref:`label conventions <conventions-for-labels>` described below.

These stipulations do not change the optionality of URL fields in core metadata.
In other words, producers **MAY** choose to omit ``Project-URL`` entirely
Expand All @@ -106,6 +104,11 @@ or ``Download-URL``. However, see :ref:`future-considerations` for
thoughts on how a new (as of yet unspecified) major core metadata version
could complete the deprecation cycle via removal of these deprecated fields.

Similarly, this PEP does **not** propose that metadata producers emit
:ref:`normalized labels <label-normalization>`. Label normalization is performed
solely on the processing and consumption side (i.e. within indices and other
consumers of distribution metadata).

.. _package-indices:

Package indices
Expand Down Expand Up @@ -153,10 +156,13 @@ informal relationship between ``Home-page``, ``Download-URL``, and their

This formalization has two parts:

1. A set of rules for normalizing ``Project-URL`` labels;
1. A set of rules for normalizing ``Project-URL`` labels during index-side
processing;
2. A set of "well-known" normalized label values that indices may specialize
URL presentation for.

.. _label-normalization:

Label normalization
-------------------

Expand Down Expand Up @@ -190,18 +196,11 @@ normalization:
"``Change_Log``", "``changelog``"
"``What's New?``", "``whatsnew``"

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.
When processing distribution metadata, package indices **SHOULD** perform
label normalization to determine if a given label is
:ref:`well known <well-known>` for subsequent special processing.
Labels that are not well-known **MUST** be processed in their un-normalized
form.

Normalization does **not** change pre-existing semantics around duplicated
``Project-URL`` labels. In other words, normalization may result in duplicate
Expand Down Expand Up @@ -258,15 +257,9 @@ Indices **MAY** choose to use the human-readable equivalents suggested above
in their UI elements, if appropriate. Alternatively, indices **MAY** choose
their own appropriate human-readable equivalents for UI elements.

Packagers and metadata producers **MAY** choose to use these well-known
labels or their aliases to communicate specific URL intents to package indices
and downstreams.

Packagers and metadata producers **SHOULD** produce the normalized version
of the well-known labels or their aliases in package metadata. Packaging tools
**MUST NOT** transform between equivalent aliases, i.e.. **SHOULD**
normalize ``GitHub`` to ``github`` but **MUST NOT** transform
``github`` to ``source``.
Packagers and metadata producers **MAY** choose to use any label that normalizes
to these labels (or their aliases) to communicate specific URL intents to
package indices and downstreams.

Similarly, indices **MAY** choose to specialize their rendering or presentation
of URLs with these labels, e.g. by presenting an appropriate icon or tooltip
Expand Down Expand Up @@ -367,11 +360,11 @@ Appendix A: Label normalization examples
========================================

This appendix provides an illustrative excerpt of a distribution's
metadata, before and after label normalization.
metadata, before and after index-side processing:

Before:

.. code-block::
.. code-block:: email
Project-URL: Home-page, https://example.com
Project-URL: Homepage, https://another.example.com
Expand All @@ -382,7 +375,7 @@ Before:
After:

.. code-block::
.. code-block:: email
Project-URL: homepage, https://example.com
Project-URL: homepage, https://another.example.com
Expand Down

0 comments on commit d0c848a

Please sign in to comment.