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