iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 753: Updates (#4010) 

Signed-off-by: William Woodruff <william@yossarian.net>
Co-authored-by: Paul Moore <p.f.moore@gmail.com>
This commit is contained in:
William Woodruff 2024-10-07 15:11:12 -04:00 committed by GitHub
parent ada0f55a8e
commit 9cb9d4e82f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 76 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
peps/pep-0753.rst
View File

@ -15,13 +15,14 @@ Post-History: `26-Aug-2024 <https://discuss.python.org/t/core-metadata-should-ho
Abstract Abstract
======== ========
This PEP recommends two discrete changes to handling of core metadata by This PEP recommends two discrete changes to the processing of core metadata by
indices, such as PyPI: indices (such as PyPI) and other core metadata consumers:
* Deprecation of the ``Home-page`` and ``Download-URL`` fields in favor of * Deprecation of the ``Home-page`` and ``Download-URL`` fields in favor of
their ``Project-URL`` equivalents; their ``Project-URL`` equivalents;
* A set of conventions for normalizing and assigning semantics to * A set of :ref:`conventions <conventions-for-labels>` for normalizing and
``Project-URL`` labels. assigning semantics to ``Project-URL`` labels during consumer-side metadata
processing.
Rationale and Motivation Rationale and Motivation
======================== ========================
@ -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 1. Metadata 1.0 introduced ``Home-page``, a single-use field containing
a URL to the distribution's home page. a URL to the distribution's home page.
.. code-block:: .. code-block:: email
Home-page: https://example.com/sampleproject Home-page: https://example.com/sampleproject
2. Metadata 1.1 introduced ``Download-URL``, a complementary single-use field 2. Metadata 1.1 introduced ``Download-URL``, a complementary single-use field
containing a URL suitable for downloading the current distribution. 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 Download-URL: https://example.com/sampleproject/sampleproject-1.2.3.tar.gz
3. Metadata 1.2 introduced ``Project-URL``, a **multiple-use** field containing 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. 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: Homepage, https://example.com/sampleproject
Project-URL: Download, https://example.com/sampleproject/sampleproject-1.2.3.tar.gz Project-URL: Download, https://example.com/sampleproject/sampleproject-1.2.3.tar.gz
@ -93,9 +94,6 @@ This PEP stipulates the following for metadata producers:
* When generating metadata 1.2 or later, producers **SHOULD** emit only * When generating metadata 1.2 or later, producers **SHOULD** emit only
``Project-URL``, and **SHOULD NOT** emit ``Home-page`` or ``Download-URL`` ``Project-URL``, and **SHOULD NOT** emit ``Home-page`` or ``Download-URL``
fields. 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. These stipulations do not change the optionality of URL fields in core metadata.
In other words, producers **MAY** choose to omit ``Project-URL`` entirely In other words, producers **MAY** choose to omit ``Project-URL`` entirely
@ -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 thoughts on how a new (as of yet unspecified) major core metadata version
could complete the deprecation cycle via removal of these deprecated fields. 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:
Package indices Package indices
@ -153,10 +156,13 @@ informal relationship between ``Home-page``, ``Download-URL``, and their
This formalization has two parts: 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 2. A set of "well-known" normalized label values that indices may specialize
URL presentation for. URL presentation for.
.. _label-normalization:
Label normalization Label normalization
------------------- -------------------
@ -190,14 +196,22 @@ normalization:
"``Change_Log``", "``changelog``" "``Change_Log``", "``changelog``"
"``What's New?``", "``whatsnew``" "``What's New?``", "``whatsnew``"
Metadata producers **SHOULD** emit the normalized form of a user When processing distribution metadata, package indices **SHOULD** perform
specified label, but **MAY** choose to emit the un-normalized form so label normalization to determine if a given label is
long as it adheres to the existing 32 character constraint. :ref:`well known <well-known>` for subsequent special processing.
Labels that are not well-known **MUST** be processed in their un-normalized
form.
Package indices **SHOULD NOT** use the normalized labels belonging to the set Normalization does **not** change pre-existing semantics around duplicated
of well-known labels directly as UI elements (instead replacing them with ``Project-URL`` labels. In other words, normalization may result in duplicate
appropriately capitalized text labels). Labels not belonging to the well-known labels in the project's metadata, but only in the same manner that was already permitted
set **MAY** be used directly as UI elements. (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 Well-known labels
----------------- -----------------
@ -243,15 +257,9 @@ Indices **MAY** choose to use the human-readable equivalents suggested above
in their UI elements, if appropriate. Alternatively, indices **MAY** choose in their UI elements, if appropriate. Alternatively, indices **MAY** choose
their own appropriate human-readable equivalents for UI elements. their own appropriate human-readable equivalents for UI elements.
Packagers and metadata producers **MAY** choose to use these well-known Packagers and metadata producers **MAY** choose to use any label that normalizes
labels or their aliases to communicate specific URL intents to package indices to these labels (or their aliases) to communicate specific URL intents to
and downstreams. 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``.
Similarly, indices **MAY** choose to specialize their rendering or presentation Similarly, indices **MAY** choose to specialize their rendering or presentation
of URLs with these labels, e.g. by presenting an appropriate icon or tooltip of URLs with these labels, e.g. by presenting an appropriate icon or tooltip
@ -264,12 +272,9 @@ for documentation hosting or issue tracking).
This PEP recognizes that the list of well-known labels is unlikely to remain 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 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 associated with a formal PEP process or new metadata version. As such,
expected use case for this information is to control the way project URLs are this PEP proposes that the list above become a "living" list within
displayed on the Python Package Index, this PEP proposes that the list above the :ref:`PyPA specifications <packaging:packaging-specifications>`.
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>`__).
Backwards Compatibility Backwards Compatibility
======================= =======================
@ -349,6 +354,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 If this PEP is accepted, the authors of this PEP will coordinate to update
and cross-link the resources mentioned above. 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 index-side processing:
Before:
.. code-block:: email
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:: email
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 Copyright
========= =========