CINXE.COM

<!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>