924 lines
83 KiB
HTML
924 lines
83 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 621 – Storing project metadata in pyproject.toml | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0621/">
|
||
<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 621 – Storing project metadata in pyproject.toml | peps.python.org'>
|
||
<meta property="og:description" content="This PEP specifies how to write a project’s core metadata in a pyproject.toml file for packaging-related tools to consume.">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0621/">
|
||
<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 specifies how to write a project’s core metadata in a pyproject.toml file for packaging-related tools to consume.">
|
||
<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 621</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 621 – Storing project metadata in pyproject.toml</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Brett Cannon <brett at python.org>,
|
||
Dustin Ingram <di at python.org>,
|
||
Paul Ganssle <paul at ganssle.io>,
|
||
Pradyun Gedam <pradyunsg at gmail.com>,
|
||
Sébastien Eustace <sebastien at eustace.io>,
|
||
Thomas Kluyver <thomas at kluyver.me.uk>,
|
||
Tzu-ping Chung <uranusjr at gmail.com></dd>
|
||
<dt class="field-even">Discussions-To<span class="colon">:</span></dt>
|
||
<dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-621-round-3/5472">Discourse thread</a></dd>
|
||
<dt class="field-odd">Status<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd>
|
||
<dt class="field-even">Type<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd>
|
||
<dt class="field-odd">Topic<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="../topic/packaging/">Packaging</a></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">22-Jun-2020</dd>
|
||
<dt class="field-odd">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-odd">22-Jun-2020,
|
||
18-Oct-2020,
|
||
24-Oct-2020,
|
||
31-Oct-2020</dd>
|
||
<dt class="field-even">Resolution<span class="colon">:</span></dt>
|
||
<dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-621-round-3/5472/109">Discourse message</a></dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<section id="contents">
|
||
<details><summary>Table of Contents</summary><ul class="simple">
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#details">Details</a><ul>
|
||
<li><a class="reference internal" href="#table-name">Table name</a></li>
|
||
<li><a class="reference internal" href="#name"><code class="docutils literal notranslate"><span class="pre">name</span></code></a></li>
|
||
<li><a class="reference internal" href="#version"><code class="docutils literal notranslate"><span class="pre">version</span></code></a></li>
|
||
<li><a class="reference internal" href="#description"><code class="docutils literal notranslate"><span class="pre">description</span></code></a></li>
|
||
<li><a class="reference internal" href="#readme"><code class="docutils literal notranslate"><span class="pre">readme</span></code></a></li>
|
||
<li><a class="reference internal" href="#requires-python"><code class="docutils literal notranslate"><span class="pre">requires-python</span></code></a></li>
|
||
<li><a class="reference internal" href="#license"><code class="docutils literal notranslate"><span class="pre">license</span></code></a></li>
|
||
<li><a class="reference internal" href="#authors-maintainers"><code class="docutils literal notranslate"><span class="pre">authors</span></code>/<code class="docutils literal notranslate"><span class="pre">maintainers</span></code></a></li>
|
||
<li><a class="reference internal" href="#keywords"><code class="docutils literal notranslate"><span class="pre">keywords</span></code></a></li>
|
||
<li><a class="reference internal" href="#classifiers"><code class="docutils literal notranslate"><span class="pre">classifiers</span></code></a></li>
|
||
<li><a class="reference internal" href="#urls"><code class="docutils literal notranslate"><span class="pre">urls</span></code></a></li>
|
||
<li><a class="reference internal" href="#entry-points">Entry points</a></li>
|
||
<li><a class="reference internal" href="#dependencies-optional-dependencies"><code class="docutils literal notranslate"><span class="pre">dependencies</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code></a></li>
|
||
<li><a class="reference internal" href="#dynamic"><code class="docutils literal notranslate"><span class="pre">dynamic</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#example">Example</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li>
|
||
<li><a class="reference internal" href="#security-implications">Security Implications</a></li>
|
||
<li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li>
|
||
<li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul>
|
||
<li><a class="reference internal" href="#other-table-names">Other table names</a><ul>
|
||
<li><a class="reference internal" href="#anything-under-build-system">Anything under <code class="docutils literal notranslate"><span class="pre">[build-system]</span></code></a></li>
|
||
<li><a class="reference internal" href="#package"><code class="docutils literal notranslate"><span class="pre">[package]</span></code></a></li>
|
||
<li><a class="reference internal" href="#metadata"><code class="docutils literal notranslate"><span class="pre">[metadata]</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#support-for-a-metadata-provider">Support for a metadata provider</a></li>
|
||
<li><a class="reference internal" href="#require-a-normalized-project-name">Require a normalized project name</a></li>
|
||
<li><a class="reference internal" href="#specify-files-to-include-when-building">Specify files to include when building</a></li>
|
||
<li><a class="reference internal" href="#name-the-project-urls-table-project-project-urls">Name the <code class="docutils literal notranslate"><span class="pre">[project.urls]</span></code> table <code class="docutils literal notranslate"><span class="pre">[project.project-urls]</span></code></a></li>
|
||
<li><a class="reference internal" href="#have-a-separate-url-home-page-field">Have a separate <code class="docutils literal notranslate"><span class="pre">url</span></code>/<code class="docutils literal notranslate"><span class="pre">home-page</span></code> field</a></li>
|
||
<li><a class="reference internal" href="#recommend-that-tools-put-development-related-dependencies-into-a-dev-extra">Recommend that tools put development-related dependencies into a “dev” extra</a></li>
|
||
<li><a class="reference internal" href="#have-the-dynamic-field-only-require-specifying-missing-required-fields">Have the <code class="docutils literal notranslate"><span class="pre">dynamic</span></code> field only require specifying missing required fields</a></li>
|
||
<li><a class="reference internal" href="#different-structures-for-the-readme-field">Different structures for the <code class="docutils literal notranslate"><span class="pre">readme</span></code> field</a></li>
|
||
<li><a class="reference internal" href="#allowing-the-readme-field-to-imply-text-plain">Allowing the <code class="docutils literal notranslate"><span class="pre">readme</span></code> field to imply <code class="docutils literal notranslate"><span class="pre">text/plain</span></code></a></li>
|
||
<li><a class="reference internal" href="#other-names-for-dependencies-optional-dependencies">Other names for <code class="docutils literal notranslate"><span class="pre">dependencies</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code></a></li>
|
||
<li><a class="reference internal" href="#drop-maintainers-to-unify-with-authors">Drop <code class="docutils literal notranslate"><span class="pre">maintainers</span></code> to unify with <code class="docutils literal notranslate"><span class="pre">authors</span></code></a></li>
|
||
<li><a class="reference internal" href="#support-an-arbitrary-depth-of-tables-for-project-entry-points">Support an arbitrary depth of tables for <code class="docutils literal notranslate"><span class="pre">project.entry-points</span></code></a></li>
|
||
<li><a class="reference internal" href="#using-structured-toml-dictionaries-to-specify-dependencies">Using structured TOML dictionaries to specify dependencies</a></li>
|
||
<li><a class="reference internal" href="#require-build-back-ends-to-update-pyproject-toml-when-generating-an-sdist">Require build back-ends to update <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> when generating an sdist</a></li>
|
||
<li><a class="reference internal" href="#allow-tools-to-add-extend-data">Allow tools to add/extend data</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#open-issues">Open Issues</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<div class="pep-banner canonical-pypa-spec sticky-banner admonition attention">
|
||
<p class="admonition-title">Attention</p>
|
||
<p>This PEP is a historical document. The up-to-date, canonical spec, <a class="reference external" href="https://packaging.python.org/en/latest/specifications/pyproject-toml/#pyproject-toml-spec" title="(in Python Packaging User Guide)"><span>pyproject.toml specification</span></a>, is maintained on the <a class="reference external" href="https://packaging.python.org/en/latest/specifications/">PyPA specs page</a>.</p>
|
||
<p class="close-button">×</p>
|
||
<p>See the <a class="reference external" href="https://www.pypa.io/en/latest/specifications/#handling-fixes-and-other-minor-updates">PyPA specification update process</a> for how to propose changes.</p>
|
||
</div>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>This PEP specifies how to write a project’s <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a> in a
|
||
<code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file for packaging-related tools to consume.</p>
|
||
</section>
|
||
<section id="motivation">
|
||
<h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2>
|
||
<p>The key motivators of this PEP are:</p>
|
||
<ul class="simple">
|
||
<li>Encourage users to specify core metadata statically for speed,
|
||
ease of specification, unambiguity, and deterministic consumption by
|
||
build back-ends</li>
|
||
<li>Provide a tool-agnostic way of specifying metadata for ease of
|
||
learning and transitioning between build back-ends</li>
|
||
<li>Allow for more code sharing between build back-ends for the
|
||
“boring parts” of a project’s metadata</li>
|
||
</ul>
|
||
<p>To speak specifically to the motivation for static metadata, that has
|
||
been an overall goal of the packaging ecosystem for some time. As
|
||
such, making it easy to specify metadata statically is important. This
|
||
also means that raising the cost of specifying data as dynamic is
|
||
acceptable as users should skew towards wanting to provide static
|
||
metadata.</p>
|
||
<p>Requiring the distinction between static and dynamic metadata also
|
||
helps with disambiguation for when metadata isn’t specified. When any
|
||
metadata <em>may</em> be dynamic, it means you never know if the absence of
|
||
metadata is on purpose or because it is to be provided later. By
|
||
requiring that dynamic metadata be specified, it disambiguates the
|
||
intent when metadata goes unspecified.</p>
|
||
<p>This PEP does <strong>not</strong> attempt to standardize all possible metadata
|
||
required by a build back-end, only the metadata covered by the
|
||
<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a> specification which are very common across projects
|
||
and would stand to benefit from being static and consistently
|
||
specified. This means build back-ends are still free and able to
|
||
innovate around patterns like how to specify the files to include in a
|
||
wheel. There is also an included escape hatch for users and build
|
||
back-ends to use when they choose to partially opt-out of this PEP
|
||
(compared to opting-out of this PEP entirely, which is also possible).</p>
|
||
<p>This PEP is also not trying to change the underlying <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a>
|
||
in any way. Such considerations should be done in a separate PEP which
|
||
may lead to changes or additions to what this PEP specifies.</p>
|
||
</section>
|
||
<section id="rationale">
|
||
<h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2>
|
||
<p>The design guidelines the authors of this PEP followed were:</p>
|
||
<ul class="simple">
|
||
<li>Define a representation of as much of the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a> in
|
||
<code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> as is reasonable</li>
|
||
<li>Define the metadata statically with an escape hatch for those who
|
||
want to define it dynamically later via a build back-end</li>
|
||
<li>Use familiar names where it makes sense, but be willing to use more
|
||
modern terminology</li>
|
||
<li>Try to be ergonomic within a TOML file instead of mirroring how
|
||
build back-ends specify metadata at a low-level when it makes sense</li>
|
||
<li>Learn from other build back-ends in the packaging ecosystem which
|
||
have used TOML for their metadata</li>
|
||
<li>Don’t try to standardize things which lack a pre-existing standard
|
||
at a lower-level</li>
|
||
<li><em>When</em> metadata is specified using this PEP, it is considered
|
||
canonical</li>
|
||
</ul>
|
||
</section>
|
||
<section id="specification">
|
||
<h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2>
|
||
<p>When specifying project metadata, tools MUST adhere and honour the
|
||
metadata as specified in this PEP. If metadata is improperly specified
|
||
then tools MUST raise an error to notify the user about their mistake.</p>
|
||
<p>Data specified using this PEP is considered canonical. Tools CANNOT
|
||
remove, add or change data that has been statically specified. Only
|
||
when a field is marked as <code class="docutils literal notranslate"><span class="pre">dynamic</span></code> may a tool provide a “new” value.</p>
|
||
<section id="details">
|
||
<h3><a class="toc-backref" href="#details" role="doc-backlink">Details</a></h3>
|
||
<section id="table-name">
|
||
<h4><a class="toc-backref" href="#table-name" role="doc-backlink">Table name</a></h4>
|
||
<p>Tools MUST specify fields defined by this PEP in a table named
|
||
<code class="docutils literal notranslate"><span class="pre">[project]</span></code>. No tools may add fields to this table which are not
|
||
defined by this PEP or subsequent PEPs. For tools wishing to store
|
||
their own settings in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>, they may use the <code class="docutils literal notranslate"><span class="pre">[tool]</span></code>
|
||
table as defined in <a class="pep reference internal" href="../pep-0518/" title="PEP 518 – Specifying Minimum Build System Requirements for Python Projects">PEP 518</a>. The lack of a <code class="docutils literal notranslate"><span class="pre">[project]</span></code> table
|
||
implicitly means the build back-end will dynamically provide all
|
||
fields.</p>
|
||
</section>
|
||
<section id="name">
|
||
<h4><a class="toc-backref" href="#name" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">name</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: string</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">Name</span></code>
|
||
(<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#name">link</a>)</li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: <code class="docutils literal notranslate"><span class="pre">module</span></code>/<code class="docutils literal notranslate"><span class="pre">dist-name</span></code>
|
||
(<a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#metadata-section">link</a>)</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: <code class="docutils literal notranslate"><span class="pre">name</span></code>
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#name">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">name</span></code>
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The name of the project.</p>
|
||
<p>Tools MUST require users to statically define this field.</p>
|
||
<p>Tools SHOULD normalize this name, as specified by <a class="pep reference internal" href="../pep-0503/" title="PEP 503 – Simple Repository API">PEP 503</a>, as soon
|
||
as it is read for internal consistency.</p>
|
||
</section>
|
||
<section id="version">
|
||
<h4><a class="toc-backref" href="#version" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">version</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: string</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">Version</span></code>
|
||
(<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#version">link</a>)</li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: N/A (read from a <code class="docutils literal notranslate"><span class="pre">__version__</span></code> attribute)
|
||
(<a class="reference external" href="https://flit.readthedocs.io/en/latest/index.html#usage">link</a>)</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: <code class="docutils literal notranslate"><span class="pre">version</span></code>
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#version">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">version</span></code>
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The version of the project as supported by <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a>.</p>
|
||
<p>Users SHOULD prefer to specify already-normalized versions.</p>
|
||
</section>
|
||
<section id="description">
|
||
<h4><a class="toc-backref" href="#description" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">description</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: string</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">Summary</span></code>
|
||
(<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#summary">link</a>)</li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: N/A</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: <code class="docutils literal notranslate"><span class="pre">description</span></code>
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#description">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">description</span></code>
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The summary description of the project.</p>
|
||
</section>
|
||
<section id="readme">
|
||
<h4><a class="toc-backref" href="#readme" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">readme</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: String or table</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">Description</span></code>
|
||
(<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#description">link</a>)</li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: <code class="docutils literal notranslate"><span class="pre">description-file</span></code>
|
||
(<a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#metadata-section">link</a>)</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: <code class="docutils literal notranslate"><span class="pre">readme</span></code>
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#readme">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">long_description</span></code>
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The full description of the project (i.e. the README).</p>
|
||
<p>The field accepts either a string or a table. If it is a string then
|
||
it is the relative path to a text file containing the full
|
||
description. Tools MUST assume the file’s encoding is UTF-8. If the
|
||
file path ends in a case-insensitive <code class="docutils literal notranslate"><span class="pre">.md</span></code> suffix, then tools MUST
|
||
assume the content-type is <code class="docutils literal notranslate"><span class="pre">text/markdown</span></code>. If the file path ends in
|
||
a case-insensitive <code class="docutils literal notranslate"><span class="pre">.rst</span></code>, then tools MUST assume the content-type
|
||
is <code class="docutils literal notranslate"><span class="pre">text/x-rst</span></code>. If a tool recognizes more extensions than this PEP,
|
||
they MAY infer the content-type for the user without specifying this
|
||
field as <code class="docutils literal notranslate"><span class="pre">dynamic</span></code>. For all unrecognized suffixes when a
|
||
content-type is not provided, tools MUST raise an error.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">readme</span></code> field may also take a table. The <code class="docutils literal notranslate"><span class="pre">file</span></code> key has a
|
||
string value representing a relative path to a file containing the
|
||
full description. The <code class="docutils literal notranslate"><span class="pre">text</span></code> key has a string value which is the
|
||
full description. These keys are mutually-exclusive, thus tools MUST
|
||
raise an error if the metadata specifies both keys.</p>
|
||
<p>A table specified in the <code class="docutils literal notranslate"><span class="pre">readme</span></code> field also has a <code class="docutils literal notranslate"><span class="pre">content-type</span></code>
|
||
field which takes a string specifying the content-type of the full
|
||
description. A tool MUST raise an error if the metadata does not
|
||
specify this field in the table. If the metadata does not specify the
|
||
<code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter, then it is assumed to be UTF-8. Tools MAY
|
||
support other encodings if they choose to. Tools MAY support
|
||
alternative content-types which they can transform to a content-type
|
||
as supported by the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a>. Otherwise tools MUST raise an
|
||
error for unsupported content-types.</p>
|
||
</section>
|
||
<section id="requires-python">
|
||
<h4><a class="toc-backref" href="#requires-python" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">requires-python</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: string</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">Requires-Python</span></code>
|
||
(<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#summary">link</a>)</li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: <code class="docutils literal notranslate"><span class="pre">requires-python</span></code>
|
||
(<a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#metadata-section">link</a>)</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: As a <code class="docutils literal notranslate"><span class="pre">python</span></code> dependency in the
|
||
<code class="docutils literal notranslate"><span class="pre">[tool.poetry.dependencies]</span></code> table
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#dependencies-and-dev-dependencies">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">python_requires</span></code>
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The Python version requirements of the project.</p>
|
||
</section>
|
||
<section id="license">
|
||
<h4><a class="toc-backref" href="#license" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">license</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: Table</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">License</span></code>
|
||
(<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#license">link</a>)</li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: <code class="docutils literal notranslate"><span class="pre">license</span></code>
|
||
(<a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#metadata-section">link</a>)</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: <code class="docutils literal notranslate"><span class="pre">license</span></code>
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#license">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">license</span></code>, <code class="docutils literal notranslate"><span class="pre">license_file</span></code>, <code class="docutils literal notranslate"><span class="pre">license_files</span></code>
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The table may have one of two keys. The <code class="docutils literal notranslate"><span class="pre">file</span></code> key has a string
|
||
value that is a relative file path to the file which contains the
|
||
license for the project. Tools MUST assume the file’s encoding is
|
||
UTF-8. The <code class="docutils literal notranslate"><span class="pre">text</span></code> key has a string value which is the license of the
|
||
project whose meaning is that of the <code class="docutils literal notranslate"><span class="pre">License</span></code> field from the
|
||
<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a>. These keys are mutually exclusive, so a tool MUST
|
||
raise an error if the metadata specifies both keys.</p>
|
||
<p>A practical string value for the <code class="docutils literal notranslate"><span class="pre">license</span></code> key has been purposefully
|
||
left out to allow for a future PEP to specify support for <a class="reference external" href="https://spdx.dev/">SPDX</a>
|
||
expressions (the same logic applies to any sort of “type” field
|
||
specifying what license the <code class="docutils literal notranslate"><span class="pre">file</span></code> or <code class="docutils literal notranslate"><span class="pre">text</span></code> represents).</p>
|
||
</section>
|
||
<section id="authors-maintainers">
|
||
<h4><a class="toc-backref" href="#authors-maintainers" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">authors</span></code>/<code class="docutils literal notranslate"><span class="pre">maintainers</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: Array of inline tables with string keys and values</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">Author</span></code>/<code class="docutils literal notranslate"><span class="pre">Author-email</span></code>/<code class="docutils literal notranslate"><span class="pre">Maintainer</span></code>/<code class="docutils literal notranslate"><span class="pre">Maintainer-email</span></code>
|
||
(<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#author">link</a>)</li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: <code class="docutils literal notranslate"><span class="pre">author</span></code>/<code class="docutils literal notranslate"><span class="pre">author-email</span></code>/<code class="docutils literal notranslate"><span class="pre">maintainer</span></code>/<code class="docutils literal notranslate"><span class="pre">maintainer-email</span></code>
|
||
(<a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#metadata-section">link</a>)</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: <code class="docutils literal notranslate"><span class="pre">authors</span></code>/<code class="docutils literal notranslate"><span class="pre">maintainers</span></code>
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#authors">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">author</span></code>/<code class="docutils literal notranslate"><span class="pre">author_email</span></code>/<code class="docutils literal notranslate"><span class="pre">maintainer</span></code>/<code class="docutils literal notranslate"><span class="pre">maintainer_email</span></code>
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The people or organizations considered to be the “authors” of the
|
||
project. The exact meaning is open to interpretation — it may list the
|
||
original or primary authors, current maintainers, or owners of the
|
||
package.</p>
|
||
<p>The “maintainers” field is similar to “authors” in that its exact
|
||
meaning is open to interpretation.</p>
|
||
<p>These fields accept an array of tables with 2 keys: <code class="docutils literal notranslate"><span class="pre">name</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">email</span></code>. Both values must be strings. The <code class="docutils literal notranslate"><span class="pre">name</span></code> value MUST be a
|
||
valid email name (i.e. whatever can be put as a name, before an email,
|
||
in <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc822.html"><strong>RFC 822</strong></a>) and not contain commas. The <code class="docutils literal notranslate"><span class="pre">email</span></code> value MUST be a
|
||
valid email address. Both keys are optional.</p>
|
||
<p>Using the data to fill in <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a> is as follows:</p>
|
||
<ol class="arabic simple">
|
||
<li>If only <code class="docutils literal notranslate"><span class="pre">name</span></code> is provided, the value goes in
|
||
<code class="docutils literal notranslate"><span class="pre">Author</span></code>/<code class="docutils literal notranslate"><span class="pre">Maintainer</span></code> as appropriate.</li>
|
||
<li>If only <code class="docutils literal notranslate"><span class="pre">email</span></code> is provided, the value goes in
|
||
<code class="docutils literal notranslate"><span class="pre">Author-email</span></code>/<code class="docutils literal notranslate"><span class="pre">Maintainer-email</span></code> as appropriate.</li>
|
||
<li>If both <code class="docutils literal notranslate"><span class="pre">email</span></code> and <code class="docutils literal notranslate"><span class="pre">name</span></code> are provided, the value goes in
|
||
<code class="docutils literal notranslate"><span class="pre">Author-email</span></code>/<code class="docutils literal notranslate"><span class="pre">Maintainer-email</span></code> as appropriate, with the
|
||
format <code class="docutils literal notranslate"><span class="pre">{name}</span> <span class="pre"><{email}></span></code> (with appropriate quoting, e.g. using
|
||
<code class="docutils literal notranslate"><span class="pre">email.headerregistry.Address</span></code>).</li>
|
||
<li>Multiple values should be separated by commas.</li>
|
||
</ol>
|
||
</section>
|
||
<section id="keywords">
|
||
<h4><a class="toc-backref" href="#keywords" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">keywords</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: array of strings</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">Keywords</span></code>
|
||
(<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#keywords">link</a>)</li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: <code class="docutils literal notranslate"><span class="pre">keywords</span></code>
|
||
(<a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#metadata-section">link</a>)</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: <code class="docutils literal notranslate"><span class="pre">keywords</span></code>
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#keywords">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">keywords</span></code>
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The keywords for the project.</p>
|
||
</section>
|
||
<section id="classifiers">
|
||
<h4><a class="toc-backref" href="#classifiers" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">classifiers</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: array of strings</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">Classifier</span></code>
|
||
(<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#classifier-multiple-use">link</a>)</li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: <code class="docutils literal notranslate"><span class="pre">classifiers</span></code>
|
||
(<a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#metadata-section">link</a>)</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: <code class="docutils literal notranslate"><span class="pre">classifiers</span></code>
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#classifiers">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">classifiers</span></code>
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p><a class="reference external" href="https://pypi.org/classifiers/">Trove classifiers</a> which apply to the project.</p>
|
||
</section>
|
||
<section id="urls">
|
||
<h4><a class="toc-backref" href="#urls" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">urls</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: Table, with keys and values of strings</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">Project-URL</span></code>
|
||
(<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#project-url-multiple-use">link</a>)</li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: <code class="docutils literal notranslate"><span class="pre">[tool.flit.metadata.urls]</span></code> table
|
||
(<a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#metadata-section">link</a>)</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: <code class="docutils literal notranslate"><span class="pre">[tool.poetry.urls]</span></code> table
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#urls">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">project_urls</span></code>
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>A table of URLs where the key is the URL label and the value is the
|
||
URL itself.</p>
|
||
</section>
|
||
<section id="entry-points">
|
||
<h4><a class="toc-backref" href="#entry-points" role="doc-backlink">Entry points</a></h4>
|
||
<ul class="simple">
|
||
<li>Format: Table (<code class="docutils literal notranslate"><span class="pre">[project.scripts]</span></code>, <code class="docutils literal notranslate"><span class="pre">[project.gui-scripts]</span></code>, and
|
||
<code class="docutils literal notranslate"><span class="pre">[project.entry-points]</span></code>)</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: N/A;
|
||
<a class="reference external" href="https://packaging.python.org/specifications/entry-points/">Entry points specification</a></li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: <code class="docutils literal notranslate"><span class="pre">[tool.flit.scripts]</span></code> table for console scripts,
|
||
<code class="docutils literal notranslate"><span class="pre">[tool.flit.entrypoints]</span></code> for the rest
|
||
(<a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#scripts-section">link</a>)</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: <code class="docutils literal notranslate"><span class="pre">[tool.poetry.scripts]</span></code> table for console scripts
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#scripts">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">entry_points</span></code>
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>There are three tables related to entry points. The
|
||
<code class="docutils literal notranslate"><span class="pre">[project.scripts]</span></code> table corresponds to the <code class="docutils literal notranslate"><span class="pre">console_scripts</span></code>
|
||
group in the <a class="reference external" href="https://packaging.python.org/specifications/entry-points/">entry points specification</a>. The key of the table is the name of the
|
||
entry point and the value is the object reference.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">[project.gui-scripts]</span></code> table corresponds to the <code class="docutils literal notranslate"><span class="pre">gui_scripts</span></code>
|
||
group in the <a class="reference external" href="https://packaging.python.org/specifications/entry-points/">entry points specification</a>. Its format is the same as
|
||
<code class="docutils literal notranslate"><span class="pre">[project.scripts]</span></code>.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">[project.entry-points]</span></code> table is a collection of tables. Each
|
||
sub-table’s name is an entry point group. The key and value semantics
|
||
are the same as <code class="docutils literal notranslate"><span class="pre">[project.scripts]</span></code>. Users MUST NOT create
|
||
nested sub-tables but instead keep the entry point groups to only one
|
||
level deep.</p>
|
||
<p>Build back-ends MUST raise an error if the metadata defines a
|
||
<code class="docutils literal notranslate"><span class="pre">[project.entry-points.console_scripts]</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">[project.entry-points.gui_scripts]</span></code> table, as they would
|
||
be ambiguous in the face of <code class="docutils literal notranslate"><span class="pre">[project.scripts]</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">[project.gui-scripts]</span></code>, respectively.</p>
|
||
</section>
|
||
<section id="dependencies-optional-dependencies">
|
||
<h4><a class="toc-backref" href="#dependencies-optional-dependencies" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">dependencies</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: Array of <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> strings (<code class="docutils literal notranslate"><span class="pre">dependencies</span></code>) and a table
|
||
with values of arrays of <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> strings
|
||
(<code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code>)</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: <code class="docutils literal notranslate"><span class="pre">Requires-Dist</span></code> and <code class="docutils literal notranslate"><span class="pre">Provides-Extra</span></code>
|
||
(<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#requires-dist-multiple-use">link</a>,
|
||
<a class="reference external" href="https://packaging.python.org/specifications/core-metadata/#provides-extra-multiple-use">link</a>)</li>
|
||
<li>Synonyms<ul>
|
||
<li><a class="reference external" href="https://flit.readthedocs.io/">Flit</a>: <code class="docutils literal notranslate"><span class="pre">requires</span></code> for required dependencies, <code class="docutils literal notranslate"><span class="pre">requires-extra</span></code>
|
||
for optional dependencies
|
||
(<a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#metadata-section">link</a>)</li>
|
||
<li><a class="reference external" href="https://python-poetry.org/">Poetry</a>: <code class="docutils literal notranslate"><span class="pre">[tool.poetry.dependencies]</span></code> for dependencies (both
|
||
required and for development),
|
||
<code class="docutils literal notranslate"><span class="pre">[tool.poetry.extras]</span></code> for optional dependencies
|
||
(<a class="reference external" href="https://python-poetry.org/docs/pyproject/#dependencies-and-dev-dependencies">link</a>)</li>
|
||
<li><a class="reference external" href="https://setuptools.readthedocs.io/">Setuptools</a>: <code class="docutils literal notranslate"><span class="pre">install_requires</span></code> for required dependencies,
|
||
<code class="docutils literal notranslate"><span class="pre">extras_require</span></code> for optional dependencies
|
||
(<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata">link</a>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>The (optional) dependencies of the project.</p>
|
||
<p>For <code class="docutils literal notranslate"><span class="pre">dependencies</span></code>, it is a key whose value is an array of strings.
|
||
Each string represents a dependency of the project and MUST be
|
||
formatted as a valid <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> string. Each string maps directly to
|
||
a <code class="docutils literal notranslate"><span class="pre">Requires-Dist</span></code> entry in the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a>.</p>
|
||
<p>For <code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code>, it is a table where each key specifies
|
||
an extra and whose value is an array of strings. The strings of the
|
||
arrays must be valid <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> strings. The keys MUST be valid values
|
||
for the <code class="docutils literal notranslate"><span class="pre">Provides-Extra</span></code> <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a>. Each value in the array
|
||
thus becomes a corresponding <code class="docutils literal notranslate"><span class="pre">Requires-Dist</span></code> entry for the matching
|
||
<code class="docutils literal notranslate"><span class="pre">Provides-Extra</span></code> metadata.</p>
|
||
</section>
|
||
<section id="dynamic">
|
||
<h4><a class="toc-backref" href="#dynamic" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">dynamic</span></code></a></h4>
|
||
<ul class="simple">
|
||
<li>Format: Array of strings</li>
|
||
<li><a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">Core metadata</a>: N/A</li>
|
||
<li>No synonyms</li>
|
||
</ul>
|
||
<p>Specifies which fields listed by this PEP were intentionally
|
||
unspecified so another tool can/will provide such metadata
|
||
dynamically. This clearly delineates which metadata is purposefully
|
||
unspecified and expected to stay unspecified compared to being
|
||
provided via tooling later on.</p>
|
||
<ul class="simple">
|
||
<li>A build back-end MUST honour statically-specified metadata (which
|
||
means the metadata did not list the field in <code class="docutils literal notranslate"><span class="pre">dynamic</span></code>).</li>
|
||
<li>A build back-end MUST raise an error if the metadata specifies the
|
||
<code class="docutils literal notranslate"><span class="pre">name</span></code> in <code class="docutils literal notranslate"><span class="pre">dynamic</span></code>.</li>
|
||
<li>If the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a> specification lists a field as “Required”,
|
||
then the metadata MUST specify the field statically or list it in
|
||
<code class="docutils literal notranslate"><span class="pre">dynamic</span></code> (build back-ends MUST raise an error otherwise, i.e. it
|
||
should not be possible for a required field to not be listed somehow
|
||
in the <code class="docutils literal notranslate"><span class="pre">[project]</span></code> table).</li>
|
||
<li>If the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a> specification lists a field as “Optional”,
|
||
the metadata MAY list it in <code class="docutils literal notranslate"><span class="pre">dynamic</span></code> if the expectation is a
|
||
build back-end will provide the data for the field later.</li>
|
||
<li>Build back-ends MUST raise an error if the metadata specifies a
|
||
field statically as well as being listed in <code class="docutils literal notranslate"><span class="pre">dynamic</span></code>.</li>
|
||
<li>If the metadata does not list a field in <code class="docutils literal notranslate"><span class="pre">dynamic</span></code>, then a build
|
||
back-end CANNOT fill in the requisite metadata on behalf of the user
|
||
(i.e. <code class="docutils literal notranslate"><span class="pre">dynamic</span></code> is the only way to allow a tool to fill in
|
||
metadata and the user must opt into the filling in).</li>
|
||
<li>Build back-ends MUST raise an error if the metadata specifies a
|
||
field in dynamic but the build back-end was unable to provide the
|
||
data for it.</li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
<section id="example">
|
||
<h3><a class="toc-backref" href="#example" role="doc-backlink">Example</a></h3>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">project</span><span class="p">]</span>
|
||
<span class="n">name</span> <span class="o">=</span> <span class="s2">"spam"</span>
|
||
<span class="n">version</span> <span class="o">=</span> <span class="s2">"2020.0.0"</span>
|
||
<span class="n">description</span> <span class="o">=</span> <span class="s2">"Lovely Spam! Wonderful Spam!"</span>
|
||
<span class="n">readme</span> <span class="o">=</span> <span class="s2">"README.rst"</span>
|
||
<span class="n">requires</span><span class="o">-</span><span class="n">python</span> <span class="o">=</span> <span class="s2">">=3.8"</span>
|
||
<span class="n">license</span> <span class="o">=</span> <span class="p">{</span><span class="n">file</span> <span class="o">=</span> <span class="s2">"LICENSE.txt"</span><span class="p">}</span>
|
||
<span class="n">keywords</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"egg"</span><span class="p">,</span> <span class="s2">"bacon"</span><span class="p">,</span> <span class="s2">"sausage"</span><span class="p">,</span> <span class="s2">"tomatoes"</span><span class="p">,</span> <span class="s2">"Lobster Thermidor"</span><span class="p">]</span>
|
||
<span class="n">authors</span> <span class="o">=</span> <span class="p">[</span>
|
||
<span class="p">{</span><span class="n">email</span> <span class="o">=</span> <span class="s2">"hi@pradyunsg.me"</span><span class="p">},</span>
|
||
<span class="p">{</span><span class="n">name</span> <span class="o">=</span> <span class="s2">"Tzu-ping Chung"</span><span class="p">}</span>
|
||
<span class="p">]</span>
|
||
<span class="n">maintainers</span> <span class="o">=</span> <span class="p">[</span>
|
||
<span class="p">{</span><span class="n">name</span> <span class="o">=</span> <span class="s2">"Brett Cannon"</span><span class="p">,</span> <span class="n">email</span> <span class="o">=</span> <span class="s2">"brett@python.org"</span><span class="p">}</span>
|
||
<span class="p">]</span>
|
||
<span class="n">classifiers</span> <span class="o">=</span> <span class="p">[</span>
|
||
<span class="s2">"Development Status :: 4 - Beta"</span><span class="p">,</span>
|
||
<span class="s2">"Programming Language :: Python"</span>
|
||
<span class="p">]</span>
|
||
|
||
<span class="n">dependencies</span> <span class="o">=</span> <span class="p">[</span>
|
||
<span class="s2">"httpx"</span><span class="p">,</span>
|
||
<span class="s2">"gidgethub[httpx]>4.0.0"</span><span class="p">,</span>
|
||
<span class="s2">"django>2.1; os_name != 'nt'"</span><span class="p">,</span>
|
||
<span class="s2">"django>2.0; os_name == 'nt'"</span>
|
||
<span class="p">]</span>
|
||
|
||
<span class="p">[</span><span class="n">project</span><span class="o">.</span><span class="n">optional</span><span class="o">-</span><span class="n">dependencies</span><span class="p">]</span>
|
||
<span class="n">test</span> <span class="o">=</span> <span class="p">[</span>
|
||
<span class="s2">"pytest < 5.0.0"</span><span class="p">,</span>
|
||
<span class="s2">"pytest-cov[all]"</span>
|
||
<span class="p">]</span>
|
||
|
||
<span class="p">[</span><span class="n">project</span><span class="o">.</span><span class="n">urls</span><span class="p">]</span>
|
||
<span class="n">homepage</span> <span class="o">=</span> <span class="s2">"https://example.com"</span>
|
||
<span class="n">documentation</span> <span class="o">=</span> <span class="s2">"https://readthedocs.org"</span>
|
||
<span class="n">repository</span> <span class="o">=</span> <span class="s2">"https://github.com"</span>
|
||
<span class="n">changelog</span> <span class="o">=</span> <span class="s2">"https://github.com/me/spam/blob/master/CHANGELOG.md"</span>
|
||
|
||
<span class="p">[</span><span class="n">project</span><span class="o">.</span><span class="n">scripts</span><span class="p">]</span>
|
||
<span class="n">spam</span><span class="o">-</span><span class="n">cli</span> <span class="o">=</span> <span class="s2">"spam:main_cli"</span>
|
||
|
||
<span class="p">[</span><span class="n">project</span><span class="o">.</span><span class="n">gui</span><span class="o">-</span><span class="n">scripts</span><span class="p">]</span>
|
||
<span class="n">spam</span><span class="o">-</span><span class="n">gui</span> <span class="o">=</span> <span class="s2">"spam:main_gui"</span>
|
||
|
||
<span class="p">[</span><span class="n">project</span><span class="o">.</span><span class="n">entry</span><span class="o">-</span><span class="n">points</span><span class="o">.</span><span class="s2">"spam.magical"</span><span class="p">]</span>
|
||
<span class="n">tomatoes</span> <span class="o">=</span> <span class="s2">"spam:main_tomatoes"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="backwards-compatibility">
|
||
<h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2>
|
||
<p>As this provides a new way to specify a project’s <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a> and
|
||
is using a new table name which falls under the reserved namespace as
|
||
outlined in <a class="pep reference internal" href="../pep-0518/" title="PEP 518 – Specifying Minimum Build System Requirements for Python Projects">PEP 518</a>, there are no backwards-compatibility concerns.</p>
|
||
</section>
|
||
<section id="security-implications">
|
||
<h2><a class="toc-backref" href="#security-implications" role="doc-backlink">Security Implications</a></h2>
|
||
<p>There are no direct security concerns as this PEP covers how to
|
||
statically define project metadata. Any security issues would stem
|
||
from how tools consume the metadata and choose to act upon it.</p>
|
||
</section>
|
||
<section id="reference-implementation">
|
||
<h2><a class="toc-backref" href="#reference-implementation" role="doc-backlink">Reference Implementation</a></h2>
|
||
<p>There are currently no proofs-of-concept from any build back-end
|
||
implementing this PEP.</p>
|
||
</section>
|
||
<section id="rejected-ideas">
|
||
<h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2>
|
||
<section id="other-table-names">
|
||
<h3><a class="toc-backref" href="#other-table-names" role="doc-backlink">Other table names</a></h3>
|
||
<section id="anything-under-build-system">
|
||
<h4><a class="toc-backref" href="#anything-under-build-system" role="doc-backlink">Anything under <code class="docutils literal notranslate"><span class="pre">[build-system]</span></code></a></h4>
|
||
<p>There was worry that using this table name would exacerbate confusion
|
||
between build metadata and project metadata, e.g. by using
|
||
<code class="docutils literal notranslate"><span class="pre">[build-system.metadata]</span></code> as a table.</p>
|
||
</section>
|
||
<section id="package">
|
||
<h4><a class="toc-backref" href="#package" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">[package]</span></code></a></h4>
|
||
<p>Garnered no strong support.</p>
|
||
</section>
|
||
<section id="metadata">
|
||
<h4><a class="toc-backref" href="#metadata" role="doc-backlink"><code class="docutils literal notranslate"><span class="pre">[metadata]</span></code></a></h4>
|
||
<p>The strongest contender after <code class="docutils literal notranslate"><span class="pre">[project]</span></code>, but in the end it was
|
||
agreed that <code class="docutils literal notranslate"><span class="pre">[project]</span></code> read better for certain sub-tables, e.g.
|
||
<code class="docutils literal notranslate"><span class="pre">[project.urls]</span></code>.</p>
|
||
</section>
|
||
</section>
|
||
<section id="support-for-a-metadata-provider">
|
||
<h3><a class="toc-backref" href="#support-for-a-metadata-provider" role="doc-backlink">Support for a metadata provider</a></h3>
|
||
<p>Initially there was a proposal to add a middle layer between the
|
||
static metadata specified by this PEP and
|
||
<code class="docutils literal notranslate"><span class="pre">prepare_metadata_for_build_wheel()</span></code> as specified by <a class="pep reference internal" href="../pep-0517/" title="PEP 517 – A build-system independent format for source trees">PEP 517</a>. The
|
||
idea was that if a project wanted to insert itself between a build
|
||
back-end and the metadata there would be a hook to do so.</p>
|
||
<p>In the end the authors considered this idea unnecessarily complicated
|
||
and would move the PEP away from its design goal to push people to
|
||
define core metadata statically as much as possible.</p>
|
||
</section>
|
||
<section id="require-a-normalized-project-name">
|
||
<h3><a class="toc-backref" href="#require-a-normalized-project-name" role="doc-backlink">Require a normalized project name</a></h3>
|
||
<p>While it would make things easier for tools to only work with the
|
||
normalized name as specified in <a class="pep reference internal" href="../pep-0503/" title="PEP 503 – Simple Repository API">PEP 503</a>, the idea was ultimately
|
||
rejected as it would hurt projects transitioning to using this PEP.</p>
|
||
</section>
|
||
<section id="specify-files-to-include-when-building">
|
||
<h3><a class="toc-backref" href="#specify-files-to-include-when-building" role="doc-backlink">Specify files to include when building</a></h3>
|
||
<p>The authors decided fairly quickly during design discussions that
|
||
this PEP should focus exclusively on project metadata and not build
|
||
metadata. As such, specifying what files should end up in a source
|
||
distribution or wheel file is out of scope for this PEP.</p>
|
||
</section>
|
||
<section id="name-the-project-urls-table-project-project-urls">
|
||
<h3><a class="toc-backref" href="#name-the-project-urls-table-project-project-urls" role="doc-backlink">Name the <code class="docutils literal notranslate"><span class="pre">[project.urls]</span></code> table <code class="docutils literal notranslate"><span class="pre">[project.project-urls]</span></code></a></h3>
|
||
<p>This suggestion came thanks to the corresponding <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a>
|
||
being <code class="docutils literal notranslate"><span class="pre">Project-Url</span></code>. But once the overall table name of <code class="docutils literal notranslate"><span class="pre">[project]</span></code>
|
||
was chosen, the redundant use of the word “project” suggested the
|
||
current, shorter name was a better fit.</p>
|
||
</section>
|
||
<section id="have-a-separate-url-home-page-field">
|
||
<h3><a class="toc-backref" href="#have-a-separate-url-home-page-field" role="doc-backlink">Have a separate <code class="docutils literal notranslate"><span class="pre">url</span></code>/<code class="docutils literal notranslate"><span class="pre">home-page</span></code> field</a></h3>
|
||
<p>While the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a> supports it, having a single field for a
|
||
project’s URL while also supporting a full table seemed redundant and
|
||
confusing.</p>
|
||
</section>
|
||
<section id="recommend-that-tools-put-development-related-dependencies-into-a-dev-extra">
|
||
<h3><a class="toc-backref" href="#recommend-that-tools-put-development-related-dependencies-into-a-dev-extra" role="doc-backlink">Recommend that tools put development-related dependencies into a “dev” extra</a></h3>
|
||
<p>As various tools have grown the concept of required dependencies
|
||
versus development dependencies, the idea of suggesting to tools that
|
||
they put such development tool into a “dev” grouping came up. In the
|
||
end, though, the authors deemed it out-of-scope for this specification
|
||
to suggest such a workflow.</p>
|
||
</section>
|
||
<section id="have-the-dynamic-field-only-require-specifying-missing-required-fields">
|
||
<h3><a class="toc-backref" href="#have-the-dynamic-field-only-require-specifying-missing-required-fields" role="doc-backlink">Have the <code class="docutils literal notranslate"><span class="pre">dynamic</span></code> field only require specifying missing required fields</a></h3>
|
||
<p>The authors considered the idea that the <code class="docutils literal notranslate"><span class="pre">dynamic</span></code> field would only
|
||
require the listing of missing required fields and make listing
|
||
optional fields optional. In the end, though, this went against the
|
||
design goal of promoting specifying as much information statically as
|
||
possible.</p>
|
||
</section>
|
||
<section id="different-structures-for-the-readme-field">
|
||
<h3><a class="toc-backref" href="#different-structures-for-the-readme-field" role="doc-backlink">Different structures for the <code class="docutils literal notranslate"><span class="pre">readme</span></code> field</a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">readme</span></code> field had a proposed <code class="docutils literal notranslate"><span class="pre">readme_content_type</span></code> field, but
|
||
the authors considered the string/table hybrid more practical for the
|
||
common case while still accommodating the more complex case. Same goes
|
||
for using <code class="docutils literal notranslate"><span class="pre">long_description</span></code> and a corresponding
|
||
<code class="docutils literal notranslate"><span class="pre">long_description_content_type</span></code> field.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">file</span></code> key in the table format was originally proposed as
|
||
<code class="docutils literal notranslate"><span class="pre">path</span></code>, but <code class="docutils literal notranslate"><span class="pre">file</span></code> corresponds to setuptools’ <code class="docutils literal notranslate"><span class="pre">file</span></code> key and
|
||
there is no strong reason otherwise to choose one over the other.</p>
|
||
</section>
|
||
<section id="allowing-the-readme-field-to-imply-text-plain">
|
||
<h3><a class="toc-backref" href="#allowing-the-readme-field-to-imply-text-plain" role="doc-backlink">Allowing the <code class="docutils literal notranslate"><span class="pre">readme</span></code> field to imply <code class="docutils literal notranslate"><span class="pre">text/plain</span></code></a></h3>
|
||
<p>The authors considered allowing for unspecified content-types which
|
||
would default to <code class="docutils literal notranslate"><span class="pre">text/plain</span></code>, but decided that it would be best to
|
||
be explicit in this case to prevent accidental incorrect renderings on
|
||
PyPI and to force users to be clear in their intent.</p>
|
||
</section>
|
||
<section id="other-names-for-dependencies-optional-dependencies">
|
||
<h3><a class="toc-backref" href="#other-names-for-dependencies-optional-dependencies" role="doc-backlink">Other names for <code class="docutils literal notranslate"><span class="pre">dependencies</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code></a></h3>
|
||
<p>The authors originally proposed <code class="docutils literal notranslate"><span class="pre">requires</span></code>/<code class="docutils literal notranslate"><span class="pre">extra-requires</span></code> as
|
||
names, but decided to go with the current names after a survey of
|
||
other packaging ecosystems showed Python was an outlier:</p>
|
||
<ol class="arabic simple">
|
||
<li><a class="reference external" href="https://docs.npmjs.com/files/package.json#optionaldependencies">npm</a></li>
|
||
<li><a class="reference external" href="https://doc.rust-lang.org/cargo/guide/dependencies.html">Rust</a></li>
|
||
<li><a class="reference external" href="https://dart.dev/guides/packages">Dart</a></li>
|
||
<li><a class="reference external" href="https://swift.org/package-manager/">Swift</a></li>
|
||
<li><a class="reference external" href="https://guides.rubygems.org/specification-reference/#add_runtime_dependency">Ruby</a></li>
|
||
</ol>
|
||
<p>Normalizing on the current names helps minimize confusion for people coming from
|
||
other ecosystems without using terminology that is necessarily foreign to new
|
||
programmers. It also prevents potential confusion with <code class="docutils literal notranslate"><span class="pre">requires</span></code> in the
|
||
<code class="docutils literal notranslate"><span class="pre">[build-system]</span></code> table as specified in <a class="pep reference internal" href="../pep-0518/" title="PEP 518 – Specifying Minimum Build System Requirements for Python Projects">PEP 518</a>.</p>
|
||
</section>
|
||
<section id="drop-maintainers-to-unify-with-authors">
|
||
<h3><a class="toc-backref" href="#drop-maintainers-to-unify-with-authors" role="doc-backlink">Drop <code class="docutils literal notranslate"><span class="pre">maintainers</span></code> to unify with <code class="docutils literal notranslate"><span class="pre">authors</span></code></a></h3>
|
||
<p>As the difference between <code class="docutils literal notranslate"><span class="pre">Authors</span></code> and <code class="docutils literal notranslate"><span class="pre">Maintainers</span></code> fields in
|
||
the <a class="reference external" href="https://packaging.python.org/specifications/core-metadata/">core metadata</a> is unspecified and ambiguous, this PEP originally
|
||
proposed unifying them as a single <code class="docutils literal notranslate"><span class="pre">authors</span></code> field. Other ecosystems
|
||
have selected “author” as the term to use, so the thinking was to
|
||
standardize on <code class="docutils literal notranslate"><span class="pre">Author</span></code> in the core metadata as the place to list
|
||
people maintaining a project.</p>
|
||
<p>In the end, though, the decision to adhere to the core metadata was
|
||
deemed more important to help with the acceptance of this PEP,
|
||
rather than trying to introduce a new interpretation for some of the
|
||
core metadata.</p>
|
||
</section>
|
||
<section id="support-an-arbitrary-depth-of-tables-for-project-entry-points">
|
||
<h3><a class="toc-backref" href="#support-an-arbitrary-depth-of-tables-for-project-entry-points" role="doc-backlink">Support an arbitrary depth of tables for <code class="docutils literal notranslate"><span class="pre">project.entry-points</span></code></a></h3>
|
||
<p>There was a worry that keeping <code class="docutils literal notranslate"><span class="pre">project.entry-points</span></code> to a depth of 1 for sub-tables
|
||
would cause confusion to users if they use a dotted name and are not used to table
|
||
names using quotation marks (e.g. <code class="docutils literal notranslate"><span class="pre">project.entry-points."spam.magical"</span></code>). But
|
||
supporting an arbitrary depth – e.g. <code class="docutils literal notranslate"><span class="pre">project.entry-points.spam.magical</span></code> – would
|
||
preclude any form of an exploded table format in the future. It would also complicate
|
||
things for build back-ends as they would have to make sure to traverse the full
|
||
table structure rather than a single level and raising errors as appropriate on
|
||
value types.</p>
|
||
</section>
|
||
<section id="using-structured-toml-dictionaries-to-specify-dependencies">
|
||
<h3><a class="toc-backref" href="#using-structured-toml-dictionaries-to-specify-dependencies" role="doc-backlink">Using structured TOML dictionaries to specify dependencies</a></h3>
|
||
<p>The format for specifying the dependencies of a project was the most
|
||
hotly contested topic in terms of data format. It led to the creation
|
||
of both <a class="pep reference internal" href="../pep-0631/" title="PEP 631 – Dependency specification in pyproject.toml based on PEP 508">PEP 631</a> and <a class="pep reference internal" href="../pep-0633/" title="PEP 633 – Dependency specification in pyproject.toml using an exploded TOML table">PEP 633</a> which represent what is in this PEP
|
||
and using TOML dictionaries more extensively, respectively. The
|
||
decision on those PEPs can be found at
|
||
<a class="reference external" href="https://discuss.python.org/t/how-to-specify-dependencies-pep-508-strings-or-a-table-in-toml/5243/38">https://discuss.python.org/t/how-to-specify-dependencies-pep-508-strings-or-a-table-in-toml/5243/38</a>.</p>
|
||
<p>The authors briefly considered supporting both formats, but decided
|
||
that it would lead to confusion as people would need to be familiar
|
||
with two formats instead of just one.</p>
|
||
</section>
|
||
<section id="require-build-back-ends-to-update-pyproject-toml-when-generating-an-sdist">
|
||
<h3><a class="toc-backref" href="#require-build-back-ends-to-update-pyproject-toml-when-generating-an-sdist" role="doc-backlink">Require build back-ends to update <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> when generating an sdist</a></h3>
|
||
<p>When this PEP was written, sdists did not require having static,
|
||
canonical metadata like this PEP does. The idea was then considered to
|
||
use this PEP as a way to get such metadata into sdists. In the end,
|
||
though, the idea of updating <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> was not generally
|
||
liked, and so the idea was rejected in favour of separately pursuing
|
||
standardizing metadata in sdists.</p>
|
||
</section>
|
||
<section id="allow-tools-to-add-extend-data">
|
||
<h3><a class="toc-backref" href="#allow-tools-to-add-extend-data" role="doc-backlink">Allow tools to add/extend data</a></h3>
|
||
<p>In an earlier version of this PEP, tools were allowed to extend data
|
||
for fields. For instance, build back-ends could take the version
|
||
number and add a local version for when they built the wheel. Tools
|
||
could also add more trove classifiers for things like the license or
|
||
supported Python versions.</p>
|
||
<p>In the end, though, it was thought better to start out stricter and
|
||
contemplate loosening how static the data could be considered based
|
||
on real-world usage.</p>
|
||
</section>
|
||
</section>
|
||
<section id="open-issues">
|
||
<h2><a class="toc-backref" href="#open-issues" role="doc-backlink">Open Issues</a></h2>
|
||
<p>None at the moment.</p>
|
||
</section>
|
||
<section id="copyright">
|
||
<h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2>
|
||
<p>This document is placed in the public domain or under the
|
||
CC0-1.0-Universal license, whichever is more permissive.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0621.rst">https://github.com/python/peps/blob/main/peps/pep-0621.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0621.rst">2023-12-06 16:17:05 GMT</a></p>
|
||
|
||
</article>
|
||
<nav id="pep-sidebar">
|
||
<h2>Contents</h2>
|
||
<ul>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#rationale">Rationale</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#details">Details</a><ul>
|
||
<li><a class="reference internal" href="#table-name">Table name</a></li>
|
||
<li><a class="reference internal" href="#name"><code class="docutils literal notranslate"><span class="pre">name</span></code></a></li>
|
||
<li><a class="reference internal" href="#version"><code class="docutils literal notranslate"><span class="pre">version</span></code></a></li>
|
||
<li><a class="reference internal" href="#description"><code class="docutils literal notranslate"><span class="pre">description</span></code></a></li>
|
||
<li><a class="reference internal" href="#readme"><code class="docutils literal notranslate"><span class="pre">readme</span></code></a></li>
|
||
<li><a class="reference internal" href="#requires-python"><code class="docutils literal notranslate"><span class="pre">requires-python</span></code></a></li>
|
||
<li><a class="reference internal" href="#license"><code class="docutils literal notranslate"><span class="pre">license</span></code></a></li>
|
||
<li><a class="reference internal" href="#authors-maintainers"><code class="docutils literal notranslate"><span class="pre">authors</span></code>/<code class="docutils literal notranslate"><span class="pre">maintainers</span></code></a></li>
|
||
<li><a class="reference internal" href="#keywords"><code class="docutils literal notranslate"><span class="pre">keywords</span></code></a></li>
|
||
<li><a class="reference internal" href="#classifiers"><code class="docutils literal notranslate"><span class="pre">classifiers</span></code></a></li>
|
||
<li><a class="reference internal" href="#urls"><code class="docutils literal notranslate"><span class="pre">urls</span></code></a></li>
|
||
<li><a class="reference internal" href="#entry-points">Entry points</a></li>
|
||
<li><a class="reference internal" href="#dependencies-optional-dependencies"><code class="docutils literal notranslate"><span class="pre">dependencies</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code></a></li>
|
||
<li><a class="reference internal" href="#dynamic"><code class="docutils literal notranslate"><span class="pre">dynamic</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#example">Example</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li>
|
||
<li><a class="reference internal" href="#security-implications">Security Implications</a></li>
|
||
<li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li>
|
||
<li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul>
|
||
<li><a class="reference internal" href="#other-table-names">Other table names</a><ul>
|
||
<li><a class="reference internal" href="#anything-under-build-system">Anything under <code class="docutils literal notranslate"><span class="pre">[build-system]</span></code></a></li>
|
||
<li><a class="reference internal" href="#package"><code class="docutils literal notranslate"><span class="pre">[package]</span></code></a></li>
|
||
<li><a class="reference internal" href="#metadata"><code class="docutils literal notranslate"><span class="pre">[metadata]</span></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#support-for-a-metadata-provider">Support for a metadata provider</a></li>
|
||
<li><a class="reference internal" href="#require-a-normalized-project-name">Require a normalized project name</a></li>
|
||
<li><a class="reference internal" href="#specify-files-to-include-when-building">Specify files to include when building</a></li>
|
||
<li><a class="reference internal" href="#name-the-project-urls-table-project-project-urls">Name the <code class="docutils literal notranslate"><span class="pre">[project.urls]</span></code> table <code class="docutils literal notranslate"><span class="pre">[project.project-urls]</span></code></a></li>
|
||
<li><a class="reference internal" href="#have-a-separate-url-home-page-field">Have a separate <code class="docutils literal notranslate"><span class="pre">url</span></code>/<code class="docutils literal notranslate"><span class="pre">home-page</span></code> field</a></li>
|
||
<li><a class="reference internal" href="#recommend-that-tools-put-development-related-dependencies-into-a-dev-extra">Recommend that tools put development-related dependencies into a “dev” extra</a></li>
|
||
<li><a class="reference internal" href="#have-the-dynamic-field-only-require-specifying-missing-required-fields">Have the <code class="docutils literal notranslate"><span class="pre">dynamic</span></code> field only require specifying missing required fields</a></li>
|
||
<li><a class="reference internal" href="#different-structures-for-the-readme-field">Different structures for the <code class="docutils literal notranslate"><span class="pre">readme</span></code> field</a></li>
|
||
<li><a class="reference internal" href="#allowing-the-readme-field-to-imply-text-plain">Allowing the <code class="docutils literal notranslate"><span class="pre">readme</span></code> field to imply <code class="docutils literal notranslate"><span class="pre">text/plain</span></code></a></li>
|
||
<li><a class="reference internal" href="#other-names-for-dependencies-optional-dependencies">Other names for <code class="docutils literal notranslate"><span class="pre">dependencies</span></code>/<code class="docutils literal notranslate"><span class="pre">optional-dependencies</span></code></a></li>
|
||
<li><a class="reference internal" href="#drop-maintainers-to-unify-with-authors">Drop <code class="docutils literal notranslate"><span class="pre">maintainers</span></code> to unify with <code class="docutils literal notranslate"><span class="pre">authors</span></code></a></li>
|
||
<li><a class="reference internal" href="#support-an-arbitrary-depth-of-tables-for-project-entry-points">Support an arbitrary depth of tables for <code class="docutils literal notranslate"><span class="pre">project.entry-points</span></code></a></li>
|
||
<li><a class="reference internal" href="#using-structured-toml-dictionaries-to-specify-dependencies">Using structured TOML dictionaries to specify dependencies</a></li>
|
||
<li><a class="reference internal" href="#require-build-back-ends-to-update-pyproject-toml-when-generating-an-sdist">Require build back-ends to update <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> when generating an sdist</a></li>
|
||
<li><a class="reference internal" href="#allow-tools-to-add-extend-data">Allow tools to add/extend data</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#open-issues">Open Issues</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
|
||
<br>
|
||
<a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0621.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> |