535 lines
41 KiB
HTML
535 lines
41 KiB
HTML
|
||
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="color-scheme" content="light dark">
|
||
<title>PEP 753 – Uniform project URLs in core metadata | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0753/">
|
||
<link rel="stylesheet" href="../_static/style.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/mq.css" type="text/css">
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light">
|
||
<link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark">
|
||
<link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss">
|
||
<meta property="og:title" content='PEP 753 – Uniform project URLs in core metadata | peps.python.org'>
|
||
<meta property="og:description" content="This PEP recommends two discrete changes to the processing of core metadata by indices (such as PyPI) and other core metadata consumers:">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0753/">
|
||
<meta property="og:site_name" content="Python Enhancement Proposals (PEPs)">
|
||
<meta property="og:image" content="https://peps.python.org/_static/og-image.png">
|
||
<meta property="og:image:alt" content="Python PEPs">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="description" content="This PEP recommends two discrete changes to the processing of core metadata by indices (such as PyPI) and other core metadata consumers:">
|
||
<meta name="theme-color" content="#3776ab">
|
||
</head>
|
||
<body>
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
|
||
<symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Following system colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="9"></circle>
|
||
<path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected dark colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
|
||
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all">
|
||
<title>Selected light colour scheme</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
|
||
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
||
<circle cx="12" cy="12" r="5"></circle>
|
||
<line x1="12" y1="1" x2="12" y2="3"></line>
|
||
<line x1="12" y1="21" x2="12" y2="23"></line>
|
||
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
|
||
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
|
||
<line x1="1" y1="12" x2="3" y2="12"></line>
|
||
<line x1="21" y1="12" x2="23" y2="12"></line>
|
||
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
|
||
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
|
||
</svg>
|
||
</symbol>
|
||
</svg>
|
||
<script>
|
||
|
||
document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto"
|
||
</script>
|
||
<section id="pep-page-section">
|
||
<header>
|
||
<h1>Python Enhancement Proposals</h1>
|
||
<ul class="breadcrumbs">
|
||
<li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li>
|
||
<li><a href="../pep-0000/">PEP Index</a> » </li>
|
||
<li>PEP 753</li>
|
||
</ul>
|
||
<button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())">
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
<span class="visually-hidden">Toggle light / dark / auto colour theme</span>
|
||
</button>
|
||
</header>
|
||
<article>
|
||
<section id="pep-content">
|
||
<h1 class="page-title">PEP 753 – Uniform project URLs in core metadata</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">William Woodruff <william at yossarian.net>,
|
||
Facundo Tuesca <facundo.tuesca at trailofbits.com></dd>
|
||
<dt class="field-even">Sponsor<span class="colon">:</span></dt>
|
||
<dd class="field-even">Barry Warsaw <barry at python.org></dd>
|
||
<dt class="field-odd">PEP-Delegate<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Paul Moore <p.f.moore at gmail.com></dd>
|
||
<dt class="field-even">Discussions-To<span class="colon">:</span></dt>
|
||
<dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-753-uniform-urls-in-core-metadata/62792">Discourse thread</a></dd>
|
||
<dt class="field-odd">Status<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Normative proposal accepted for implementation">Accepted</abbr></dd>
|
||
<dt class="field-even">Type<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd>
|
||
<dt class="field-odd">Topic<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="../topic/packaging/">Packaging</a></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">29-Aug-2024</dd>
|
||
<dt class="field-odd">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/core-metadata-should-home-page-and-download-url-be-deprecated/62037" title="Discourse thread">26-Aug-2024</a>,
|
||
<a class="reference external" href="https://discuss.python.org/t/pep-753-uniform-urls-in-core-metadata/62792" title="Discourse thread">03-Sep-2024</a></dd>
|
||
<dt class="field-even">Resolution<span class="colon">:</span></dt>
|
||
<dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/62792/30">10-Oct-2024</a></dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<section id="contents">
|
||
<details><summary>Table of Contents</summary><ul class="simple">
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#rationale-and-motivation">Rationale and Motivation</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#metadata-producers">Metadata producers</a></li>
|
||
<li><a class="reference internal" href="#package-indices">Package indices</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#conventions-for-project-url-labels">Conventions for <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> labels</a><ul>
|
||
<li><a class="reference internal" href="#label-normalization">Label normalization</a></li>
|
||
<li><a class="reference internal" href="#well-known-labels">Well-known labels</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a><ul>
|
||
<li><a class="reference internal" href="#limited-impact">Limited Impact</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#future-considerations">Future Considerations</a></li>
|
||
<li><a class="reference internal" href="#security-implications">Security Implications</a></li>
|
||
<li><a class="reference internal" href="#how-to-teach-this">How To Teach This</a></li>
|
||
<li><a class="reference internal" href="#appendix-a-label-normalization-examples">Appendix A: Label normalization examples</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<div class="pep-banner canonical-pypa-spec sticky-banner admonition attention">
|
||
<p class="admonition-title">Attention</p>
|
||
<p>This PEP is a historical document. The up-to-date, canonical spec, <a class="reference external" href="https://packaging.python.org/en/latest/specifications/well-known-project-urls/#well-known-project-urls" title="(in Python Packaging User Guide)"><span>Well-known Project URLs in Metadata</span></a>, is maintained on the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/">PyPA specs page</a>.</p>
|
||
<p class="close-button">×</p>
|
||
<p>See the <a class="reference external" href="https://www.pypa.io/en/latest/specifications/#handling-fixes-and-other-minor-updates">PyPA specification update process</a> for how to propose changes.</p>
|
||
</div>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>This PEP recommends two discrete changes to the processing of core metadata by
|
||
indices (such as PyPI) and other core metadata consumers:</p>
|
||
<ul class="simple">
|
||
<li>Deprecation of the <code class="docutils literal notranslate"><span class="pre">Home-page</span></code> and <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code> fields in favor of
|
||
their <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> equivalents;</li>
|
||
<li>A set of <a class="reference internal" href="#conventions-for-labels"><span class="std std-ref">conventions</span></a> for normalizing and
|
||
assigning semantics to <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> labels during consumer-side metadata
|
||
processing.</li>
|
||
</ul>
|
||
</section>
|
||
<section id="rationale-and-motivation">
|
||
<h2><a class="toc-backref" href="#rationale-and-motivation" role="doc-backlink">Rationale and Motivation</a></h2>
|
||
<p>Python’s standard <a class="reference external" href="https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata" title="(in Python Packaging User Guide)"><span class="xref std std-ref">core metadata</span></a> has gone
|
||
through many years of revisions, with various standardized milestone versions.</p>
|
||
<p>These revisions of the core metadata have introduced various mechanisms
|
||
for expressing a package’s relationship to external resources, via URLs:</p>
|
||
<ol class="arabic">
|
||
<li>Metadata 1.0 introduced <code class="docutils literal notranslate"><span class="pre">Home-page</span></code>, a single-use field containing
|
||
a URL to the distribution’s home page.<div class="highlight-email notranslate"><div class="highlight"><pre><span></span><span class="nt">Home-page:</span><span class="w"> </span>https://<span class="nf">example.com</span>/sampleproject
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Metadata 1.1 introduced <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code>, a complementary single-use field
|
||
containing a URL suitable for downloading the current distribution.<div class="highlight-email notranslate"><div class="highlight"><pre><span></span><span class="nt">Download-URL:</span><span class="w"> </span>https://<span class="nf">example.com</span>/sampleproject/<span class="nf">sampleproject-1.2.3.tar.gz</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li>Metadata 1.2 introduced <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code>, a <strong>multiple-use</strong> field containing
|
||
a label-and-URL pair. Each label is free text conveying the URL’s semantics.<div class="highlight-email notranslate"><div class="highlight"><pre><span></span><span class="nt">Project-URL:</span><span class="w"> </span>Homepage,<span class="w"> </span>https://<span class="nf">example.com</span>/sampleproject
|
||
<span class="nt">Project-URL:</span><span class="w"> </span>Download,<span class="w"> </span>https://<span class="nf">example.com</span>/sampleproject/<span class="nf">sampleproject-1.2.3.tar.gz</span>
|
||
<span class="nt">Project-URL:</span><span class="w"> </span>Documentation,<span class="w"> </span>https://<span class="nf">example.com</span>/sampleproject/docs
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ol>
|
||
<p>Metadata 2.1, 2.2, and 2.3 leave the behavior of these fields as originally
|
||
specified.</p>
|
||
<p>Because <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> allows free text labels and is multiple-use, informal
|
||
conventions have arisen for representing the values of
|
||
<code class="docutils literal notranslate"><span class="pre">Home-page</span></code> and <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code> within <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> instead.</p>
|
||
<p>These conventions have seen significant adoption, with <a class="pep reference internal" href="../pep-0621/" title="PEP 621 – Storing project metadata in pyproject.toml">PEP 621</a> explicitly
|
||
choosing to provide only a <code class="docutils literal notranslate"><span class="pre">project.urls</span></code> table rather than a
|
||
<code class="docutils literal notranslate"><span class="pre">project.home-page</span></code> field. From <a class="pep reference internal" href="../pep-0621/" title="PEP 621 – Storing project metadata in pyproject.toml">PEP 621</a>’s rejected ideas:</p>
|
||
<blockquote class="pull-quote">
|
||
<div>While the core metadata supports it, having a single field for a project’s
|
||
URL while also supporting a full table seemed redundant and confusing.</div></blockquote>
|
||
<p>This PEP exists to formalize the informal conventions that have arisen, as well
|
||
as explicitly document <code class="docutils literal notranslate"><span class="pre">Home-page</span></code> and <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code> as deprecated in
|
||
favor of equivalent <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> representations.</p>
|
||
</section>
|
||
<section id="specification">
|
||
<h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2>
|
||
<p>This PEP proposes that <code class="docutils literal notranslate"><span class="pre">Home-page</span></code> and <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code> be considered
|
||
<strong>deprecated</strong>. This deprecation has implications for both package metadata
|
||
producers (e.g. build backends and packaging tools) and package indices
|
||
(e.g. PyPI).</p>
|
||
<section id="metadata-producers">
|
||
<span id="id1"></span><h3><a class="toc-backref" href="#metadata-producers" role="doc-backlink">Metadata producers</a></h3>
|
||
<p>This PEP stipulates the following for metadata producers:</p>
|
||
<ul class="simple">
|
||
<li>When generating metadata 1.2 or later, producers <strong>SHOULD</strong> emit only
|
||
<code class="docutils literal notranslate"><span class="pre">Project-URL</span></code>, and <strong>SHOULD NOT</strong> emit <code class="docutils literal notranslate"><span class="pre">Home-page</span></code> or <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code>
|
||
fields.</li>
|
||
</ul>
|
||
<p>These stipulations do not change the optionality of URL fields in core metadata.
|
||
In other words, producers <strong>MAY</strong> choose to omit <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> entirely
|
||
at their discretion.</p>
|
||
<p>This PEP does <strong>not</strong> propose the outright removal of support for <code class="docutils literal notranslate"><span class="pre">Home-page</span></code>
|
||
or <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code>. However, see <a class="reference internal" href="#future-considerations"><span class="std std-ref">Future Considerations</span></a> 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.</p>
|
||
<p>Similarly, this PEP does <strong>not</strong> propose that metadata producers emit
|
||
<a class="reference internal" href="#label-normalization"><span class="std std-ref">normalized labels</span></a>. Label normalization is performed
|
||
solely on the processing and consumption side (i.e. within indices and other
|
||
consumers of distribution metadata).</p>
|
||
</section>
|
||
<section id="package-indices">
|
||
<span id="id2"></span><h3><a class="toc-backref" href="#package-indices" role="doc-backlink">Package indices</a></h3>
|
||
<p>This PEP stipulates the following for package indices:</p>
|
||
<ul class="simple">
|
||
<li>When interpreting a distribution’s metadata of version 1.2 or later
|
||
(e.g. for rendering on a web page), the index <strong>MUST</strong> prefer
|
||
<code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> fields as a source of URLs over <code class="docutils literal notranslate"><span class="pre">Home-page</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">Download-URL</span></code>, even if the latter are explicitly provided.</li>
|
||
<li>If a distribution’s metadata contains only the <code class="docutils literal notranslate"><span class="pre">Home-page</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">Download-URL</span></code> fields, the index <strong>MAY</strong> choose to ignore those fields
|
||
and behave as though no URLs were provided in the metadata. In this case,
|
||
the index <strong>SHOULD</strong> present an appropriate warning or notification to
|
||
the uploading party.<ul>
|
||
<li>The mechanism for presenting this warning or notification is not
|
||
specified, since it will vary by index. By way of example, an index may
|
||
choose to present a warning in the HTTP response to an upload request, or
|
||
send an email or other notification to the maintainer(s) of the project.</li>
|
||
</ul>
|
||
</li>
|
||
<li>If a distribution’s metadata contains both sets of fields, the index <strong>MAY</strong>
|
||
choose to reject the distribution outright. However, this is
|
||
<strong>NOT RECOMMENDED</strong> until a future unspecified major metadata version
|
||
formally removes support for <code class="docutils literal notranslate"><span class="pre">Home-page</span></code> and <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code>.</li>
|
||
<li>Any changes to the interpretation of metadata of version 1.2 or later that
|
||
result in previously recognized URLs no longer being recognized
|
||
<strong>SHOULD NOT</strong> be retroactively applied to previously uploaded packages.</li>
|
||
</ul>
|
||
<p>These stipulations do not change the optionality of URL processing by indices.
|
||
In other words, an index that does not process URLs within uploaded
|
||
distributions may continue to ignore all URL fields entirely.</p>
|
||
<p>Similarly, these stipulations do <strong>not</strong> imply that the index should
|
||
persist any normalizations that it performs to a distribution’s metadata.
|
||
In other words, this PEP stipulates label normalization for the purpose
|
||
of user presentation, not for the purpose of modifying an uploaded distribution
|
||
or its “sidecar” <a class="pep reference internal" href="../pep-0658/" title="PEP 658 – Serve Distribution Metadata in the Simple Repository API">PEP 658</a> metadata file.</p>
|
||
</section>
|
||
</section>
|
||
<section id="conventions-for-project-url-labels">
|
||
<span id="conventions-for-labels"></span><h2><a class="toc-backref" href="#conventions-for-project-url-labels" role="doc-backlink">Conventions for <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> labels</a></h2>
|
||
<p>The deprecations proposed above require a formalization of the currently
|
||
informal relationship between <code class="docutils literal notranslate"><span class="pre">Home-page</span></code>, <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code>, and their
|
||
<code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> equivalents.</p>
|
||
<p>This formalization has two parts:</p>
|
||
<ol class="arabic simple">
|
||
<li>A set of rules for normalizing <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> labels during index-side
|
||
processing;</li>
|
||
<li>A set of “well-known” normalized label values that indices may specialize
|
||
URL presentation for.</li>
|
||
</ol>
|
||
<section id="label-normalization">
|
||
<span id="id3"></span><h3><a class="toc-backref" href="#label-normalization" role="doc-backlink">Label normalization</a></h3>
|
||
<p>The core metadata specification stipulates that <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> labels are
|
||
free text, limited to 32 characters.</p>
|
||
<p>This PEP proposes adding the concept of a “normalized” label to the core
|
||
metadata specification. Label normalization is defined via the following
|
||
Python function:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">string</span>
|
||
<span class="k">def</span> <span class="nf">normalize_label</span><span class="p">(</span><span class="n">label</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-></span> <span class="nb">str</span><span class="p">:</span>
|
||
<span class="n">chars_to_remove</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">punctuation</span> <span class="o">+</span> <span class="n">string</span><span class="o">.</span><span class="n">whitespace</span>
|
||
<span class="n">removal_map</span> <span class="o">=</span> <span class="nb">str</span><span class="o">.</span><span class="n">maketrans</span><span class="p">(</span><span class="s2">""</span><span class="p">,</span> <span class="s2">""</span><span class="p">,</span> <span class="n">chars_to_remove</span><span class="p">)</span>
|
||
<span class="k">return</span> <span class="n">label</span><span class="o">.</span><span class="n">translate</span><span class="p">(</span><span class="n">removal_map</span><span class="p">)</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In plain language: a label is <em>normalized</em> by deleting all ASCII punctuation and
|
||
whitespace, and then converting the result to lowercase.</p>
|
||
<p>The following table shows examples of labels before (raw) and after
|
||
normalization:</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head">Raw</th>
|
||
<th class="head">Normalized</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">Homepage</span></code></td>
|
||
<td><code class="docutils literal notranslate"><span class="pre">homepage</span></code></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">Home-page</span></code></td>
|
||
<td><code class="docutils literal notranslate"><span class="pre">homepage</span></code></td>
|
||
</tr>
|
||
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">Home</span> <span class="pre">page</span></code></td>
|
||
<td><code class="docutils literal notranslate"><span class="pre">homepage</span></code></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">Change_Log</span></code></td>
|
||
<td><code class="docutils literal notranslate"><span class="pre">changelog</span></code></td>
|
||
</tr>
|
||
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">What's</span> <span class="pre">New?</span></code></td>
|
||
<td><code class="docutils literal notranslate"><span class="pre">whatsnew</span></code></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>When processing distribution metadata, package indices <strong>SHOULD</strong> perform
|
||
label normalization to determine if a given label is
|
||
<a class="reference internal" href="#well-known"><span class="std std-ref">well known</span></a> for subsequent special processing.
|
||
Labels that are not well-known <strong>MUST</strong> be processed in their un-normalized
|
||
form.</p>
|
||
<p>Normalization does <strong>not</strong> change pre-existing semantics around duplicated
|
||
<code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> 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 <a class="reference external" href="https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata" title="(in Python Packaging User Guide)"><span class="xref std std-ref">core metadata specification</span></a> does
|
||
not stipulate that labels are unique).</p>
|
||
<p>Excerpted examples of normalized metadata fields are provided in
|
||
<a class="reference internal" href="#appendix-a"><span class="std std-ref">Appendix A</span></a>.</p>
|
||
</section>
|
||
<section id="well-known-labels">
|
||
<span id="well-known"></span><h3><a class="toc-backref" href="#well-known-labels" role="doc-backlink">Well-known labels</a></h3>
|
||
<p>In addition to the normalization rules above, this PEP proposes a
|
||
fixed (but extensible) set of “well-known” <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> labels,
|
||
as well as aliases and human-readable equivalents.</p>
|
||
<p>The following table lists these labels, in normalized form:</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head">Label (Human-readable equivalent)</th>
|
||
<th class="head">Description</th>
|
||
<th class="head">Aliases</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">homepage</span></code> (Homepage)</td>
|
||
<td>The project’s home page</td>
|
||
<td><em>(none)</em></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">source</span></code> (Source Code)</td>
|
||
<td>The project’s hosted source code or repository</td>
|
||
<td><code class="docutils literal notranslate"><span class="pre">repository</span></code>, <code class="docutils literal notranslate"><span class="pre">sourcecode</span></code>, <code class="docutils literal notranslate"><span class="pre">github</span></code></td>
|
||
</tr>
|
||
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">download</span></code> (Download)</td>
|
||
<td>A download URL for the current distribution, equivalent to <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code></td>
|
||
<td><em>(none)</em></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">changelog</span></code> (Changelog)</td>
|
||
<td>The project’s comprehensive changelog</td>
|
||
<td><code class="docutils literal notranslate"><span class="pre">changes</span></code>, <code class="docutils literal notranslate"><span class="pre">whatsnew</span></code>, <code class="docutils literal notranslate"><span class="pre">history</span></code></td>
|
||
</tr>
|
||
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">releasenotes</span></code> (Release Notes)</td>
|
||
<td>The project’s curated release notes</td>
|
||
<td><em>(none)</em></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">documentation</span></code> (Documentation)</td>
|
||
<td>The project’s online documentation</td>
|
||
<td><code class="docutils literal notranslate"><span class="pre">docs</span></code></td>
|
||
</tr>
|
||
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">issues</span></code> (Issue Tracker)</td>
|
||
<td>The project’s bug tracker</td>
|
||
<td><code class="docutils literal notranslate"><span class="pre">bugs</span></code>, <code class="docutils literal notranslate"><span class="pre">issue</span></code>, <code class="docutils literal notranslate"><span class="pre">tracker</span></code>, <code class="docutils literal notranslate"><span class="pre">issuetracker</span></code>, <code class="docutils literal notranslate"><span class="pre">bugtracker</span></code></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">funding</span></code> (Funding)</td>
|
||
<td>Funding Information</td>
|
||
<td><code class="docutils literal notranslate"><span class="pre">sponsor</span></code>, <code class="docutils literal notranslate"><span class="pre">donate</span></code>, <code class="docutils literal notranslate"><span class="pre">donation</span></code></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Indices <strong>MAY</strong> choose to use the human-readable equivalents suggested above
|
||
in their UI elements, if appropriate. Alternatively, indices <strong>MAY</strong> choose
|
||
their own appropriate human-readable equivalents for UI elements.</p>
|
||
<p>Packagers and metadata producers <strong>MAY</strong> choose to use any label that normalizes
|
||
to these labels (or their aliases) to communicate specific URL intents to
|
||
package indices and downstreams.</p>
|
||
<p>Similarly, indices <strong>MAY</strong> choose to specialize their rendering or presentation
|
||
of URLs with these labels, e.g. by presenting an appropriate icon or tooltip
|
||
for each label.</p>
|
||
<p>Indices <strong>MAY</strong> also specialize the rendering or presentation of additional
|
||
labels or URLs, including (but not limited to), labels that start with a
|
||
well-known label, and URLs that refer to a known service provider domain (e.g.
|
||
for documentation hosting or issue tracking).</p>
|
||
<p>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 such,
|
||
this PEP proposes that the list above become a “living” list within
|
||
the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/#packaging-specifications" title="(in Python Packaging User Guide)"><span class="xref std std-ref">PyPA specifications</span></a>.</p>
|
||
</section>
|
||
</section>
|
||
<section id="backwards-compatibility">
|
||
<h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2>
|
||
<section id="limited-impact">
|
||
<h3><a class="toc-backref" href="#limited-impact" role="doc-backlink">Limited Impact</a></h3>
|
||
<p>This PEP is expected to have little to no impact on existing packaging tooling
|
||
or package indices:</p>
|
||
<ul class="simple">
|
||
<li>Packaging tooling: no changes to the correctness or well-formedness
|
||
of the core metadata. This PEP proposes deprecations as well as behavioral
|
||
refinements, but all currently (and historically) produced metadata will
|
||
continue to be valid per the rules of its respective version.</li>
|
||
<li>Package indices: indices will continue to expect well-formed core metadata,
|
||
with no behavioral changes. Indices <strong>MAY</strong> choose to emit warnings or
|
||
notifications on the presence of now-deprecated fields,
|
||
<a class="reference internal" href="#package-indices"><span class="std std-ref">per above</span></a>.</li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
<section id="future-considerations">
|
||
<span id="id4"></span><h2><a class="toc-backref" href="#future-considerations" role="doc-backlink">Future Considerations</a></h2>
|
||
<p>This PEP does not stipulate or require any future metadata changes.</p>
|
||
<p>However, per <a class="reference internal" href="#metadata-producers"><span class="std std-ref">Metadata producers</span></a> and <a class="reference internal" href="#conventions-for-labels"><span class="std std-ref">Conventions for Project-URL labels</span></a>,
|
||
we identify the following potential future goals for a new major release of
|
||
the core metadata standards:</p>
|
||
<ul class="simple">
|
||
<li>Outright removal of support for <code class="docutils literal notranslate"><span class="pre">Home-page</span></code> and <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code> in the
|
||
next major core metadata version. If removed, package indices and consumers
|
||
<strong>MUST</strong> reject metadata containing these fields when said metadata is of
|
||
the new major version.</li>
|
||
<li>Enforcement of label normalization. If enforced, package producers
|
||
<strong>MUST</strong> emit only normalized <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> labels when generating
|
||
distribution metadata, and package indices and consumers <strong>MUST</strong> reject
|
||
distributions containing non-normalized labels. Note: requiring
|
||
normalization merely restricts labels to lowercase text, and excludes
|
||
whitespace and punctuation. It does NOT restrict project URLs solely to
|
||
the use of “well-known” labels.</li>
|
||
</ul>
|
||
<p>These potential changes would be backwards incompatible, hence their
|
||
inclusion only in this section. Acceptance of this PEP does NOT commit
|
||
any future metadata revision to actually making these changes.</p>
|
||
</section>
|
||
<section id="security-implications">
|
||
<h2><a class="toc-backref" href="#security-implications" role="doc-backlink">Security Implications</a></h2>
|
||
<p>This PEP does not identify any positive or negative security implications
|
||
associated with deprecating <code class="docutils literal notranslate"><span class="pre">Home-page</span></code> and <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code> or with
|
||
label normalization.</p>
|
||
</section>
|
||
<section id="how-to-teach-this">
|
||
<h2><a class="toc-backref" href="#how-to-teach-this" role="doc-backlink">How To Teach This</a></h2>
|
||
<p>The changes in this PEP should be transparent to the majority of the packaging
|
||
ecosystem’s userbase; the primary beneficiaries of this PEP’s changes are
|
||
packaging tooling authors and index maintainers, who will be able to reduce the
|
||
number of unique URL fields produced and checked.</p>
|
||
<p>A small number of package maintainers may observe new warnings or notifications
|
||
from their index of choice, should the index choose to ignore <code class="docutils literal notranslate"><span class="pre">Home-page</span></code>
|
||
and <code class="docutils literal notranslate"><span class="pre">Download-URL</span></code> as suggested. Similarly, a small number of package
|
||
maintainers may observe that their index of choice no longer renders
|
||
their URLs, if only present in the deprecated fields. However, no package
|
||
maintainers should observe rejected package uploads or other breaking
|
||
changes to packaging workflows due to this PEP’s proposed changes.</p>
|
||
<p>Anybody who observes warnings or changes to the presentation of
|
||
URLs on indices can be taught about this PEP’s behavior via official
|
||
packaging resources, such as the
|
||
<a class="reference external" href="https://packaging.python.org/en/latest/key_projects/#packaging" title="(in Python Packaging User Guide)"><span class="xref std std-ref">Python Packaging User Guide</span></a>
|
||
and <a class="reference external" href="https://docs.pypi.org/">PyPI’s user documentation</a>, the latter of which
|
||
already contains an informal description of PyPI’s URL handling behavior.</p>
|
||
<p>If this PEP is accepted, the authors of this PEP will coordinate to update
|
||
and cross-link the resources mentioned above.</p>
|
||
</section>
|
||
<section id="appendix-a-label-normalization-examples">
|
||
<span id="appendix-a"></span><h2><a class="toc-backref" href="#appendix-a-label-normalization-examples" role="doc-backlink">Appendix A: Label normalization examples</a></h2>
|
||
<p>This appendix provides an illustrative excerpt of a distribution’s
|
||
metadata, before and after index-side processing:</p>
|
||
<p>Before:</p>
|
||
<div class="highlight-email notranslate"><div class="highlight"><pre><span></span><span class="nt">Project-URL:</span><span class="w"> </span>Home-page,<span class="w"> </span>https://<span class="nf">example.com</span>
|
||
<span class="nt">Project-URL:</span><span class="w"> </span>Homepage,<span class="w"> </span>https://<span class="nf">another.example.com</span>
|
||
<span class="nt">Project-URL:</span><span class="w"> </span>Source,<span class="w"> </span>https://<span class="nf">github.com</span>/example/example
|
||
<span class="nt">Project-URL:</span><span class="w"> </span>GitHub,<span class="w"> </span>https://<span class="nf">github.com</span>/example/example
|
||
<span class="nt">Project-URL:</span><span class="w"> </span>Another<span class="w"> </span>Service,<span class="w"> </span>https://<span class="nf">custom.example.com</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>After:</p>
|
||
<div class="highlight-email notranslate"><div class="highlight"><pre><span></span><span class="nt">Project-URL:</span><span class="w"> </span>homepage,<span class="w"> </span>https://<span class="nf">example.com</span>
|
||
<span class="nt">Project-URL:</span><span class="w"> </span>homepage,<span class="w"> </span>https://<span class="nf">another.example.com</span>
|
||
<span class="nt">Project-URL:</span><span class="w"> </span>source,<span class="w"> </span>https://<span class="nf">github.com</span>/example/example
|
||
<span class="nt">Project-URL:</span><span class="w"> </span>github,<span class="w"> </span>https://<span class="nf">github.com</span>/example/example
|
||
<span class="nt">Project-URL:</span><span class="w"> </span>Another<span class="w"> </span>Service,<span class="w"> </span>https://<span class="nf">custom.example.com</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In particular, observe:</p>
|
||
<ul class="simple">
|
||
<li>Normalized duplicates are preserved (both <code class="docutils literal notranslate"><span class="pre">Home-page</span></code> and <code class="docutils literal notranslate"><span class="pre">Homepage</span></code>
|
||
become <code class="docutils literal notranslate"><span class="pre">homepage</span></code>);</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">Source</span></code> and <code class="docutils literal notranslate"><span class="pre">GitHub</span></code> are both normalized into their respective forms,
|
||
but <code class="docutils literal notranslate"><span class="pre">github</span></code> is <strong>not</strong> transformed into <code class="docutils literal notranslate"><span class="pre">source</span></code>.</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">Another</span> <span class="pre">Service</span></code> is <strong>not</strong> normalized, since its normal form
|
||
(<code class="docutils literal notranslate"><span class="pre">anotherservice</span></code>) is not a <a class="reference internal" href="#well-known"><span class="std std-ref">well-known label</span></a>.</li>
|
||
</ul>
|
||
</section>
|
||
<section id="copyright">
|
||
<h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2>
|
||
<p>This document is placed in the public domain or under the
|
||
CC0-1.0-Universal license, whichever is more permissive.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0753.rst">https://github.com/python/peps/blob/main/peps/pep-0753.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0753.rst">2024-10-30 06:11:26 GMT</a></p>
|
||
|
||
</article>
|
||
<nav id="pep-sidebar">
|
||
<h2>Contents</h2>
|
||
<ul>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#rationale-and-motivation">Rationale and Motivation</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#metadata-producers">Metadata producers</a></li>
|
||
<li><a class="reference internal" href="#package-indices">Package indices</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#conventions-for-project-url-labels">Conventions for <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code> labels</a><ul>
|
||
<li><a class="reference internal" href="#label-normalization">Label normalization</a></li>
|
||
<li><a class="reference internal" href="#well-known-labels">Well-known labels</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a><ul>
|
||
<li><a class="reference internal" href="#limited-impact">Limited Impact</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#future-considerations">Future Considerations</a></li>
|
||
<li><a class="reference internal" href="#security-implications">Security Implications</a></li>
|
||
<li><a class="reference internal" href="#how-to-teach-this">How To Teach This</a></li>
|
||
<li><a class="reference internal" href="#appendix-a-label-normalization-examples">Appendix A: Label normalization examples</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
|
||
<br>
|
||
<a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0753.rst">Page Source (GitHub)</a>
|
||
</nav>
|
||
</section>
|
||
<script src="../_static/colour_scheme.js"></script>
|
||
<script src="../_static/wrap_tables.js"></script>
|
||
<script src="../_static/sticky_banner.js"></script>
|
||
</body>
|
||
</html> |