312 lines
21 KiB
HTML
312 lines
21 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 643 – Metadata for Package Source Distributions | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0643/">
|
||
<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 643 – Metadata for Package Source Distributions | peps.python.org'>
|
||
<meta property="og:description" content="Python package metadata is stored in the distribution file in a standard format, defined in the Core Metadata Specification. However, for source distributions, while the format of the data is defined, there has traditionally been a lot of inconsistency ...">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0643/">
|
||
<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="Python package metadata is stored in the distribution file in a standard format, defined in the Core Metadata Specification. However, for source distributions, while the format of the data is defined, there has traditionally been a lot of inconsistency ...">
|
||
<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 643</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 643 – Metadata for Package Source Distributions</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Paul Moore <p.f.moore at gmail.com></dd>
|
||
<dt class="field-even">BDFL-Delegate<span class="colon">:</span></dt>
|
||
<dd class="field-even">Paul Ganssle <paul at ganssle.io></dd>
|
||
<dt class="field-odd">Discussions-To<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-643-metadata-for-package-source-distributions/5577">Discourse thread</a></dd>
|
||
<dt class="field-even">Status<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd>
|
||
<dt class="field-odd">Type<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><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-even">Topic<span class="colon">:</span></dt>
|
||
<dd class="field-even"><a class="reference external" href="../topic/packaging/">Packaging</a></dd>
|
||
<dt class="field-odd">Created<span class="colon">:</span></dt>
|
||
<dd class="field-odd">24-Oct-2020</dd>
|
||
<dt class="field-even">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-even">24-Oct-2020, 01-Nov-2020, 02-Nov-2020, 14-Nov-2020</dd>
|
||
<dt class="field-odd">Resolution<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-643-metadata-for-package-source-distributions/5577/53">Discourse message</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="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a></li>
|
||
<li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</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="#rejected-ideas">Rejected Ideas</a></li>
|
||
<li><a class="reference internal" href="#open-issues">Open Issues</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/core-metadata/#core-metadata" title="(in Python Packaging User Guide)"><span>Core metadata specifications</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>Python package metadata is stored in the distribution file in a standard
|
||
format, defined in the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core Metadata Specification</a>. However, for
|
||
source distributions, while the format of the data is defined, there has
|
||
traditionally been a lot of inconsistency in what data is recorded in
|
||
the source distribution. See <a class="reference external" href="https://discuss.python.org/t/why-isnt-source-distribution-metadata-trustworthy-can-we-make-it-so/2620">here</a>
|
||
for a discussion of this issue.</p>
|
||
<p>As a result, metadata consumers are unable to rely on the data available
|
||
from source distributions, and need to use the (costly) <a class="pep reference internal" href="../pep-0517/" title="PEP 517 – A build-system independent format for source trees">PEP 517</a> build
|
||
mechanisms to extract medatata.</p>
|
||
<p>This PEP defines a standard that allows build backends to reliably store
|
||
package metadata in the source distribution, while still retaining the
|
||
necessary flexibility to handle metadata fields that have to be calculated
|
||
at build time.</p>
|
||
</section>
|
||
<section id="motivation">
|
||
<h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2>
|
||
<p>There are a number of issues with the way that metadata is currently
|
||
stored in source distributions:</p>
|
||
<ul class="simple">
|
||
<li>The details of how to store metadata, while standardised, are not
|
||
easy to find.</li>
|
||
<li>The specification requires an old metadata version, and has not been
|
||
updated in line with changes to the core metadata spec.</li>
|
||
<li>There is no way in the spec to distinguish between “this field has been
|
||
omitted because its value will not be known until build time” and “this
|
||
field does not have a value”.</li>
|
||
<li>The core metadata specification allows most fields to be optional,
|
||
meaning that the previous issue affects nearly every metadata field.</li>
|
||
</ul>
|
||
<p>This PEP proposes an update to the metadata specification to allow
|
||
recording of fields which are expected to be “filled in later”, and
|
||
updates the source distribution specification to clarify that backends
|
||
should record sdist metadata using that version of the spec (or later).</p>
|
||
</section>
|
||
<section id="rationale">
|
||
<h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2>
|
||
<p>This PEP allows projects to define source distribution metadata values
|
||
as being “dynamic”. In this context, saying that a field is “dynamic”
|
||
means that the value has not been fixed at the time that the source
|
||
distribution was generated. Dynamic values will be supplied by the build
|
||
backend at the time when the wheel is generated, and could depend on
|
||
details of the build environment.</p>
|
||
<p><a class="pep reference internal" href="../pep-0621/" title="PEP 621 – Storing project metadata in pyproject.toml">PEP 621</a> has a similar concept, of “dynamic” values that will be
|
||
“filled in later”, and so we choose to use the same term here by
|
||
analogy.</p>
|
||
</section>
|
||
<section id="specification">
|
||
<h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2>
|
||
<p>This PEP defines the relationship between metadata values specified in a
|
||
source distribution, and the corresponding values in wheels built from
|
||
it. It requires build backends to clearly mark any fields which will
|
||
<em>not</em> simply be copied unchanged from the sdist to the wheel.</p>
|
||
<p>In addition, this PEP makes the <a class="reference external" href="https://packaging.python.org/specifications/">PyPA Specifications</a> document the
|
||
canonical location for the specification of the source distribution
|
||
format (collecting the information in <a class="pep reference internal" href="../pep-0517/" title="PEP 517 – A build-system independent format for source trees">PEP 517</a> and in this PEP).</p>
|
||
<p>A new field, <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code>, will be added to the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core Metadata Specification</a>.
|
||
This field will be multiple use, and will be allowed to contain the name
|
||
of another core metadata field.</p>
|
||
<p>When found in the metadata of a source distribution, the following
|
||
rules apply:</p>
|
||
<ol class="arabic simple">
|
||
<li>If a field is <em>not</em> marked as <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code>, then the value of the field
|
||
in any wheel built from the sdist MUST match the value in the sdist.
|
||
If the field is not in the sdist, and not marked as <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code>, then
|
||
it MUST NOT be present in the wheel.</li>
|
||
<li>If a field is marked as <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code>, it may contain any valid value in
|
||
a wheel built from the sdist (including not being present at all).</li>
|
||
<li>Backends MUST NOT mark a field as <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code> if they can determine that
|
||
it was generated from data that will not change at build time.</li>
|
||
</ol>
|
||
<p>Backends MAY record the value they calculated for a field they mark as
|
||
<code class="docutils literal notranslate"><span class="pre">Dynamic</span></code> in a source distribution. Consumers, however, MUST NOT treat
|
||
this value as canonical, but MAY use it as an hint about what the final
|
||
value in a wheel could be.</p>
|
||
<p>In any context other than a source distribution, if a field is marked as
|
||
<code class="docutils literal notranslate"><span class="pre">Dynamic</span></code>, that indicates that the value was generated at wheel build
|
||
time and may not match the value in the sdist (or in other builds of the
|
||
project). Backends are not required to record this information, though,
|
||
and consumers MUST NOT assume that the lack of a <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code> marking has
|
||
any significance, except in a source distribution.</p>
|
||
<p>The fields <code class="docutils literal notranslate"><span class="pre">Name</span></code> and <code class="docutils literal notranslate"><span class="pre">Version</span></code> MUST NOT be marked as <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code>.</p>
|
||
<p>As it adds a new metadata field, this PEP updates the core metadata
|
||
format to version 2.2.</p>
|
||
<p>Source distributions SHOULD use the latest version of the core metadata
|
||
specification that was available when they were created.</p>
|
||
<p>Build backends are strongly encouraged to only mark fields as
|
||
<code class="docutils literal notranslate"><span class="pre">Dynamic</span></code> when absolutely necessary, and to encourage projects to
|
||
avoid backend features that require the use of <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code>. Projects
|
||
should prefer to use environment markers on static values to adapt to
|
||
details of the install location.</p>
|
||
</section>
|
||
<section id="backwards-compatibility">
|
||
<h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2>
|
||
<p>As this proposal increments the core metadata version, it is compatible
|
||
with existing source distributions, which will use an older metadata
|
||
version. Tools can determine whether a source distribution conforms to
|
||
this PEP by checking the metadata version.</p>
|
||
</section>
|
||
<section id="security-implications">
|
||
<h2><a class="toc-backref" href="#security-implications" role="doc-backlink">Security Implications</a></h2>
|
||
<p>As this specification is purely for the storage of data that is intended
|
||
to be publicly available, there are no security implications.</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>This is a data storage format for project metadata, and so will not
|
||
typically be visible to end users. There is therefore no need to teach
|
||
users how to use the format. Developers wanting to reference the
|
||
metadata will be able to find the details in the <a class="reference external" href="https://packaging.python.org/specifications/">PyPA Specifications</a>.</p>
|
||
</section>
|
||
<section id="rejected-ideas">
|
||
<h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2>
|
||
<ol class="arabic">
|
||
<li>Rather than marking fields as <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code>, fields should be assumed
|
||
to be dynamic unless explicitly marked as <code class="docutils literal notranslate"><span class="pre">Static</span></code>.<p>This is logically equivalent to the current proposal, but it implies
|
||
that fields being dynamic is the norm. Packaging tools can be much
|
||
more efficient in the presence of metadata that is known to be static,
|
||
so the PEP chooses to make dynamic fields the exception, and require
|
||
backends to “opt in” to making a field dynamic.</p>
|
||
<p>In addition, if dynamic is the default, then in future, as more
|
||
and more metadata becomes static, metadata files will include an
|
||
increasing number of <code class="docutils literal notranslate"><span class="pre">Static</span></code> declarations.</p>
|
||
</li>
|
||
<li>Rather than having a <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code> field, add a special value that
|
||
indicates that a field is “not yet defined”.<p>Again, this is logically equivalent to the current proposal. It makes
|
||
“being dynamic” an explicit choice, but requires a special value. As
|
||
some fields can contain arbitrary text, choosing a such a value is
|
||
somewhat awkward (although likely not a problem in practice). There
|
||
does not seem to be enough benefit to this approach to make it worth
|
||
using instead of the proposed mechanism.</p>
|
||
</li>
|
||
<li>Special handling of <code class="docutils literal notranslate"><span class="pre">Requires-Python</span></code>.<p>Early drafts of the PEP needed special discussion of <code class="docutils literal notranslate"><span class="pre">Requires-Python</span></code>,
|
||
because the lack of environment markers for this field meant that it might
|
||
be difficult to require it to be static. The final form of the PEP no longer
|
||
needs this, as the idea of a whitelist of fields allowed to be dynamic was
|
||
dropped.</p>
|
||
</li>
|
||
<li>Restrict the use of <code class="docutils literal notranslate"><span class="pre">Dynamic</span></code> to a minimal “white list” of
|
||
permitted fields.<p>This approach was likely to prove extremely difficult for setuptools
|
||
to implement in a backward compatible way, due to the dynamic nature
|
||
of the setuptools interface. Instead, the proposal now allows most
|
||
fields to be dynamic, but encourages backends to avoid dynamic values
|
||
unless essential.</p>
|
||
</li>
|
||
</ol>
|
||
</section>
|
||
<section id="open-issues">
|
||
<h2><a class="toc-backref" href="#open-issues" role="doc-backlink">Open Issues</a></h2>
|
||
<p>None</p>
|
||
</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-0643.rst">https://github.com/python/peps/blob/main/peps/pep-0643.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0643.rst">2023-09-09 17:39:29 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="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a></li>
|
||
<li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</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="#rejected-ideas">Rejected Ideas</a></li>
|
||
<li><a class="reference internal" href="#open-issues">Open Issues</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-0643.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> |