1514 lines
112 KiB
HTML
1514 lines
112 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 426 – Metadata for Python Software Packages 2.0 | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0426/">
|
||
<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 426 – Metadata for Python Software Packages 2.0 | peps.python.org'>
|
||
<meta property="og:description" content="This PEP describes a mechanism for publishing and exchanging metadata related to Python distributions. It includes specifics of the field names, and their semantics and usage.">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0426/">
|
||
<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 describes a mechanism for publishing and exchanging metadata related to Python distributions. It includes specifics of the field names, and their semantics and usage.">
|
||
<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 426</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 426 – Metadata for Python Software Packages 2.0</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Alyssa Coghlan <ncoghlan at gmail.com>,
|
||
Daniel Holth <dholth at gmail.com>,
|
||
Donald Stufft <donald at stufft.io></dd>
|
||
<dt class="field-even">BDFL-Delegate<span class="colon">:</span></dt>
|
||
<dd class="field-even">Donald Stufft <donald at stufft.io></dd>
|
||
<dt class="field-odd">Discussions-To<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="https://mail.python.org/archives/list/distutils-sig@python.org/">Distutils-SIG list</a></dd>
|
||
<dt class="field-even">Status<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Removed from consideration by sponsor or authors">Withdrawn</abbr></dd>
|
||
<dt class="field-odd">Type<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Non-normative PEP containing background, guidelines or other information relevant to the Python ecosystem">Informational</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">Requires<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="../pep-0440/">440</a>, <a class="reference external" href="../pep-0508/">508</a>, <a class="reference external" href="../pep-0518/">518</a></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">30-Aug-2012</dd>
|
||
<dt class="field-odd">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-odd">14-Nov-2012, 05-Feb-2013, 07-Feb-2013, 09-Feb-2013,
|
||
27-May-2013, 20-Jun-2013, 23-Jun-2013, 14-Jul-2013,
|
||
21-Dec-2013</dd>
|
||
<dt class="field-even">Replaces<span class="colon">:</span></dt>
|
||
<dd class="field-even"><a class="reference external" href="../pep-0345/">345</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="#note-on-pep-history">Note on PEP History</a></li>
|
||
<li><a class="reference internal" href="#purpose">Purpose</a></li>
|
||
<li><a class="reference internal" href="#development-distribution-and-deployment-of-python-software">Development, Distribution and Deployment of Python Software</a><ul>
|
||
<li><a class="reference internal" href="#supporting-definitions">Supporting definitions</a></li>
|
||
<li><a class="reference internal" href="#integration-and-deployment-of-distributions">Integration and deployment of distributions</a></li>
|
||
<li><a class="reference internal" href="#development-and-publication-of-distributions">Development and publication of distributions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#metadata-format">Metadata format</a><ul>
|
||
<li><a class="reference internal" href="#metadata-files">Metadata files</a></li>
|
||
<li><a class="reference internal" href="#metadata-validation">Metadata validation</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#core-metadata">Core metadata</a><ul>
|
||
<li><a class="reference internal" href="#metadata-version">Metadata version</a></li>
|
||
<li><a class="reference internal" href="#generator">Generator</a></li>
|
||
<li><a class="reference internal" href="#name">Name</a></li>
|
||
<li><a class="reference internal" href="#version">Version</a></li>
|
||
<li><a class="reference internal" href="#summary">Summary</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#source-code-metadata">Source code metadata</a><ul>
|
||
<li><a class="reference internal" href="#source-labels">Source labels</a></li>
|
||
<li><a class="reference internal" href="#source-url">Source URL</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#semantic-dependencies">Semantic dependencies</a><ul>
|
||
<li><a class="reference internal" href="#mapping-dependencies-to-development-and-distribution-activities">Mapping dependencies to development and distribution activities</a></li>
|
||
<li><a class="reference internal" href="#extras">Extras</a></li>
|
||
<li><a class="reference internal" href="#dependencies">Dependencies</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#metadata-extensions">Metadata Extensions</a><ul>
|
||
<li><a class="reference internal" href="#extension-versioning">Extension versioning</a></li>
|
||
<li><a class="reference internal" href="#required-extension-handling">Required extension handling</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#extras-optional-dependencies">Extras (optional dependencies)</a></li>
|
||
<li><a class="reference internal" href="#updating-the-metadata-specification">Updating the metadata specification</a></li>
|
||
<li><a class="reference internal" href="#appendix-a-conversion-notes-for-legacy-metadata">Appendix A: Conversion notes for legacy metadata</a></li>
|
||
<li><a class="reference internal" href="#appendix-b-mapping-dependency-declarations-to-an-rpm-spec-file">Appendix B: Mapping dependency declarations to an RPM SPEC file</a></li>
|
||
<li><a class="reference internal" href="#appendix-c-summary-of-differences-from-pep-345">Appendix C: Summary of differences from PEP 345</a><ul>
|
||
<li><a class="reference internal" href="#metadata-version-semantics">Metadata-Version semantics</a></li>
|
||
<li><a class="reference internal" href="#switching-to-a-json-compatible-format">Switching to a JSON compatible format</a></li>
|
||
<li><a class="reference internal" href="#changing-the-version-scheme">Changing the version scheme</a></li>
|
||
<li><a class="reference internal" href="#id1">Source labels</a></li>
|
||
<li><a class="reference internal" href="#support-for-optional-dependencies-for-distributions">Support for optional dependencies for distributions</a></li>
|
||
<li><a class="reference internal" href="#support-for-different-kinds-of-semantic-dependencies">Support for different kinds of semantic dependencies</a></li>
|
||
<li><a class="reference internal" href="#support-for-metadata-extensions">Support for metadata extensions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#appendix-d-deferred-features">Appendix D: Deferred features</a><ul>
|
||
<li><a class="reference internal" href="#standard-extensions">Standard extensions</a></li>
|
||
<li><a class="reference internal" href="#improved-handling-of-project-obsolescence-renames-and-mergers">Improved handling of project obsolescence, renames and mergers</a></li>
|
||
<li><a class="reference internal" href="#mime-type-registration">MIME type registration</a></li>
|
||
<li><a class="reference internal" href="#string-methods-in-environment-markers">String methods in environment markers</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#appendix-e-rejected-features">Appendix E: Rejected features</a><ul>
|
||
<li><a class="reference internal" href="#separate-lists-for-conditional-and-unconditional-dependencies">Separate lists for conditional and unconditional dependencies</a></li>
|
||
<li><a class="reference internal" href="#separate-lists-for-semantic-dependencies">Separate lists for semantic dependencies</a></li>
|
||
<li><a class="reference internal" href="#introducing-friction-for-overly-precise-dependency-declarations">Introducing friction for overly precise dependency declarations</a></li>
|
||
<li><a class="reference internal" href="#disallowing-underscores-in-distribution-names">Disallowing underscores in distribution names</a></li>
|
||
<li><a class="reference internal" href="#allowing-the-use-of-unicode-in-distribution-names">Allowing the use of Unicode in distribution names</a></li>
|
||
<li><a class="reference internal" href="#depending-on-source-labels">Depending on source labels</a></li>
|
||
<li><a class="reference internal" href="#alternative-dependencies">Alternative dependencies</a></li>
|
||
<li><a class="reference internal" href="#compatible-release-comparisons-in-environment-markers">Compatible release comparisons in environment markers</a></li>
|
||
<li><a class="reference internal" href="#conditional-provides">Conditional provides</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#references">References</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<div class="pep-banner sticky-banner deprecated withdrawn admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>This PEP has been withdrawn.</p>
|
||
<p class="close-button">×</p>
|
||
<p>The ground-up metadata redesign proposed in this PEP has been withdrawn in
|
||
favour of the more modest proposal in <a class="pep reference internal" href="../pep-0566/" title="PEP 566 – Metadata for Python Software Packages 2.1">PEP 566</a>, which retains the basic
|
||
Key:Value format of previous metadata versions, but also defines a standardised
|
||
mechanism for translating that format to nested JSON-compatible data structures.</p>
|
||
<p>Some of the ideas in this PEP (or the related <a class="pep reference internal" href="../pep-0459/" title="PEP 459 – Standard Metadata Extensions for Python Software Packages">PEP 459</a>) may still be considered
|
||
as part of later proposals, but they will be handled in a more incremental
|
||
fashion, rather than as a single large proposed change with no feasible
|
||
migration plan.</p>
|
||
<p></p>
|
||
</div>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>This PEP describes a mechanism for publishing and exchanging metadata
|
||
related to Python distributions. It includes specifics of the field names,
|
||
and their semantics and usage.</p>
|
||
<p>This document specifies the never released version 2.0 of the metadata format.</p>
|
||
<p>Version 1.0 is specified in <a class="pep reference internal" href="../pep-0241/" title="PEP 241 – Metadata for Python Software Packages">PEP 241</a>.
|
||
Version 1.1 is specified in <a class="pep reference internal" href="../pep-0314/" title="PEP 314 – Metadata for Python Software Packages 1.1">PEP 314</a>.
|
||
Version 1.2 is specified in <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a>.</p>
|
||
<p>Version 2.0 of the metadata format proposed migrating from directly defining a
|
||
custom key-value file format to instead defining a JSON-compatible in-memory
|
||
representation that may be used to define metadata representation in other
|
||
contexts (such as API and archive format definitions).</p>
|
||
<p>This version also defines a formal extension mechanism, allowing new
|
||
fields to be added for particular purposes without requiring updates to
|
||
the core metadata format.</p>
|
||
</section>
|
||
<section id="note-on-pep-history">
|
||
<h2><a class="toc-backref" href="#note-on-pep-history" role="doc-backlink">Note on PEP History</a></h2>
|
||
<p>This PEP was initially deferred for an extended period, from December 2013
|
||
through to March 2017, as distutils-sig worked through a number of other
|
||
changes. These changes included:</p>
|
||
<ul class="simple">
|
||
<li>defining a binary compatibility tagging format in <a class="pep reference internal" href="../pep-0425/" title="PEP 425 – Compatibility Tags for Built Distributions">PEP 425</a></li>
|
||
<li>defining a binary archive format (<code class="docutils literal notranslate"><span class="pre">wheel</span></code>) in <a class="pep reference internal" href="../pep-0427/" title="PEP 427 – The Wheel Binary Package Format 1.0">PEP 427</a></li>
|
||
<li>explicitly defining versioning and version comparison in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a></li>
|
||
<li>explicitly defining the PyPI “simple” API in <a class="pep reference internal" href="../pep-0503/" title="PEP 503 – Simple Repository API">PEP 503</a></li>
|
||
<li>explicitly defining dependency specifiers and the extras system in <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a></li>
|
||
<li>declaring static build system dependencies (<code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>) in <a class="pep reference internal" href="../pep-0518/" title="PEP 518 – Specifying Minimum Build System Requirements for Python Projects">PEP 518</a></li>
|
||
<li>migrating PyPI hosting to Rackspace, and placing it behind the Fastly CDN</li>
|
||
<li>shipping <code class="docutils literal notranslate"><span class="pre">pip</span></code> with CPython by default in <a class="pep reference internal" href="../pep-0453/" title="PEP 453 – Explicit bootstrapping of pip in Python installations">PEP 453</a>, and backporting that
|
||
addition to Python 2.7 in <a class="pep reference internal" href="../pep-0477/" title="PEP 477 – Backport ensurepip (PEP 453) to Python 2.7">PEP 477</a></li>
|
||
<li>establishing <a class="reference external" href="https://packaging.python.org/">packaging.python.org</a> as the common access point for Python
|
||
packaging ecosystem documentation</li>
|
||
<li>migrating to using the <a class="reference external" href="https://packaging.python.org/specifications/">specifications</a> section of packaging.python.org
|
||
as the central location for tracking packaging related PEPs</li>
|
||
</ul>
|
||
<p>The time spent pursuing these changes provided additional perspective on which
|
||
metadata format changes were genuinely desirable, and which could be omitted
|
||
from the revised specification as merely being “change for change’s sake”.</p>
|
||
<p>It also allowed a number of features that aren’t critical to the core activity
|
||
of publishing and distributing software to be moved out to <a class="pep reference internal" href="../pep-0459/" title="PEP 459 – Standard Metadata Extensions for Python Software Packages">PEP 459</a>, a separate
|
||
proposal for a number of standard metadata extensions that provide additional
|
||
optional information about a release.</p>
|
||
<p>As of September 2017, it was deferred again, on the grounds that
|
||
it doesn’t actually help solve any particularly pressing problems:</p>
|
||
<ul class="simple">
|
||
<li>JSON representation would be better handled through defining a
|
||
transformation of the existing metadata 1.2 fields</li>
|
||
<li>clarification of the additional fields defined in the past few
|
||
years and related changes to the spec management process would
|
||
be better covered in a <a class="reference external" href="https://mail.python.org/pipermail/distutils-sig/2017-September/031465.html">minor spec version update</a></li>
|
||
</ul>
|
||
<p>Finally, the PEP was withdrawn in February 2018 in favour of <a class="pep reference internal" href="../pep-0566/" title="PEP 566 – Metadata for Python Software Packages 2.1">PEP 566</a> (which
|
||
pursues that more incremental strategy).</p>
|
||
</section>
|
||
<section id="purpose">
|
||
<h2><a class="toc-backref" href="#purpose" role="doc-backlink">Purpose</a></h2>
|
||
<p>The purpose of this PEP is to define a common metadata interchange format
|
||
for communication between software publication tools and software integration
|
||
tools in the Python ecosystem. One key aim is to support full dependency
|
||
analysis in that ecosystem without requiring the execution of arbitrary
|
||
Python code by those doing the analysis. Another aim is to encourage good
|
||
software distribution practices by default, while continuing to support the
|
||
current practices of almost all existing users of the Python Package Index
|
||
(both publishers and integrators). Finally, the aim is to support an upgrade
|
||
path from the currently in use metadata formats that is transparent to end
|
||
users.</p>
|
||
<p>The design draws on the Python community’s nearly 20 years of experience with
|
||
distutils based software distribution, and incorporates ideas and concepts
|
||
from other distribution systems, including Python’s setuptools, pip and
|
||
other projects, Ruby’s gems, Perl’s CPAN, Node.js’s npm, PHP’s composer
|
||
and Linux packaging systems such as RPM and APT.</p>
|
||
<p>While the specifics of this format are aimed at the Python ecosystem, some
|
||
of the ideas may also be useful in the future evolution of other dependency
|
||
management ecosystems.</p>
|
||
</section>
|
||
<section id="development-distribution-and-deployment-of-python-software">
|
||
<h2><a class="toc-backref" href="#development-distribution-and-deployment-of-python-software" role="doc-backlink">Development, Distribution and Deployment of Python Software</a></h2>
|
||
<p>The metadata design in this PEP is based on a particular conceptual model
|
||
of the software development and distribution process. This model consists of
|
||
the following phases:</p>
|
||
<ul class="simple">
|
||
<li>Software development: this phase involves working with a source checkout
|
||
for a particular application to add features and fix bugs. It is
|
||
expected that developers in this phase will need to be able to build the
|
||
software, run the software’s automated test suite, run project specific
|
||
utility scripts and publish the software.</li>
|
||
<li>Software publication: this phase involves taking the developed software
|
||
and making it available for use by software integrators. This includes
|
||
creating the descriptive metadata defined in this PEP, as well as making
|
||
the software available (typically by uploading it to an index server).</li>
|
||
<li>Software integration: this phase involves taking published software
|
||
components and combining them into a coherent, integrated system. This
|
||
may be done directly using Python specific cross-platform tools, or it may
|
||
be handled through conversion to development language neutral platform
|
||
specific packaging systems.</li>
|
||
<li>Software deployment: this phase involves taking integrated software
|
||
components and deploying them on to the target system where the software
|
||
will actually execute.</li>
|
||
</ul>
|
||
<p>The publication and integration phases are collectively referred to as
|
||
the distribution phase, and the individual software components distributed
|
||
in that phase are formally referred to as “distribution packages”, but are more
|
||
colloquially known as just “packages” (relying on context to disambiguate them
|
||
from the “module with submodules” kind of Python package).</p>
|
||
<p>The exact details of these phases will vary greatly for particular use cases.
|
||
Deploying a web application to a public Platform-as-a-Service provider,
|
||
publishing a new release of a web framework or scientific library,
|
||
creating an integrated Linux distribution, or upgrading a custom application
|
||
running in a secure enclave are all situations this metadata design should
|
||
be able to handle.</p>
|
||
<p>The complexity of the metadata described in this PEP thus arises directly
|
||
from the actual complexities associated with software development,
|
||
distribution and deployment in a wide range of scenarios.</p>
|
||
<section id="supporting-definitions">
|
||
<h3><a class="toc-backref" href="#supporting-definitions" role="doc-backlink">Supporting definitions</a></h3>
|
||
<p>The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,
|
||
“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this
|
||
document are to be interpreted as described in <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2119.html"><strong>RFC 2119</strong></a>.</p>
|
||
<p>“Projects” are software components that are made available for integration.
|
||
Projects include Python libraries, frameworks, scripts, plugins,
|
||
applications, collections of data or other resources, and various
|
||
combinations thereof. Public Python projects are typically registered on
|
||
the <a class="reference external" href="https://pypi.org/">Python Package Index</a>.</p>
|
||
<p>“Releases” are uniquely identified snapshots of a project.</p>
|
||
<p>“Distribution packages” are the packaged files which are used to publish
|
||
and distribute a release.</p>
|
||
<p>Depending on context, “package” may refer to either a distribution, or
|
||
to an importable Python module that has a <code class="docutils literal notranslate"><span class="pre">__path__</span></code> attribute and hence
|
||
may also have importable submodules.</p>
|
||
<p>“Source archive” and “VCS checkout” both refer to the raw source code for
|
||
a release, prior to creation of an sdist or binary archive.</p>
|
||
<p>An “sdist” is a publication format providing the distribution metadata and
|
||
any source files that are essential to creating a binary archive for
|
||
the distribution. Creating a binary archive from an sdist requires that
|
||
the appropriate build tools be available on the system.</p>
|
||
<p>“Binary archives” only require that prebuilt files be moved to the correct
|
||
location on the target system. As Python is a dynamically bound
|
||
cross-platform language, many so-called “binary” archives will contain only
|
||
pure Python source code.</p>
|
||
<p>“Contributors” are individuals and organizations that work together to
|
||
develop a software component.</p>
|
||
<p>“Publishers” are individuals and organizations that make software components
|
||
available for integration (typically by uploading distributions to an
|
||
index server)</p>
|
||
<p>“Integrators” are individuals and organizations that incorporate published
|
||
distributions as components of an application or larger system.</p>
|
||
<p>“Build tools” are automated tools intended to run on development systems,
|
||
producing source and binary distribution archives. Build tools may also be
|
||
invoked by integration tools in order to build software distributed as
|
||
sdists rather than prebuilt binary archives.</p>
|
||
<p>“Index servers” are active distribution registries which publish version and
|
||
dependency metadata and place constraints on the permitted metadata.</p>
|
||
<p>“Public index servers” are index servers which allow distribution uploads
|
||
from untrusted third parties. The <a class="reference external" href="https://pypi.org/">Python Package Index</a> is a public index
|
||
server.</p>
|
||
<p>“Publication tools” are automated tools intended to run on development
|
||
systems and upload source and binary distribution archives to index servers.</p>
|
||
<p>“Integration tools” are automated tools that consume the metadata and
|
||
distribution archives published by an index server or other designated
|
||
source, and make use of them in some fashion, such as installing them or
|
||
converting them to a platform specific packaging format.</p>
|
||
<p>“Installation tools” are integration tools specifically intended to run on
|
||
deployment targets, consuming source and binary distribution archives from
|
||
an index server or other designated location and deploying them to the target
|
||
system.</p>
|
||
<p>“Automated tools” is a collective term covering build tools, index servers,
|
||
publication tools, integration tools and any other software that produces
|
||
or consumes distribution version and dependency metadata.</p>
|
||
<p>“Legacy metadata” refers to earlier versions of this metadata specification,
|
||
along with the supporting metadata file formats defined by the
|
||
<code class="docutils literal notranslate"><span class="pre">setuptools</span></code> project.</p>
|
||
<p>“Distro” is used as the preferred term for Linux distributions, to help
|
||
avoid confusion with the Python-specific use of the term “distribution
|
||
package”.</p>
|
||
<p>“Qualified name” is a dotted Python identifier. For imported modules and
|
||
packages, the qualified name is available as the <code class="docutils literal notranslate"><span class="pre">__name__</span></code> attribute,
|
||
while for functions and classes it is available as the <code class="docutils literal notranslate"><span class="pre">__qualname__</span></code>
|
||
attribute.</p>
|
||
<p>A “fully qualified name” uniquely locates an object in the Python module
|
||
namespace. For imported modules and packages, it is the same as the
|
||
qualified name. For other Python objects, the fully qualified name consists
|
||
of the qualified name of the containing module or package, a colon (<code class="docutils literal notranslate"><span class="pre">:</span></code>)
|
||
and the qualified name of the object relative to the containing module or
|
||
package.</p>
|
||
<p>A “prefixed name” starts with a qualified name, but is not necessarily a
|
||
qualified name - it may contain additional dot separated segments which are
|
||
not valid identifiers.</p>
|
||
</section>
|
||
<section id="integration-and-deployment-of-distributions">
|
||
<h3><a class="toc-backref" href="#integration-and-deployment-of-distributions" role="doc-backlink">Integration and deployment of distributions</a></h3>
|
||
<p>The primary purpose of the distribution metadata is to support integration
|
||
and deployment of distributions as part of larger applications and systems.</p>
|
||
<p>Integration and deployment can in turn be broken down into further substeps.</p>
|
||
<ul class="simple">
|
||
<li>Build: the build step is the process of turning a VCS checkout, source
|
||
archive or sdist into a binary archive. Dependencies must be available
|
||
in order to build and create a binary archive of the distribution
|
||
(including any documentation that is installed on target systems).</li>
|
||
<li>Installation: the installation step involves getting the distribution
|
||
and all of its runtime dependencies onto the target system. In this
|
||
step, the distribution may already be on the system (when upgrading or
|
||
reinstalling) or else it may be a completely new installation.</li>
|
||
<li>Runtime: this is normal usage of a distribution after it has been
|
||
installed on the target system.</li>
|
||
</ul>
|
||
<p>These three steps may all occur directly on the target system. Alternatively
|
||
the build step may be separated out by using binary archives provided by the
|
||
publisher of the distribution, or by creating the binary archives on a
|
||
separate system prior to deployment. The advantage of the latter approach
|
||
is that it minimizes the dependencies that need to be installed on
|
||
deployment targets (as the build dependencies will be needed only on the
|
||
build systems).</p>
|
||
<p>The published metadata for distribution packages SHOULD allow integrators, with
|
||
the aid of build and integration tools, to:</p>
|
||
<ul class="simple">
|
||
<li>obtain the original source code that was used to create a distribution</li>
|
||
<li>identify and retrieve the dependencies (if any) required to use a
|
||
distribution</li>
|
||
<li>identify and retrieve the dependencies (if any) required to build a
|
||
distribution from source</li>
|
||
<li>identify and retrieve the dependencies (if any) required to run a
|
||
distribution’s test suite</li>
|
||
</ul>
|
||
</section>
|
||
<section id="development-and-publication-of-distributions">
|
||
<h3><a class="toc-backref" href="#development-and-publication-of-distributions" role="doc-backlink">Development and publication of distributions</a></h3>
|
||
<p>The secondary purpose of the distribution metadata is to support effective
|
||
collaboration amongst software contributors and publishers during the
|
||
development phase.</p>
|
||
<p>The published metadata for distributions SHOULD allow contributors
|
||
and publishers, with the aid of build and publication tools, to:</p>
|
||
<ul class="simple">
|
||
<li>perform all the same activities needed to effectively integrate and
|
||
deploy the distribution</li>
|
||
<li>identify and retrieve the additional dependencies needed to develop and
|
||
publish the distribution</li>
|
||
<li>specify the dependencies (if any) required to use the distribution</li>
|
||
<li>specify the dependencies (if any) required to build the distribution
|
||
from source</li>
|
||
<li>specify the dependencies (if any) required to run the distribution’s
|
||
test suite</li>
|
||
<li>specify the additional dependencies (if any) required to develop and
|
||
publish the distribution</li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
<section id="metadata-format">
|
||
<h2><a class="toc-backref" href="#metadata-format" role="doc-backlink">Metadata format</a></h2>
|
||
<p>The format defined in this PEP is an in-memory representation of Python
|
||
distribution metadata as a string-keyed dictionary. Permitted values for
|
||
individual entries are strings, lists of strings, and additional
|
||
nested string-keyed dictionaries.</p>
|
||
<p>Except where otherwise noted, dictionary keys in distribution metadata MUST
|
||
be valid Python identifiers in order to support attribute based metadata
|
||
access APIs.</p>
|
||
<p>The individual field descriptions show examples of the key name and value
|
||
as they would be serialised as part of a JSON mapping.</p>
|
||
<p>Unless otherwise indicated, the fields identified as core metadata are required.
|
||
Automated tools MUST NOT accept distributions with missing core metadata as
|
||
valid Python distributions.</p>
|
||
<p>All other fields are optional. Automated tools MUST operate correctly
|
||
if a distribution does not provide them, except for those operations
|
||
which specifically require the omitted fields.</p>
|
||
<p>Automated tools MUST NOT insert dummy data for missing fields. If a valid
|
||
value is not provided for a required field then the metadata and the
|
||
associated distribution MUST be rejected as invalid. If a valid value
|
||
is not provided for an optional field, that field MUST be omitted entirely.
|
||
Automated tools MAY automatically derive valid values from other
|
||
information sources (such as a version control system).</p>
|
||
<p>Automated tools, especially public index servers, MAY impose additional
|
||
length restrictions on metadata beyond those enumerated in this PEP. Such
|
||
limits SHOULD be imposed where necessary to protect the integrity of a
|
||
service, based on the available resources and the service provider’s
|
||
judgment of reasonable metadata capacity requirements.</p>
|
||
<section id="metadata-files">
|
||
<h3><a class="toc-backref" href="#metadata-files" role="doc-backlink">Metadata files</a></h3>
|
||
<p>The information defined in this PEP is serialised to <code class="docutils literal notranslate"><span class="pre">pysdist.json</span></code>
|
||
files for some use cases. These are files containing UTF-8 encoded JSON
|
||
metadata.</p>
|
||
<p>Each metadata file consists of a single serialised mapping, with fields as
|
||
described in this PEP. When serialising metadata, automated tools SHOULD
|
||
lexically sort any keys and list elements in order to simplify reviews
|
||
of any changes.</p>
|
||
<p>There are expected to be three standard locations for these metadata files:</p>
|
||
<ul class="simple">
|
||
<li>as a <code class="docutils literal notranslate"><span class="pre">{distribution}-{version}.dist-info/pysdist.json</span></code> file in an
|
||
<code class="docutils literal notranslate"><span class="pre">sdist</span></code> source distribution archive</li>
|
||
<li>as a <code class="docutils literal notranslate"><span class="pre">{distribution}-{version}.dist-info/pysdist.json</span></code> file in a <code class="docutils literal notranslate"><span class="pre">wheel</span></code>
|
||
binary distribution archive</li>
|
||
<li>as a <code class="docutils literal notranslate"><span class="pre">{distribution}-{version}.dist-info/pysdist.json</span></code> file in a local
|
||
Python installation database</li>
|
||
</ul>
|
||
<p>This file is expected to be identical in all three locations - it is
|
||
generated when creating a source archive or binary archive from a source
|
||
tree, and then preserved unchanged on installation, or when building a
|
||
binary archive from a source archive.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>These locations are to be confirmed, since they depend on the definition
|
||
of sdist 2.0 and the revised installation database standard. There will
|
||
also be a wheel 1.1 format update after this PEP is approved that
|
||
mandates provision of 2.0+ metadata.</p>
|
||
</div>
|
||
<p>Note that these metadata files MAY be processed even if the version of the
|
||
containing location is too low to indicate that they are valid. Specifically,
|
||
unversioned <code class="docutils literal notranslate"><span class="pre">sdist</span></code> archives, unversioned installation database directories
|
||
and version 1.0 of the <code class="docutils literal notranslate"><span class="pre">wheel</span></code> specification may still provide
|
||
<code class="docutils literal notranslate"><span class="pre">pysdist.json</span></code> files.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Until this specification is formally marked as Active, it is recommended
|
||
that tools following the draft format use an alternative filename like
|
||
<code class="docutils literal notranslate"><span class="pre">metadata.json</span></code> or <code class="docutils literal notranslate"><span class="pre">pep426-20131213.json</span></code> to avoid colliding with
|
||
the eventually standardised files.</p>
|
||
</div>
|
||
<p>Other tools involved in Python distribution MAY also use this format.</p>
|
||
<p>Note that these metadata files are generated by build tools based on other
|
||
input formats (such as <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> and <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>) rather than being
|
||
used directly as a data input format. Generating the metadata as part of the
|
||
publication process also helps to deal with version specific fields (including
|
||
the source URL and the version field itself).</p>
|
||
<p>For backwards compatibility with older installation tools, metadata 2.0
|
||
files MAY be distributed alongside legacy metadata.</p>
|
||
<p>Index servers MAY allow distributions to be uploaded and installation tools
|
||
MAY allow distributions to be installed with only legacy metadata.</p>
|
||
<p>Automated tools MAY attempt to automatically translate legacy metadata to
|
||
the format described in this PEP. Advice for doing so effectively is given
|
||
in Appendix A.</p>
|
||
</section>
|
||
<section id="metadata-validation">
|
||
<h3><a class="toc-backref" href="#metadata-validation" role="doc-backlink">Metadata validation</a></h3>
|
||
<p>A <a class="reference external" href="https://pypi.org/project/jsonschema/">jsonschema</a> description of
|
||
the distribution metadata is <a class="reference external" href="https://hg.python.org/peps/file/default/pep-0426/pydist-schema.json">available</a>.</p>
|
||
<p>This schema does NOT currently handle validation of some of the more complex
|
||
string fields (instead treating them as opaque strings).</p>
|
||
<p>Except where otherwise noted, all URL fields in the metadata MUST comply
|
||
with <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3986.html"><strong>RFC 3986</strong></a>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The current version of the schema file covers the previous draft of the
|
||
PEP, and has not yet been updated for the split into the essential
|
||
dependency resolution metadata and multiple standard extensions, and nor
|
||
has it been updated for the various other differences between the current
|
||
draft and the earlier drafts.</p>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="core-metadata">
|
||
<h2><a class="toc-backref" href="#core-metadata" role="doc-backlink">Core metadata</a></h2>
|
||
<p>This section specifies the core metadata fields that are required for every
|
||
Python distribution.</p>
|
||
<p>Publication tools MUST ensure at least these fields are present when
|
||
publishing a distribution.</p>
|
||
<p>Index servers MUST ensure at least these fields are present in the metadata
|
||
when distributions are uploaded.</p>
|
||
<p>Installation tools MUST refuse to install distributions with one or more
|
||
of these fields missing by default, but MAY allow users to force such an
|
||
installation to occur.</p>
|
||
<section id="metadata-version">
|
||
<h3><a class="toc-backref" href="#metadata-version" role="doc-backlink">Metadata version</a></h3>
|
||
<p>Version of the file format; <code class="docutils literal notranslate"><span class="pre">"2.0"</span></code> is the only legal value.</p>
|
||
<p>Automated tools consuming metadata SHOULD warn if <code class="docutils literal notranslate"><span class="pre">metadata_version</span></code> is
|
||
greater than the highest version they support, and MUST fail if
|
||
<code class="docutils literal notranslate"><span class="pre">metadata_version</span></code> has a greater major version than the highest
|
||
version they support (as described in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a>, the major version is the
|
||
value before the first dot).</p>
|
||
<p>For broader compatibility, build tools MAY choose to produce
|
||
distribution metadata using the lowest metadata version that includes
|
||
all of the needed fields.</p>
|
||
<p>Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"metadata_version"</span><span class="p">:</span> <span class="s2">"2.0"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="generator">
|
||
<h3><a class="toc-backref" href="#generator" role="doc-backlink">Generator</a></h3>
|
||
<p>Name (and optional version) of the program that generated the file,
|
||
if any. A manually produced file would omit this field.</p>
|
||
<p>Examples:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"generator"</span><span class="p">:</span> <span class="s2">"flit"</span>
|
||
<span class="s2">"generator"</span><span class="p">:</span> <span class="s2">"setuptools (34.3.1)"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="name">
|
||
<h3><a class="toc-backref" href="#name" role="doc-backlink">Name</a></h3>
|
||
<p>The name of the distribution, as defined in <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>.</p>
|
||
<p>As distribution names are used as part of URLs, filenames, command line
|
||
parameters and must also interoperate with other packaging systems, the
|
||
permitted characters are constrained to:</p>
|
||
<ul class="simple">
|
||
<li>ASCII letters (<code class="docutils literal notranslate"><span class="pre">[a-zA-Z]</span></code>)</li>
|
||
<li>ASCII digits (<code class="docutils literal notranslate"><span class="pre">[0-9]</span></code>)</li>
|
||
<li>underscores (<code class="docutils literal notranslate"><span class="pre">_</span></code>)</li>
|
||
<li>hyphens (<code class="docutils literal notranslate"><span class="pre">-</span></code>)</li>
|
||
<li>periods (<code class="docutils literal notranslate"><span class="pre">.</span></code>)</li>
|
||
</ul>
|
||
<p>Distribution names MUST start and end with an ASCII letter or digit.</p>
|
||
<p>Automated tools MUST reject non-compliant names. A regular expression to
|
||
enforce these constraints (when run with <code class="docutils literal notranslate"><span class="pre">re.IGNORECASE</span></code>) is:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$
|
||
</pre></div>
|
||
</div>
|
||
<p>All comparisons of distribution names MUST be case insensitive, and MUST
|
||
consider hyphens and underscores to be equivalent.</p>
|
||
<p>Index servers MAY consider “confusable” characters (as defined by the
|
||
Unicode Consortium in <a class="reference external" href="https://www.unicode.org/reports/tr39/tr39-1.html#Confusable_Detection">TR39: Unicode Security Mechanisms</a>) to be
|
||
equivalent.</p>
|
||
<p>Index servers that permit arbitrary distribution name registrations from
|
||
untrusted sources SHOULD consider confusable characters to be equivalent
|
||
when registering new distributions (and hence reject them as duplicates).</p>
|
||
<p>Integration tools MUST NOT silently accept a confusable alternate
|
||
spelling as matching a requested distribution name.</p>
|
||
<p>At time of writing, the characters in the ASCII subset designated as
|
||
confusables by the Unicode Consortium are:</p>
|
||
<ul class="simple">
|
||
<li><code class="docutils literal notranslate"><span class="pre">1</span></code> (DIGIT ONE), <code class="docutils literal notranslate"><span class="pre">l</span></code> (LATIN SMALL LETTER L), and <code class="docutils literal notranslate"><span class="pre">I</span></code> (LATIN CAPITAL
|
||
LETTER I)</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">0</span></code> (DIGIT ZERO), and <code class="docutils literal notranslate"><span class="pre">O</span></code> (LATIN CAPITAL LETTER O)</li>
|
||
</ul>
|
||
<p>Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"name"</span><span class="p">:</span> <span class="s2">"ComfyChair"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="version">
|
||
<h3><a class="toc-backref" href="#version" role="doc-backlink">Version</a></h3>
|
||
<p>The distribution’s public or local version identifier, as defined in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a>.
|
||
Version identifiers are designed for consumption by automated tools and
|
||
support a variety of flexible version specification mechanisms (see <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a>
|
||
for details).</p>
|
||
<p>Version identifiers MUST comply with the format defined in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a>.</p>
|
||
<p>Version identifiers MUST be unique within each project.</p>
|
||
<p>Index servers MAY place restrictions on the use of local version identifiers
|
||
as described in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a>.</p>
|
||
<p>Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"version"</span><span class="p">:</span> <span class="s2">"1.0a2"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="summary">
|
||
<h3><a class="toc-backref" href="#summary" role="doc-backlink">Summary</a></h3>
|
||
<p>A short summary of what the distribution does.</p>
|
||
<p>This field SHOULD contain fewer than 512 characters and MUST contain fewer
|
||
than 2048.</p>
|
||
<p>This field SHOULD NOT contain any line breaks.</p>
|
||
<p>A more complete description SHOULD be included as a separate file in the
|
||
sdist for the distribution. Refer to the <code class="docutils literal notranslate"><span class="pre">python-details</span></code> extension in
|
||
<a class="pep reference internal" href="../pep-0459/" title="PEP 459 – Standard Metadata Extensions for Python Software Packages">PEP 459</a> for more information.</p>
|
||
<p>Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"summary"</span><span class="p">:</span> <span class="s2">"A module that is more fiendish than soft cushions."</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="source-code-metadata">
|
||
<h2><a class="toc-backref" href="#source-code-metadata" role="doc-backlink">Source code metadata</a></h2>
|
||
<p>This section specifies fields that provide identifying details for the
|
||
source code used to produce this distribution.</p>
|
||
<p>All of these fields are optional. Automated tools MUST operate correctly if
|
||
a distribution does not provide them, including failing cleanly when an
|
||
operation depending on one of these fields is requested.</p>
|
||
<section id="source-labels">
|
||
<h3><a class="toc-backref" href="#source-labels" role="doc-backlink">Source labels</a></h3>
|
||
<p>Source labels are text strings with minimal defined semantics. They are
|
||
intended to allow the original source code to be unambiguously identified,
|
||
even if an integrator has applied additional local modifications to a
|
||
particular distribution.</p>
|
||
<p>To ensure source labels can be readily incorporated as part of file names
|
||
and URLs, and to avoid formatting inconsistencies in hexadecimal hash
|
||
representations they MUST be limited to the following set of permitted
|
||
characters:</p>
|
||
<ul class="simple">
|
||
<li>Lowercase ASCII letters (<code class="docutils literal notranslate"><span class="pre">[a-z]</span></code>)</li>
|
||
<li>ASCII digits (<code class="docutils literal notranslate"><span class="pre">[0-9]</span></code>)</li>
|
||
<li>underscores (<code class="docutils literal notranslate"><span class="pre">_</span></code>)</li>
|
||
<li>hyphens (<code class="docutils literal notranslate"><span class="pre">-</span></code>)</li>
|
||
<li>periods (<code class="docutils literal notranslate"><span class="pre">.</span></code>)</li>
|
||
<li>plus signs (<code class="docutils literal notranslate"><span class="pre">+</span></code>)</li>
|
||
</ul>
|
||
<p>Source labels MUST start and end with an ASCII letter or digit.</p>
|
||
<p>A regular expression to rnforce these constraints (when run with
|
||
<code class="docutils literal notranslate"><span class="pre">re.IGNORECASE</span></code>) is:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>^([A-Z0-9]|[A-Z0-9][A-Z0-9._-+]*[A-Z0-9])$
|
||
</pre></div>
|
||
</div>
|
||
<p>A source label for a project MUST NOT match any defined version for that
|
||
project. This restriction ensures that there is no ambiguity between version
|
||
identifiers and source labels.</p>
|
||
<p>Examples:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"source_label"</span><span class="p">:</span> <span class="s2">"1.0.0-alpha.1"</span>
|
||
|
||
<span class="s2">"source_label"</span><span class="p">:</span> <span class="s2">"1.3.7+build.11.e0f985a"</span>
|
||
|
||
<span class="s2">"source_label"</span><span class="p">:</span> <span class="s2">"v1.8.1.301.ga0df26f"</span>
|
||
|
||
<span class="s2">"source_label"</span><span class="p">:</span> <span class="s2">"2013.02.17.dev123"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="source-url">
|
||
<h3><a class="toc-backref" href="#source-url" role="doc-backlink">Source URL</a></h3>
|
||
<p>A string containing a full URL where the source for this specific version of
|
||
the distribution can be downloaded.</p>
|
||
<p>Source URLs MUST be unique within each project. This means that the URL
|
||
can’t be something like <code class="docutils literal notranslate"><span class="pre">"https://github.com/pypa/pip/archive/main.zip"</span></code>,
|
||
but instead must be <code class="docutils literal notranslate"><span class="pre">"https://github.com/pypa/pip/archive/1.3.1.zip"</span></code>.</p>
|
||
<p>The source URL MUST reference either a source archive or a tag or specific
|
||
commit in an online version control system that permits creation of a
|
||
suitable VCS checkout. It is intended primarily for integrators that
|
||
wish to recreate the distribution from the original source form.</p>
|
||
<p>All source URL references SHOULD specify a secure transport mechanism
|
||
(such as <code class="docutils literal notranslate"><span class="pre">https</span></code>) AND include an expected hash value in the URL for
|
||
verification purposes. If a source URL is specified without any hash
|
||
information, with hash information that the tool doesn’t understand, or
|
||
with a selected hash algorithm that the tool considers too weak to trust,
|
||
automated tools SHOULD at least emit a warning and MAY refuse to rely on
|
||
the URL. If such a source URL also uses an insecure transport, automated
|
||
tools SHOULD NOT rely on the URL.</p>
|
||
<p>For source archive references, an expected hash value may be specified by
|
||
including a <code class="docutils literal notranslate"><span class="pre"><hash-algorithm>=<expected-hash></span></code> entry as part of the URL
|
||
fragment.</p>
|
||
<p>As of 2017, it is RECOMMENDED that <code class="docutils literal notranslate"><span class="pre">'sha256'</span></code> hashes be used for source
|
||
URLs, as this hash is not yet known to be vulnerable to generation of
|
||
malicious collisions, while also being widely available on client systems.</p>
|
||
<p>For version control references, the <code class="docutils literal notranslate"><span class="pre">VCS+protocol</span></code> scheme SHOULD be
|
||
used to identify both the version control system and the secure transport,
|
||
and a version control system with hash based commit identifiers SHOULD be
|
||
used. Automated tools MAY omit warnings about missing hashes for version
|
||
control systems that do not provide hash based commit identifiers.</p>
|
||
<p>To handle version control systems that do not support including commit or
|
||
tag references directly in the URL, that information may be appended to the
|
||
end of the URL using the <code class="docutils literal notranslate"><span class="pre">@<commit-hash></span></code> or the <code class="docutils literal notranslate"><span class="pre">@<tag>#<commit-hash></span></code>
|
||
notation.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This isn’t <em>quite</em> the same as the existing VCS reference notation
|
||
supported by pip. Firstly, the distribution name is a separate field rather
|
||
than embedded as part of the URL. Secondly, the commit hash is included
|
||
even when retrieving based on a tag, in order to meet the requirement
|
||
above that <em>every</em> link should include a hash to make things harder to
|
||
forge (creating a malicious repo with a particular tag is easy, creating
|
||
one with a specific <em>hash</em>, less so).</p>
|
||
</div>
|
||
<p>Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"source_url"</span><span class="p">:</span> <span class="s2">"https://github.com/pypa/pip/archive/1.3.1.zip#sha256=2dc6b5a470a1bde68946f263f1af1515a2574a150a30d6ce02c6ff742fcc0db8</span>
|
||
<span class="s2">"source_url"</span><span class="p">:</span> <span class="s2">"git+https://github.com/pypa/pip.git@1.3.1#7921be1537eac1e97bc40179a57f0349c2aee67d"</span>
|
||
<span class="s2">"source_url"</span><span class="p">:</span> <span class="s2">"git+https://github.com/pypa/pip.git@7921be1537eac1e97bc40179a57f0349c2aee67d"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="semantic-dependencies">
|
||
<h2><a class="toc-backref" href="#semantic-dependencies" role="doc-backlink">Semantic dependencies</a></h2>
|
||
<p>Dependency metadata allows published projects to make use of functionality
|
||
provided by other published projects, without needing to bundle copies of
|
||
particular releases of those projects.</p>
|
||
<p>Semantic dependencies allow publishers to indicate not only which other
|
||
projects are needed, but also <em>why</em> they’re needed. This additional
|
||
information allows integrators to install just the dependencies they need
|
||
for specific activities, making it easier to minimise installation
|
||
footprints in constrained environments (regardless of the reasons for
|
||
those constraints).</p>
|
||
<p>By default, dependency declarations are assumed to be for
|
||
“runtime dependencies”: other releases that are needed to actually use the
|
||
published release.</p>
|
||
<p>There are also four different kinds of optional dependency that releases may
|
||
declare:</p>
|
||
<ul class="simple">
|
||
<li><code class="docutils literal notranslate"><span class="pre">test</span></code> dependencies: other releases that are needed to run the
|
||
automated test suite for this release, but are not needed just to
|
||
use it (e.g. <code class="docutils literal notranslate"><span class="pre">nose2</span></code> or <code class="docutils literal notranslate"><span class="pre">pytest</span></code>)</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">build</span></code> dependencies: other releases that are needed to build this
|
||
a deployable binary version of this release from source
|
||
(e.g. <code class="docutils literal notranslate"><span class="pre">flit</span></code> or <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>)</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">doc</span></code> dependencies: other releases that are needed to build the
|
||
documentation for this distribution (e.g. the <code class="docutils literal notranslate"><span class="pre">sphinx</span></code> build tool)</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">dev</span></code> dependencies: other releases that are needed when working on this
|
||
distribution, but do not fit into exactly one of the other optional
|
||
dependency categories (e.g. <code class="docutils literal notranslate"><span class="pre">pylint</span></code>, <code class="docutils literal notranslate"><span class="pre">flake8</span></code>). <code class="docutils literal notranslate"><span class="pre">dev</span></code> dependencies
|
||
are also effectively considered as combined <code class="docutils literal notranslate"><span class="pre">test</span></code>, <code class="docutils literal notranslate"><span class="pre">build</span></code>, and <code class="docutils literal notranslate"><span class="pre">doc</span></code>
|
||
dependencies, without needing to be listed three times</li>
|
||
</ul>
|
||
<p>These optional categories are known as
|
||
<a class="reference internal" href="#extras-optional-dependencies">Extras</a>. In addition to the four
|
||
standard categories, projects may also declare their own custom categories
|
||
in the <a class="reference internal" href="#extras-optional-dependencies">Extras</a> field.</p>
|
||
<p>There are also two standard extra categories that imply dependencies on
|
||
other extras:</p>
|
||
<ul class="simple">
|
||
<li><code class="docutils literal notranslate"><span class="pre">alldev</span></code>: implies the <code class="docutils literal notranslate"><span class="pre">test</span></code>, <code class="docutils literal notranslate"><span class="pre">build</span></code>, <code class="docutils literal notranslate"><span class="pre">doc</span></code>, <code class="docutils literal notranslate"><span class="pre">dev</span></code> extras</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">all</span></code>: if not otherwise defined, implies all declared extras</li>
|
||
</ul>
|
||
<p>Dependency management is heavily dependent on the version identification
|
||
and specification scheme defined in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> and the dependency specification,
|
||
extra, and environment marker schemes defined in <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>.</p>
|
||
<p>All of these fields are optional. Automated tools MUST operate correctly if
|
||
a distribution does not provide them, by assuming that a missing field
|
||
indicates “Not applicable for this distribution”.</p>
|
||
<section id="mapping-dependencies-to-development-and-distribution-activities">
|
||
<h3><a class="toc-backref" href="#mapping-dependencies-to-development-and-distribution-activities" role="doc-backlink">Mapping dependencies to development and distribution activities</a></h3>
|
||
<p>The different categories of dependency are based on the various distribution
|
||
and development activities identified above, and govern which dependencies
|
||
should be installed for the specified activities:</p>
|
||
<ul class="simple">
|
||
<li>Required runtime dependencies:<ul>
|
||
<li>unconditional dependencies</li>
|
||
</ul>
|
||
</li>
|
||
<li>Required build dependencies:<ul>
|
||
<li>the <code class="docutils literal notranslate"><span class="pre">build</span></code> extra</li>
|
||
<li>the <code class="docutils literal notranslate"><span class="pre">dev</span></code> extra</li>
|
||
<li>If running the distribution’s test suite as part of the build process,
|
||
also install the unconditional dependencies and <code class="docutils literal notranslate"><span class="pre">test</span></code> extra</li>
|
||
</ul>
|
||
</li>
|
||
<li>Required development and publication dependencies:<ul>
|
||
<li>unconditional dependencies</li>
|
||
<li>the <code class="docutils literal notranslate"><span class="pre">test</span></code> extra</li>
|
||
<li>the <code class="docutils literal notranslate"><span class="pre">build</span></code> extra</li>
|
||
<li>the <code class="docutils literal notranslate"><span class="pre">doc</span></code> extra</li>
|
||
<li>the <code class="docutils literal notranslate"><span class="pre">dev</span></code> extra</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The notation described in <a class="reference internal" href="#extras-optional-dependencies">Extras (optional dependencies)</a> SHOULD be used
|
||
to determine exactly what gets installed for various operations.</p>
|
||
<p>Installation tools SHOULD report an error if dependencies cannot be
|
||
satisfied, MUST at least emit a warning, and MAY allow the user to force
|
||
the installation to proceed regardless.</p>
|
||
<p>See Appendix B for an overview of mapping these dependencies to an RPM
|
||
spec file.</p>
|
||
</section>
|
||
<section id="extras">
|
||
<h3><a class="toc-backref" href="#extras" role="doc-backlink">Extras</a></h3>
|
||
<p>A list of optional sets of dependencies that may be used to define
|
||
conditional dependencies in dependency fields. See
|
||
<a class="reference internal" href="#extras-optional-dependencies">Extras (optional dependencies)</a> for details.</p>
|
||
<p>The names of extras MUST abide by the same restrictions as those for
|
||
distribution names.</p>
|
||
<p>The following extra names are available by default and MUST NOT be
|
||
declared explicitly in this field:</p>
|
||
<ul class="simple">
|
||
<li><code class="docutils literal notranslate"><span class="pre">all</span></code></li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">alldev</span></code></li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">build</span></code></li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">dev</span></code></li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">doc</span></code></li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">test</span></code></li>
|
||
</ul>
|
||
<p>Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"extras"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"warmup"</span><span class="p">,</span> <span class="s2">"tea"</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="dependencies">
|
||
<h3><a class="toc-backref" href="#dependencies" role="doc-backlink">Dependencies</a></h3>
|
||
<p>A list of release requirements needed to actually run this release.</p>
|
||
<p>Public index servers MAY prohibit strict version matching clauses or direct
|
||
references in this field.</p>
|
||
<p>Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"dependencies"</span><span class="p">:</span>
|
||
<span class="p">{</span>
|
||
<span class="s2">"requires"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"SciPy"</span><span class="p">,</span> <span class="s2">"PasteDeploy"</span><span class="p">,</span> <span class="s2">"zope.interface > 3.5.0"</span><span class="p">]</span>
|
||
<span class="p">},</span>
|
||
<span class="p">{</span>
|
||
<span class="s2">"requires"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"pywin32 > 1.0"</span><span class="p">],</span>
|
||
<span class="s2">"environment"</span><span class="p">:</span> <span class="s2">"sys_platform == 'win32'"</span>
|
||
<span class="p">},</span>
|
||
<span class="p">{</span>
|
||
<span class="s2">"requires"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"SoftCushions"</span><span class="p">],</span>
|
||
<span class="s2">"extra"</span><span class="p">:</span> <span class="s2">"warmup"</span>
|
||
<span class="p">}</span>
|
||
<span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>While many dependencies will be needed to use a project release at all, others
|
||
are needed only on particular platforms or only when particular optional
|
||
features of the release are needed.</p>
|
||
<p>To handle this, release dependency specifiers are mappings with the following
|
||
subfields:</p>
|
||
<ul class="simple">
|
||
<li><code class="docutils literal notranslate"><span class="pre">requires</span></code>: a list of requirements needed to satisfy the dependency</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">extra</span></code>: the name of a set of optional dependencies that are requested
|
||
and installed together. See <a class="reference internal" href="#extras-optional-dependencies">Extras (optional dependencies)</a> for details</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">environment</span></code>: an environment marker defining the environment that
|
||
needs these dependencies. The syntax and capabilities of environment
|
||
markers are defined in <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a></li>
|
||
</ul>
|
||
<p>Individual entries in the <code class="docutils literal notranslate"><span class="pre">requires</span></code> lists are strings using the dependency
|
||
declaration format defined in <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>, with the exception that environment
|
||
markers MUST NOT be included in the individual dependency declarations, and
|
||
are instead supplied in the separate <code class="docutils literal notranslate"><span class="pre">environment</span></code> field.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">requires</span></code> is the only required subfield. When it is the only subfield, the
|
||
dependencies are said to be <em>unconditional</em>. If <code class="docutils literal notranslate"><span class="pre">extra</span></code> or <code class="docutils literal notranslate"><span class="pre">environment</span></code>
|
||
is specified, then the dependencies are <em>conditional</em>.</p>
|
||
<p>All three fields may be supplied, indicating that the dependencies are
|
||
needed only when the named extra is requested in a particular environment.</p>
|
||
<p>Automated tools MUST combine related dependency specifiers (those with
|
||
common values for <code class="docutils literal notranslate"><span class="pre">extra</span></code> and <code class="docutils literal notranslate"><span class="pre">environment</span></code>) into a single specifier
|
||
listing multiple requirements when serialising metadata.</p>
|
||
<p>Despite this required normalisation, the same extra name or environment
|
||
marker MAY appear in multiple conditional dependencies. This may happen,
|
||
for example, if an extra itself only needs some of its dependencies in
|
||
specific environments. It is only the combination of extras and environment
|
||
markers that is required to be unique in a list of dependency specifiers.</p>
|
||
<p>Aside from the six standard extra categories, any extras referenced from a
|
||
dependency specifier MUST be named in the <a class="reference internal" href="#extras-optional-dependencies">Extras</a> field for this distribution.
|
||
This helps avoid typographical errors and also makes it straightforward to
|
||
identify the available extras without scanning the full set of dependencies.</p>
|
||
<p>To reuse an extra definition as part of another extra, project releases MAY
|
||
declare dependencies on themselves. To avoid infinite recursion in these cases,
|
||
automated tools MUST special case dependencies from a project back onto itself.</p>
|
||
</section>
|
||
</section>
|
||
<section id="metadata-extensions">
|
||
<h2><a class="toc-backref" href="#metadata-extensions" role="doc-backlink">Metadata Extensions</a></h2>
|
||
<p>Extensions to the metadata MAY be present in a mapping under the
|
||
<code class="docutils literal notranslate"><span class="pre">extensions</span></code> key. The keys MUST be valid prefixed names, while
|
||
the values MUST themselves be nested mappings.</p>
|
||
<p>Two key names are reserved and MUST NOT be used by extensions, except as
|
||
described below:</p>
|
||
<ul class="simple">
|
||
<li><code class="docutils literal notranslate"><span class="pre">extension_version</span></code></li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">installer_must_handle</span></code></li>
|
||
</ul>
|
||
<p>The following example shows the <code class="docutils literal notranslate"><span class="pre">python.details</span></code> and <code class="docutils literal notranslate"><span class="pre">python.commands</span></code>
|
||
standard extensions from <a class="pep reference internal" href="../pep-0459/" title="PEP 459 – Standard Metadata Extensions for Python Software Packages">PEP 459</a>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"extensions"</span> <span class="p">:</span> <span class="p">{</span>
|
||
<span class="s2">"python.details"</span><span class="p">:</span> <span class="p">{</span>
|
||
<span class="s2">"license"</span><span class="p">:</span> <span class="s2">"GPL version 3, excluding DRM provisions"</span><span class="p">,</span>
|
||
<span class="s2">"keywords"</span><span class="p">:</span> <span class="p">[</span>
|
||
<span class="s2">"comfy"</span><span class="p">,</span> <span class="s2">"chair"</span><span class="p">,</span> <span class="s2">"cushions"</span><span class="p">,</span> <span class="s2">"too silly"</span><span class="p">,</span> <span class="s2">"monty python"</span>
|
||
<span class="p">],</span>
|
||
<span class="s2">"classifiers"</span><span class="p">:</span> <span class="p">[</span>
|
||
<span class="s2">"Development Status :: 4 - Beta"</span><span class="p">,</span>
|
||
<span class="s2">"Environment :: Console (Text Based)"</span><span class="p">,</span>
|
||
<span class="s2">"License :: OSI Approved :: GNU General Public License v3 (GPLv3)"</span>
|
||
<span class="p">],</span>
|
||
<span class="s2">"document_names"</span><span class="p">:</span> <span class="p">{</span>
|
||
<span class="s2">"description"</span><span class="p">:</span> <span class="s2">"README.rst"</span><span class="p">,</span>
|
||
<span class="s2">"license"</span><span class="p">:</span> <span class="s2">"LICENSE.rst"</span><span class="p">,</span>
|
||
<span class="s2">"changelog"</span><span class="p">:</span> <span class="s2">"NEWS"</span>
|
||
<span class="p">}</span>
|
||
<span class="p">},</span>
|
||
<span class="s2">"python.commands"</span><span class="p">:</span> <span class="p">{</span>
|
||
<span class="s2">"wrap_console"</span><span class="p">:</span> <span class="p">[{</span><span class="s2">"chair"</span><span class="p">:</span> <span class="s2">"chair:run_cli"</span><span class="p">}],</span>
|
||
<span class="s2">"wrap_gui"</span><span class="p">:</span> <span class="p">[{</span><span class="s2">"chair-gui"</span><span class="p">:</span> <span class="s2">"chair:run_gui"</span><span class="p">}],</span>
|
||
<span class="s2">"prebuilt"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"reduniforms"</span><span class="p">]</span>
|
||
<span class="p">},</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Extension names are defined by distributions that will then make use of
|
||
the additional published metadata in some way.</p>
|
||
<p>To reduce the chance of name conflicts, extension names SHOULD use a
|
||
prefix that corresponds to a module name in the distribution that defines
|
||
the meaning of the extension. This practice will also make it easier to
|
||
find authoritative documentation for metadata extensions.</p>
|
||
<p>Metadata extensions allow development tools to record information in the
|
||
metadata that may be useful during later phases of distribution, but is
|
||
not essential for dependency resolution or building the software.</p>
|
||
<section id="extension-versioning">
|
||
<h3><a class="toc-backref" href="#extension-versioning" role="doc-backlink">Extension versioning</a></h3>
|
||
<p>Extensions MUST be versioned, using the <code class="docutils literal notranslate"><span class="pre">extension_version</span></code> key.
|
||
However, if this key is omitted, then the implied version is <code class="docutils literal notranslate"><span class="pre">1.0</span></code>.</p>
|
||
<p>Automated tools consuming extension metadata SHOULD warn if
|
||
<code class="docutils literal notranslate"><span class="pre">extension_version</span></code> is greater than the highest version they support,
|
||
and MUST fail if <code class="docutils literal notranslate"><span class="pre">extension_version</span></code> has a greater major version than
|
||
the highest version they support (as described in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a>, the major
|
||
version is the value before the first dot).</p>
|
||
<p>For broader compatibility, build tools MAY choose to produce
|
||
extension metadata using the lowest metadata version that includes
|
||
all of the needed fields.</p>
|
||
</section>
|
||
<section id="required-extension-handling">
|
||
<h3><a class="toc-backref" href="#required-extension-handling" role="doc-backlink">Required extension handling</a></h3>
|
||
<p>A project may consider correct handling of some extensions to be essential
|
||
to correct installation of the software. This is indicated by setting the
|
||
<code class="docutils literal notranslate"><span class="pre">installer_must_handle</span></code> field to <code class="docutils literal notranslate"><span class="pre">true</span></code>. Setting it to <code class="docutils literal notranslate"><span class="pre">false</span></code> or
|
||
omitting it altogether indicates that processing the extension when
|
||
installing the distribution is not considered mandatory by the developers.</p>
|
||
<p>Installation tools MUST fail if <code class="docutils literal notranslate"><span class="pre">installer_must_handle</span></code> is set to <code class="docutils literal notranslate"><span class="pre">true</span></code>
|
||
for an extension and the tool does not have any ability to process that
|
||
particular extension (whether directly or through a tool-specific plugin
|
||
system).</p>
|
||
<p>If an installation tool encounters a required extension it doesn’t
|
||
understand when attempting to install from a wheel archive, it MAY fall
|
||
back on attempting to install from source rather than failing entirely.</p>
|
||
</section>
|
||
</section>
|
||
<section id="extras-optional-dependencies">
|
||
<h2><a class="toc-backref" href="#extras-optional-dependencies" role="doc-backlink">Extras (optional dependencies)</a></h2>
|
||
<p>As defined in <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>, extras are additional dependencies that enable an
|
||
optional aspect of a project release, often corresponding to a <code class="docutils literal notranslate"><span class="pre">try:</span> <span class="pre">import</span>
|
||
<span class="pre">optional_dependency</span> <span class="pre">...</span></code> block in the code. They are also used to indicate
|
||
semantic dependencies for activities other than normal runtime using (such as
|
||
testing, building, or working on the component).</p>
|
||
<p>To support the use of the release with or without the optional dependencies,
|
||
they are listed separately from the release’s core runtime dependencies
|
||
and must be requested explicitly, either in the dependency specifications of
|
||
another project, or else when issuing a command to an installation tool.</p>
|
||
<p>Example of a distribution with optional dependencies:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"name"</span><span class="p">:</span> <span class="s2">"ComfyChair"</span><span class="p">,</span>
|
||
<span class="s2">"extras"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"warmup"</span><span class="p">]</span>
|
||
<span class="s2">"dependencies"</span><span class="p">:</span> <span class="p">[</span>
|
||
<span class="p">{</span>
|
||
<span class="s2">"requires"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"SoftCushions"</span><span class="p">],</span>
|
||
<span class="s2">"extra"</span><span class="p">:</span> <span class="s2">"warmup"</span>
|
||
<span class="p">},</span>
|
||
<span class="p">{</span>
|
||
<span class="s2">"requires"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"cython"</span><span class="p">],</span>
|
||
<span class="s2">"extra"</span><span class="p">:</span> <span class="s2">"build"</span>
|
||
<span class="p">}</span>
|
||
<span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Other distributions require the additional dependencies by placing the
|
||
relevant extra names inside square brackets after the distribution name when
|
||
specifying the dependency. Multiple extras from a dependency can be requested
|
||
by placing to</p>
|
||
<p>If the standard <code class="docutils literal notranslate"><span class="pre">all</span></code> extra has no explicitly declared entries, then
|
||
integration tools SHOULD implicitly define it as a dependency on all of the
|
||
extras explicitly declared by the project.</p>
|
||
<p>If the standard <code class="docutils literal notranslate"><span class="pre">alldev</span></code> extra has no explicitly declared entries, then
|
||
integration tools SHOULD implicitly define it as a dependency on the standard
|
||
<code class="docutils literal notranslate"><span class="pre">test</span></code>, <code class="docutils literal notranslate"><span class="pre">build</span></code>, <code class="docutils literal notranslate"><span class="pre">doc</span></code>, and <code class="docutils literal notranslate"><span class="pre">dev</span></code> extras.</p>
|
||
<p>The full set of dependency requirements is then based on the unconditional
|
||
dependencies, along with those of any requested extras.</p>
|
||
<p>Dependency examples (showing just the <code class="docutils literal notranslate"><span class="pre">requires</span></code> subfield):</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>"requires": ["ComfyChair"]
|
||
-> requires ``ComfyChair`` only
|
||
|
||
"requires": ["ComfyChair[warmup]"]
|
||
-> requires ``ComfyChair`` and ``SoftCushions``
|
||
|
||
"requires": ["ComfyChair[all]"]
|
||
-> requires ``ComfyChair`` and ``SoftCushions``, but will also
|
||
pick up any new extras defined in later versions
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="updating-the-metadata-specification">
|
||
<h2><a class="toc-backref" href="#updating-the-metadata-specification" role="doc-backlink">Updating the metadata specification</a></h2>
|
||
<p>The metadata specification may be updated with clarifications without
|
||
requiring a new PEP or a change to the metadata version.</p>
|
||
<p>Changing the meaning of existing fields or adding new features (other than
|
||
through the extension mechanism) requires a new metadata version defined in
|
||
a new PEP.</p>
|
||
</section>
|
||
<section id="appendix-a-conversion-notes-for-legacy-metadata">
|
||
<h2><a class="toc-backref" href="#appendix-a-conversion-notes-for-legacy-metadata" role="doc-backlink">Appendix A: Conversion notes for legacy metadata</a></h2>
|
||
<p>The reference implementations for converting from legacy metadata to
|
||
metadata 2.0 are:</p>
|
||
<ul class="simple">
|
||
<li>the <a class="reference external" href="https://bitbucket.org/dholth/wheel/overview">wheel project</a>, which
|
||
adds the <code class="docutils literal notranslate"><span class="pre">bdist_wheel</span></code> command to <code class="docutils literal notranslate"><span class="pre">setuptools</span></code></li>
|
||
<li>the <a class="reference external" href="https://github.com/dstufft/warehouse">Warehouse project</a>, which
|
||
will eventually be migrated to the Python Packaging Authority as the next
|
||
generation Python Package Index implementation</li>
|
||
<li>the <a class="reference external" href="https://bitbucket.org/pypa/distlib/">distlib project</a> which is
|
||
derived from the core packaging infrastructure created for the
|
||
<code class="docutils literal notranslate"><span class="pre">distutils2</span></code> project</li>
|
||
</ul>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>These tools have yet to be updated for the switch to standard extensions
|
||
for several fields.</p>
|
||
</div>
|
||
<p>While it is expected that there may be some edge cases where manual
|
||
intervention is needed for clean conversion, the specification has been
|
||
designed to allow fully automated conversion of almost all projects on
|
||
PyPI.</p>
|
||
<p>Metadata conversion (especially on the part of the index server) is a
|
||
necessary step to allow installation and analysis tools to start
|
||
benefiting from the new metadata format, without having to wait for
|
||
developers to upgrade to newer build systems.</p>
|
||
</section>
|
||
<section id="appendix-b-mapping-dependency-declarations-to-an-rpm-spec-file">
|
||
<h2><a class="toc-backref" href="#appendix-b-mapping-dependency-declarations-to-an-rpm-spec-file" role="doc-backlink">Appendix B: Mapping dependency declarations to an RPM SPEC file</a></h2>
|
||
<p>As an example of mapping this PEP to Linux distro packages, assume an
|
||
example project without any extras defined is split into 2 RPMs
|
||
in a SPEC file: <code class="docutils literal notranslate"><span class="pre">example</span></code> and <code class="docutils literal notranslate"><span class="pre">example-devel</span></code>.</p>
|
||
<p>The unconditional dependencies would be mapped to the Requires dependencies
|
||
for the “example” RPM (a mapping from environment markers relevant to Linux
|
||
to SPEC file conditions would also allow those to be handled correctly).</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">build</span></code> and <code class="docutils literal notranslate"><span class="pre">dev</span></code> extra dependencies would be mapped to the
|
||
BuildRequires dependencies for the “example” RPM. Depending on how the
|
||
<code class="docutils literal notranslate"><span class="pre">%check</span></code> section in the RPM was defined, the <code class="docutils literal notranslate"><span class="pre">test</span></code> extra may also be
|
||
mapped to the BuildRequires declaration for the RPM.</p>
|
||
<p>All defined dependencies relevant to Linux in the <code class="docutils literal notranslate"><span class="pre">dev</span></code>, <code class="docutils literal notranslate"><span class="pre">test</span></code>, <code class="docutils literal notranslate"><span class="pre">build</span></code>,
|
||
and <code class="docutils literal notranslate"><span class="pre">doc</span></code> extras would become Requires dependencies for the “example-devel”
|
||
RPM.</p>
|
||
<p>A documentation toolchain dependency like Sphinx would either go in the
|
||
<code class="docutils literal notranslate"><span class="pre">build</span></code> extra (for example, if man pages were included in the
|
||
built distribution) or in the <code class="docutils literal notranslate"><span class="pre">doc</span></code> extra (for example, if the
|
||
documentation is published solely through Read the Docs or the
|
||
project website). This would be enough to allow an automated converter
|
||
to map it to an appropriate dependency in the spec file.</p>
|
||
<p>If the project did define any extras, those could be mapped to additional
|
||
virtual RPMs with appropriate BuildRequires and Requires entries based on
|
||
the details of the dependency specifications. Alternatively, they could
|
||
be mapped to other system package manager features (such as weak dependencies).</p>
|
||
<p>The metadata extension format should also provide a way for distribution
|
||
specific hints to be included in the upstream project metadata without needing
|
||
to manually duplicate any of the upstream metadata in a distribution specific
|
||
format.</p>
|
||
</section>
|
||
<section id="appendix-c-summary-of-differences-from-pep-345">
|
||
<h2><a class="toc-backref" href="#appendix-c-summary-of-differences-from-pep-345" role="doc-backlink">Appendix C: Summary of differences from PEP 345</a></h2>
|
||
<ul class="simple">
|
||
<li>Metadata-Version is now 2.0, with semantics specified for handling
|
||
version changes</li>
|
||
<li>The increasingly complex ad hoc “Key: Value” format has been replaced by
|
||
a more structured JSON compatible format that is easily represented as
|
||
Python dictionaries, strings, lists.</li>
|
||
<li>Most fields are now optional and filling in dummy data for omitted fields
|
||
is explicitly disallowed</li>
|
||
<li>Explicit permission for in-place clarifications without releasing a new
|
||
version of the specification</li>
|
||
<li>The PEP now attempts to provide more of an explanation of <em>why</em> the fields
|
||
exist and how they are intended to be used, rather than being a simple
|
||
description of the permitted contents</li>
|
||
<li>Changed the version scheme to be based on <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> rather than <a class="pep reference internal" href="../pep-0386/" title="PEP 386 – Changing the version comparison module in Distutils">PEP 386</a></li>
|
||
<li>Added the source label mechanism as described in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a></li>
|
||
<li>Formally defined dependency declarations, extras, and environment markers
|
||
in <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a></li>
|
||
<li>Support for different kinds of dependencies through additional reserved
|
||
extra names</li>
|
||
<li>Updated obsolescence mechanism</li>
|
||
<li>A well-defined metadata extension mechanism, and migration of any fields
|
||
not needed for dependency resolution to standard extensions</li>
|
||
<li>With all due respect to Charles Schulz and Peanuts, many of the examples
|
||
have been updated to be more thematically appropriate for Python ;)</li>
|
||
</ul>
|
||
<p>The rationale for major changes is given in the following sections.</p>
|
||
<section id="metadata-version-semantics">
|
||
<h3><a class="toc-backref" href="#metadata-version-semantics" role="doc-backlink">Metadata-Version semantics</a></h3>
|
||
<p>The semantics of major and minor version increments are now specified,
|
||
and follow the same model as the format version semantics specified for
|
||
the wheel format in <a class="pep reference internal" href="../pep-0427/" title="PEP 427 – The Wheel Binary Package Format 1.0">PEP 427</a>: minor version increments must behave
|
||
reasonably when processed by a tool that only understand earlier metadata
|
||
versions with the same major version, while major version increments
|
||
may include changes that are not compatible with existing tools.</p>
|
||
<p>The major version number of the specification has been incremented
|
||
accordingly, as interpreting <a class="pep reference internal" href="../pep-0426/" title="PEP 426 – Metadata for Python Software Packages 2.0">PEP 426</a> metadata obviously cannot be
|
||
interpreted in accordance with earlier metadata specifications.</p>
|
||
<p>Whenever the major version number of the specification is incremented, it
|
||
is expected that deployment will take some time, as either metadata
|
||
consuming tools must be updated before other tools can safely start
|
||
producing the new format, or else the sdist and wheel formats, along with
|
||
the installation database definition, will need to be updated to support
|
||
provision of multiple versions of the metadata in parallel.</p>
|
||
<p>Existing tools won’t abide by this guideline until they’re updated to
|
||
support the new metadata standard, so the new semantics will first take
|
||
effect for a hypothetical 2.x -> 3.0 transition. For the 1.x -> 2.x
|
||
transition, we will use the approach where tools continue to produce the
|
||
existing supplementary files (such as <code class="docutils literal notranslate"><span class="pre">entry_points.txt</span></code>) in addition
|
||
to any equivalents specified using the new features of the standard
|
||
metadata format (including the formal extension mechanism).</p>
|
||
</section>
|
||
<section id="switching-to-a-json-compatible-format">
|
||
<h3><a class="toc-backref" href="#switching-to-a-json-compatible-format" role="doc-backlink">Switching to a JSON compatible format</a></h3>
|
||
<p>The old “Key:Value” format was becoming increasingly limiting, with various
|
||
complexities like parsers needing to know which fields were permitted to
|
||
occur more than once, which fields supported the environment marker
|
||
syntax (with an optional <code class="docutils literal notranslate"><span class="pre">";"</span></code> to separate the value from the marker) and
|
||
eventually even the option to embed arbitrary JSON inside particular
|
||
subfields.</p>
|
||
<p>The old serialisation format also wasn’t amenable to easy conversion to
|
||
standard Python data structures for use in any new install hook APIs, or
|
||
in future extensions to the runtime importer APIs to allow them to provide
|
||
information for inclusion in the installation database.</p>
|
||
<p>Accordingly, we’ve taken the step of switching to a JSON-compatible metadata
|
||
format. This works better for APIs and is much easier for tools to parse and
|
||
generate correctly. Changing the name of the metadata file also makes it
|
||
easy to distribute 1.x and 2.x metadata in parallel, greatly simplifying
|
||
several aspects of the migration to the new metadata format.</p>
|
||
<p>The specific choice of <code class="docutils literal notranslate"><span class="pre">pydist.json</span></code> as the preferred file name relates
|
||
to the fact that the metadata described in these files applies to the
|
||
distribution as a whole, rather than to any particular build. Additional
|
||
metadata formats may be defined in the future to hold information that can
|
||
only be determined after building a binary distribution for a particular
|
||
target environment.</p>
|
||
</section>
|
||
<section id="changing-the-version-scheme">
|
||
<h3><a class="toc-backref" href="#changing-the-version-scheme" role="doc-backlink">Changing the version scheme</a></h3>
|
||
<p>See <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> for a detailed rationale for the various changes made to the
|
||
versioning scheme.</p>
|
||
</section>
|
||
<section id="id1">
|
||
<h3><a class="toc-backref" href="#id1" role="doc-backlink">Source labels</a></h3>
|
||
<p>The new source label support is intended to make it clearer that the
|
||
constraints on public version identifiers are there primarily to aid in
|
||
the creation of reliable automated dependency analysis tools. Projects
|
||
are free to use whatever versioning scheme they like internally, so long
|
||
as they are able to translate it to something the dependency analysis tools
|
||
will understand.</p>
|
||
<p>Source labels also make it straightforward to record specific details of a
|
||
version, like a hash or tag name that allows the release to be reconstructed
|
||
from the project version control system.</p>
|
||
</section>
|
||
<section id="support-for-optional-dependencies-for-distributions">
|
||
<h3><a class="toc-backref" href="#support-for-optional-dependencies-for-distributions" role="doc-backlink">Support for optional dependencies for distributions</a></h3>
|
||
<p>The new extras system allows distributions to declare optional
|
||
behaviour, and to use the dependency fields to indicate when
|
||
particular dependencies are needed only to support that behaviour. It is
|
||
derived from the equivalent system that is already in widespread use as
|
||
part of <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> and allows that aspect of the legacy <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>
|
||
metadata to be accurately represented in the new metadata format.</p>
|
||
<p>The additions to the extras syntax relative to setuptools are defined to
|
||
make it easier to express the various possible combinations of dependencies,
|
||
in particular those associated with build systems (with optional support
|
||
for running the test suite) and development systems.</p>
|
||
</section>
|
||
<section id="support-for-different-kinds-of-semantic-dependencies">
|
||
<h3><a class="toc-backref" href="#support-for-different-kinds-of-semantic-dependencies" role="doc-backlink">Support for different kinds of semantic dependencies</a></h3>
|
||
<p>The separation of the five different kinds of dependency through the Extras
|
||
system allows a project to optionally indicate whether a dependency is needed
|
||
specifically to develop, build, test or use the distribution.</p>
|
||
<p>The advantage of having these distinctions supported in the upstream Python
|
||
specific metadata is that even if a project doesn’t care about these
|
||
distinction themselves, they may be more amenable to patches from
|
||
downstream redistributors that separate the fields appropriately. Over time,
|
||
this should allow much greater control over where and when particular
|
||
dependencies end up being installed.</p>
|
||
</section>
|
||
<section id="support-for-metadata-extensions">
|
||
<h3><a class="toc-backref" href="#support-for-metadata-extensions" role="doc-backlink">Support for metadata extensions</a></h3>
|
||
<p>The new extension effectively allows sections of the metadata
|
||
namespace to be delegated to other projects, while preserving a
|
||
standard overall format metadata format for easy of processing by
|
||
distribution tools that do not support a particular extension.</p>
|
||
<p>It also works well in combination with the new <code class="docutils literal notranslate"><span class="pre">build</span></code> extra
|
||
to allow a distribution to depend on tools which <em>do</em> know how to handle
|
||
the chosen extension, and the new extras mechanism in general, allowing
|
||
support for particular extensions to be provided as optional features.</p>
|
||
<p>Possible future uses for extensions include declaration of plugins for
|
||
other projects and hints for automatic conversion to Linux system
|
||
packages.</p>
|
||
<p>The ability to declare an extension as required is included primarily to
|
||
allow the definition of the metadata hooks extension to be deferred until
|
||
some time after the initial adoption of the metadata 2.0 specification. If
|
||
a release needs a <code class="docutils literal notranslate"><span class="pre">postinstall</span></code> hook to run in order to complete
|
||
the installation successfully, then earlier versions of tools should fall
|
||
back to installing from source rather than installing from a wheel file and
|
||
then failing to run the expected postinstall hook.</p>
|
||
</section>
|
||
</section>
|
||
<section id="appendix-d-deferred-features">
|
||
<h2><a class="toc-backref" href="#appendix-d-deferred-features" role="doc-backlink">Appendix D: Deferred features</a></h2>
|
||
<p>Several potentially useful features have been deliberately deferred in
|
||
order to better prioritise our efforts in migrating to the new metadata
|
||
standard. These all reflect information that may be nice to have in the
|
||
new metadata, but which can be readily added through metadata extensions or
|
||
in metadata 2.1 without breaking any use cases already supported by metadata
|
||
2.0.</p>
|
||
<p>Once the <code class="docutils literal notranslate"><span class="pre">pypi</span></code>, <code class="docutils literal notranslate"><span class="pre">setuptools</span></code>, <code class="docutils literal notranslate"><span class="pre">pip</span></code>, <code class="docutils literal notranslate"><span class="pre">wheel</span></code> and <code class="docutils literal notranslate"><span class="pre">distlib</span></code>
|
||
projects support creation and consumption of metadata 2.0, then we may
|
||
revisit the creation of metadata 2.1 with some or all of these additional
|
||
features.</p>
|
||
<section id="standard-extensions">
|
||
<h3><a class="toc-backref" href="#standard-extensions" role="doc-backlink">Standard extensions</a></h3>
|
||
<p>Some of the information provided by the legacy metadata system has been
|
||
moved out to standard extensions defined in <a class="pep reference internal" href="../pep-0459/" title="PEP 459 – Standard Metadata Extensions for Python Software Packages">PEP 459</a>.</p>
|
||
<p>This allows publication of the core dependency metadata in a more readily
|
||
consumable format to proceed even before the full details of those extensions
|
||
have been resolved.</p>
|
||
</section>
|
||
<section id="improved-handling-of-project-obsolescence-renames-and-mergers">
|
||
<h3><a class="toc-backref" href="#improved-handling-of-project-obsolescence-renames-and-mergers" role="doc-backlink">Improved handling of project obsolescence, renames and mergers</a></h3>
|
||
<p>Earlier drafts of this PEP included new <code class="docutils literal notranslate"><span class="pre">Provides</span></code> and <code class="docutils literal notranslate"><span class="pre">Obsoleted-By</span></code>
|
||
fields for more robust automated notifications and tracking of project
|
||
obsolescence, renames and mergers.</p>
|
||
<p>This isn’t an essential feature of a dependency management system, and has
|
||
been deferred indefinitely as a possible future metadata extension.</p>
|
||
</section>
|
||
<section id="mime-type-registration">
|
||
<h3><a class="toc-backref" href="#mime-type-registration" role="doc-backlink">MIME type registration</a></h3>
|
||
<p>At some point after acceptance of the PEP, we may submit the
|
||
following MIME type registration request to IANA:</p>
|
||
<ul class="simple">
|
||
<li><code class="docutils literal notranslate"><span class="pre">application/vnd.python.pydist+json</span></code></li>
|
||
</ul>
|
||
<p>It’s even possible we may be able to just register the <code class="docutils literal notranslate"><span class="pre">vnd.python</span></code>
|
||
namespace under the banner of the PSF rather than having to register
|
||
the individual subformats.</p>
|
||
</section>
|
||
<section id="string-methods-in-environment-markers">
|
||
<h3><a class="toc-backref" href="#string-methods-in-environment-markers" role="doc-backlink">String methods in environment markers</a></h3>
|
||
<p>Supporting at least “.startswith” and “.endswith” string methods in
|
||
environment markers would allow some conditions to be written more
|
||
naturally. For example, <code class="docutils literal notranslate"><span class="pre">"sys.platform.startswith('win')"</span></code> is a
|
||
somewhat more intuitive way to mark Windows specific dependencies,
|
||
since <code class="docutils literal notranslate"><span class="pre">"'win'</span> <span class="pre">in</span> <span class="pre">sys.platform"</span></code> is incorrect thanks to <code class="docutils literal notranslate"><span class="pre">cygwin</span></code>
|
||
and the fact that 64-bit Windows still shows up as <code class="docutils literal notranslate"><span class="pre">win32</span></code> is more
|
||
than a little strange.</p>
|
||
</section>
|
||
</section>
|
||
<section id="appendix-e-rejected-features">
|
||
<h2><a class="toc-backref" href="#appendix-e-rejected-features" role="doc-backlink">Appendix E: Rejected features</a></h2>
|
||
<p>The following features have been explicitly considered and rejected as
|
||
introducing too much additional complexity for too small a gain in
|
||
expressiveness.</p>
|
||
<section id="separate-lists-for-conditional-and-unconditional-dependencies">
|
||
<h3><a class="toc-backref" href="#separate-lists-for-conditional-and-unconditional-dependencies" role="doc-backlink">Separate lists for conditional and unconditional dependencies</a></h3>
|
||
<p>Earlier versions of this PEP used separate lists for conditional and
|
||
unconditional dependencies. This turned out to be annoying to handle in
|
||
automated tools and removing it also made the PEP and metadata schema
|
||
substantially shorter, suggesting it was actually harder to explain as well.</p>
|
||
</section>
|
||
<section id="separate-lists-for-semantic-dependencies">
|
||
<h3><a class="toc-backref" href="#separate-lists-for-semantic-dependencies" role="doc-backlink">Separate lists for semantic dependencies</a></h3>
|
||
<p>Earlier versions of this PEP used separate fields rather than the extras
|
||
system for test, build, documentation, and development dependencies. This
|
||
turned out to be annoying to handle in automated tools and removing it also
|
||
made the PEP and metadata schema substantially shorter, suggesting it was
|
||
actually harder to explain as well.</p>
|
||
</section>
|
||
<section id="introducing-friction-for-overly-precise-dependency-declarations">
|
||
<h3><a class="toc-backref" href="#introducing-friction-for-overly-precise-dependency-declarations" role="doc-backlink">Introducing friction for overly precise dependency declarations</a></h3>
|
||
<p>Earlier versions of this PEP attempted to introduce friction into the
|
||
inappropriate use of overly strict dependency declarations in published
|
||
releases. Discussion on distutils-sig came to the conclusion that wasn’t
|
||
a serious enough problem to tackle directly at the interoperability
|
||
specification layer, and if it does become a problem in the future,
|
||
it would be better tackled at the point where projects are uploaded to
|
||
the public Python Package Index.</p>
|
||
</section>
|
||
<section id="disallowing-underscores-in-distribution-names">
|
||
<h3><a class="toc-backref" href="#disallowing-underscores-in-distribution-names" role="doc-backlink">Disallowing underscores in distribution names</a></h3>
|
||
<p>Debian doesn’t actually permit underscores in names, but that seems
|
||
unduly restrictive for this spec given the common practice of using
|
||
valid Python identifiers as Python distribution names. A Debian side
|
||
policy of converting underscores to hyphens seems easy enough to
|
||
implement (and the requirement to consider hyphens and underscores as
|
||
equivalent ensures that doing so won’t introduce any name conflicts).</p>
|
||
</section>
|
||
<section id="allowing-the-use-of-unicode-in-distribution-names">
|
||
<h3><a class="toc-backref" href="#allowing-the-use-of-unicode-in-distribution-names" role="doc-backlink">Allowing the use of Unicode in distribution names</a></h3>
|
||
<p>This PEP deliberately avoids following Python 3 down the path of arbitrary
|
||
Unicode identifiers, as the security implications of doing so are
|
||
substantially worse in the software distribution use case (it opens
|
||
up far more interesting attack vectors than mere code obfuscation).</p>
|
||
<p>In addition, the existing tools really only work properly if you restrict
|
||
names to ASCII and changing that would require a <em>lot</em> of work for all
|
||
the automated tools in the chain.</p>
|
||
<p>It may be reasonable to revisit this question at some point in the (distant)
|
||
future, but setting up a more reliable software distribution system is
|
||
challenging enough without adding more general Unicode identifier support
|
||
into the mix.</p>
|
||
</section>
|
||
<section id="depending-on-source-labels">
|
||
<h3><a class="toc-backref" href="#depending-on-source-labels" role="doc-backlink">Depending on source labels</a></h3>
|
||
<p>There is no mechanism to express a dependency on a source label - they
|
||
are included in the metadata for internal project reference only. Instead,
|
||
dependencies must be expressed in terms of either public versions or else
|
||
direct URL references.</p>
|
||
</section>
|
||
<section id="alternative-dependencies">
|
||
<h3><a class="toc-backref" href="#alternative-dependencies" role="doc-backlink">Alternative dependencies</a></h3>
|
||
<p>An earlier draft of this PEP considered allowing lists in place of the
|
||
usual strings in dependency specifications to indicate that there are
|
||
multiple ways to satisfy a dependency.</p>
|
||
<p>If at least one of the individual dependencies was already available, then
|
||
the entire dependency would be considered satisfied, otherwise the first
|
||
entry would be added to the dependency set.</p>
|
||
<p>Alternative dependency specification example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="s2">"Pillow"</span><span class="p">,</span> <span class="s2">"PIL"</span><span class="p">]</span>
|
||
<span class="p">[</span><span class="s2">"mysql"</span><span class="p">,</span> <span class="s2">"psycopg2 >= 4"</span><span class="p">,</span> <span class="s2">"sqlite3"</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>However, neither of the given examples is particularly compelling,
|
||
since Pillow/PIL style forks aren’t common, and the database driver use
|
||
case would arguably be better served by an SQL Alchemy defined “supported
|
||
database driver” metadata extension where a project depends on SQL Alchemy,
|
||
and then declares in the extension which database drivers are checked for
|
||
compatibility by the upstream project.</p>
|
||
</section>
|
||
<section id="compatible-release-comparisons-in-environment-markers">
|
||
<h3><a class="toc-backref" href="#compatible-release-comparisons-in-environment-markers" role="doc-backlink">Compatible release comparisons in environment markers</a></h3>
|
||
<p><a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> defines a rich syntax for version comparisons that could
|
||
potentially be useful with <code class="docutils literal notranslate"><span class="pre">python_version</span></code> and <code class="docutils literal notranslate"><span class="pre">python_full_version</span></code>
|
||
in environment markers. However, allowing the full syntax would mean
|
||
environment markers are no longer a Python subset, while allowing
|
||
only some of the comparisons would introduce yet another special case
|
||
to handle.</p>
|
||
<p>Given that environment markers are only used in cases where a higher level
|
||
“or” is implied by the metadata structure, it seems easier to require the
|
||
use of multiple comparisons against specific Python versions for the rare
|
||
cases where this would be useful.</p>
|
||
</section>
|
||
<section id="conditional-provides">
|
||
<h3><a class="toc-backref" href="#conditional-provides" role="doc-backlink">Conditional provides</a></h3>
|
||
<p>Under the revised metadata design, conditional “provides” based on runtime
|
||
features or the environment would go in a separate “may_provide” field.
|
||
However, it isn’t clear there’s any use case for doing that, so the idea
|
||
is rejected unless someone can present a compelling use case (and even then
|
||
the idea won’t be reconsidered until metadata 2.1 at the earliest).</p>
|
||
</section>
|
||
</section>
|
||
<section id="references">
|
||
<h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2>
|
||
<p>This document specifies version 2.0 of the metadata format.
|
||
Version 1.0 is specified in <a class="pep reference internal" href="../pep-0241/" title="PEP 241 – Metadata for Python Software Packages">PEP 241</a>.
|
||
Version 1.1 is specified in <a class="pep reference internal" href="../pep-0314/" title="PEP 314 – Metadata for Python Software Packages 1.1">PEP 314</a>.
|
||
Version 1.2 is specified in <a class="pep reference internal" href="../pep-0345/" title="PEP 345 – Metadata for Python Software Packages 1.2">PEP 345</a>.</p>
|
||
<p>The initial attempt at a standardised version scheme, along with the
|
||
justifications for needing such a standard can be found in <a class="pep reference internal" href="../pep-0386/" title="PEP 386 – Changing the version comparison module in Distutils">PEP 386</a>.</p>
|
||
<ul class="simple">
|
||
<li><a class="reference external" href="https://docutils.sourceforge.io/">reStructuredText markup</a></li>
|
||
</ul>
|
||
</section>
|
||
<section id="copyright">
|
||
<h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2>
|
||
<p>This document has been placed in the public domain.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0426.rst">https://github.com/python/peps/blob/main/peps/pep-0426.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0426.rst">2024-04-14 20:08:31 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="#note-on-pep-history">Note on PEP History</a></li>
|
||
<li><a class="reference internal" href="#purpose">Purpose</a></li>
|
||
<li><a class="reference internal" href="#development-distribution-and-deployment-of-python-software">Development, Distribution and Deployment of Python Software</a><ul>
|
||
<li><a class="reference internal" href="#supporting-definitions">Supporting definitions</a></li>
|
||
<li><a class="reference internal" href="#integration-and-deployment-of-distributions">Integration and deployment of distributions</a></li>
|
||
<li><a class="reference internal" href="#development-and-publication-of-distributions">Development and publication of distributions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#metadata-format">Metadata format</a><ul>
|
||
<li><a class="reference internal" href="#metadata-files">Metadata files</a></li>
|
||
<li><a class="reference internal" href="#metadata-validation">Metadata validation</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#core-metadata">Core metadata</a><ul>
|
||
<li><a class="reference internal" href="#metadata-version">Metadata version</a></li>
|
||
<li><a class="reference internal" href="#generator">Generator</a></li>
|
||
<li><a class="reference internal" href="#name">Name</a></li>
|
||
<li><a class="reference internal" href="#version">Version</a></li>
|
||
<li><a class="reference internal" href="#summary">Summary</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#source-code-metadata">Source code metadata</a><ul>
|
||
<li><a class="reference internal" href="#source-labels">Source labels</a></li>
|
||
<li><a class="reference internal" href="#source-url">Source URL</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#semantic-dependencies">Semantic dependencies</a><ul>
|
||
<li><a class="reference internal" href="#mapping-dependencies-to-development-and-distribution-activities">Mapping dependencies to development and distribution activities</a></li>
|
||
<li><a class="reference internal" href="#extras">Extras</a></li>
|
||
<li><a class="reference internal" href="#dependencies">Dependencies</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#metadata-extensions">Metadata Extensions</a><ul>
|
||
<li><a class="reference internal" href="#extension-versioning">Extension versioning</a></li>
|
||
<li><a class="reference internal" href="#required-extension-handling">Required extension handling</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#extras-optional-dependencies">Extras (optional dependencies)</a></li>
|
||
<li><a class="reference internal" href="#updating-the-metadata-specification">Updating the metadata specification</a></li>
|
||
<li><a class="reference internal" href="#appendix-a-conversion-notes-for-legacy-metadata">Appendix A: Conversion notes for legacy metadata</a></li>
|
||
<li><a class="reference internal" href="#appendix-b-mapping-dependency-declarations-to-an-rpm-spec-file">Appendix B: Mapping dependency declarations to an RPM SPEC file</a></li>
|
||
<li><a class="reference internal" href="#appendix-c-summary-of-differences-from-pep-345">Appendix C: Summary of differences from PEP 345</a><ul>
|
||
<li><a class="reference internal" href="#metadata-version-semantics">Metadata-Version semantics</a></li>
|
||
<li><a class="reference internal" href="#switching-to-a-json-compatible-format">Switching to a JSON compatible format</a></li>
|
||
<li><a class="reference internal" href="#changing-the-version-scheme">Changing the version scheme</a></li>
|
||
<li><a class="reference internal" href="#id1">Source labels</a></li>
|
||
<li><a class="reference internal" href="#support-for-optional-dependencies-for-distributions">Support for optional dependencies for distributions</a></li>
|
||
<li><a class="reference internal" href="#support-for-different-kinds-of-semantic-dependencies">Support for different kinds of semantic dependencies</a></li>
|
||
<li><a class="reference internal" href="#support-for-metadata-extensions">Support for metadata extensions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#appendix-d-deferred-features">Appendix D: Deferred features</a><ul>
|
||
<li><a class="reference internal" href="#standard-extensions">Standard extensions</a></li>
|
||
<li><a class="reference internal" href="#improved-handling-of-project-obsolescence-renames-and-mergers">Improved handling of project obsolescence, renames and mergers</a></li>
|
||
<li><a class="reference internal" href="#mime-type-registration">MIME type registration</a></li>
|
||
<li><a class="reference internal" href="#string-methods-in-environment-markers">String methods in environment markers</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#appendix-e-rejected-features">Appendix E: Rejected features</a><ul>
|
||
<li><a class="reference internal" href="#separate-lists-for-conditional-and-unconditional-dependencies">Separate lists for conditional and unconditional dependencies</a></li>
|
||
<li><a class="reference internal" href="#separate-lists-for-semantic-dependencies">Separate lists for semantic dependencies</a></li>
|
||
<li><a class="reference internal" href="#introducing-friction-for-overly-precise-dependency-declarations">Introducing friction for overly precise dependency declarations</a></li>
|
||
<li><a class="reference internal" href="#disallowing-underscores-in-distribution-names">Disallowing underscores in distribution names</a></li>
|
||
<li><a class="reference internal" href="#allowing-the-use-of-unicode-in-distribution-names">Allowing the use of Unicode in distribution names</a></li>
|
||
<li><a class="reference internal" href="#depending-on-source-labels">Depending on source labels</a></li>
|
||
<li><a class="reference internal" href="#alternative-dependencies">Alternative dependencies</a></li>
|
||
<li><a class="reference internal" href="#compatible-release-comparisons-in-environment-markers">Compatible release comparisons in environment markers</a></li>
|
||
<li><a class="reference internal" href="#conditional-provides">Conditional provides</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#references">References</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-0426.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> |