CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 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>