PEP 633 – Dependency specification in pyproject.toml using an exploded TOML table

<!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 633 – Dependency specification in pyproject.toml using an exploded TOML table | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0633/"> <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 633 – Dependency specification in pyproject.toml using an exploded TOML table | peps.python.org'> <meta property="og:description" content="This PEP specifies how to write a project’s dependencies in a pyproject.toml file for packaging-related tools to consume using the fields defined in PEP 621, as an alternative to the PEP 508-based approach defined in PEP 631."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0633/"> <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 dependencies in a pyproject.toml file for packaging-related tools to consume using the fields defined in PEP 621, as an alternative to the PEP 508-based approach defined in PEP 631."> <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 633</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> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 633 – Dependency specification in pyproject.toml using an exploded TOML table</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Laurie Opperman <laurie_opperman at hotmail.com>, Arun Babu Neelicattu <arun.neelicattu at gmail.com></dd> <dt class="field-even">Sponsor:</dt> <dd class="field-even">Brett Cannon <brett at python.org></dd> <dt class="field-odd">Discussions-To:</dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/dependency-specification-in-pyproject-toml-using-an-exploded-toml-table/5123/">Discourse thread</a></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Formally declined and will not be accepted">Rejected</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Topic:</dt> <dd class="field-even"><a class="reference external" href="../topic/packaging/">Packaging</a></dd> <dt class="field-odd">Created:</dt> <dd class="field-odd">02-Sep-2020</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even">02-Sep-2020</dd> <dt class="field-odd">Resolution:</dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/how-to-specify-dependencies-pep-508-strings-or-a-table-in-toml/5243/38">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="#rejection-notice">Rejection Notice</a></li> <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="#dependencies"><code class="docutils literal notranslate">dependencies</code></a><ul> <li><a class="reference internal" href="#requirement-table">Requirement table</a></li> </ul> </li> <li><a class="reference internal" href="#optional-dependencies"><code class="docutils literal notranslate">optional-dependencies</code></a></li> </ul> </li> <li><a class="reference internal" href="#reference-implementation">Reference implementation</a><ul> <li><a class="reference internal" href="#id1">JSON schema</a></li> </ul> </li> <li><a class="reference internal" href="#examples">Examples</a></li> <li><a class="reference internal" href="#compatibility-examples">Compatibility Examples</a><ul> <li><a class="reference internal" href="#version-constrained-dependencies">Version Constrained Dependencies</a></li> <li><a class="reference internal" href="#direct-reference-dependencies">Direct Reference Dependencies</a></li> <li><a class="reference internal" href="#environment-markers">Environment Markers</a></li> <li><a class="reference internal" href="#package-extras">Package Extras</a></li> <li><a class="reference internal" href="#complex-examples">Complex Examples</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#switch-to-an-array-for-dependencies">Switch to an array for <code class="docutils literal notranslate">dependencies</code></a></li> <li><a class="reference internal" href="#replace-optional-dependencies-with-extras">Replace <code class="docutils literal notranslate">optional-dependencies</code> with <code class="docutils literal notranslate">extras</code></a></li> <li><a class="reference internal" href="#direct-table-in-requirement"><code class="docutils literal notranslate">direct</code> table in requirement</a></li> <li><a class="reference internal" href="#include-hash">Include hash</a></li> <li><a class="reference internal" href="#dependency-tables-for-each-extra">Dependency tables for each extra</a></li> <li><a class="reference internal" href="#environment-marker-keys">Environment marker keys</a></li> <li><a class="reference internal" href="#multiple-extras-which-one-requirement-can-satisfy">Multiple extras which one requirement can satisfy</a></li> </ul> </li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="rejection-notice"> <h2><a class="toc-backref" href="#rejection-notice" role="doc-backlink">Rejection Notice</a></h2> This PEP has been rejected in favour of <a class="pep reference internal" href="../pep-0631/" title="PEP 631 – Dependency specification in pyproject.toml based on PEP 508">PEP 631</a> due to its popularity, consistency with the existing usage of <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> strings, and compatibility with existing packaging tool suites. </section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP specifies how to write a project’s dependencies in a <code class="docutils literal notranslate">pyproject.toml</code> file for packaging-related tools to consume using the fields defined in <a class="pep reference internal" href="../pep-0621/" title="PEP 621 – Storing project metadata in pyproject.toml">PEP 621</a>, as an alternative to the <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>-based approach defined in <a class="pep reference internal" href="../pep-0631/" title="PEP 631 – Dependency specification in pyproject.toml based on PEP 508">PEP 631</a>. </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> There are multiple benefits to using TOML tables and other data-types to represent requirements rather than <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> strings: <ul class="simple"> <li>Easy initial validation via the TOML syntax.</li> <li>Easy secondary validation using a schema, for example a <a class="reference external" href="https://json-schema.org/">JSON Schema</a>.</li> <li>Potential for users to guess the keys of given features, rather than memorising a syntax.</li> <li>Users of multiple other popular languages may already be familiar with the TOML syntax.</li> <li>TOML directly represents the same data structures as in JSON, and therefore a sub-set of Python literals, so users can understand the hierarchy and type of value</li> </ul> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> Most of this is taken from discussions in the <a class="reference external" href="https://discuss.python.org/t/pep-621-how-to-specify-dependencies/4599">PEP 621 dependencies topic</a>. This has elements from <a class="reference external" href="https://github.com/pypa/pipfile">Pipfile</a>, <a class="reference external" href="https://python-poetry.org/docs/dependency-specification/">Poetry</a>, <a class="reference external" href="https://dart.dev/tools/pub/dependencies">Dart’s dependencies</a> and <a class="reference external" href="https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html">Rust’s Cargo</a>. A <a class="reference external" href="https://github.com/uranusjr/packaging-metadata-comparisons/blob/master/topics/dependency-entries.md">comparison document</a> shows advantages and disadvantages between this format and <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>-style specifiers. In the specification of multiple requirements with the same distribution name (where environment markers choose the appropriate dependency), the chosen solution is similar to <a class="reference external" href="https://python-poetry.org/docs/dependency-specification/">Poetry</a>’s, where an array of requirements is allowed. The direct-reference keys closely align with and utilise <a class="pep reference internal" href="../pep-0610/" title="PEP 610 – Recording the Direct URL Origin of installed distributions">PEP 610</a> and <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> as to reduce differences in the packaging ecosystem and rely on previous work in specification. </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> As in <a class="pep reference internal" href="../pep-0621/" title="PEP 621 – Storing project metadata in pyproject.toml">PEP 621</a>, if metadata is improperly specified then tools MUST raise an error. The metadata MUST conform to the <a class="reference external" href="https://toml.io/">TOML</a> specification. To reduce confusion with this document being a specification for specifying dependencies, the word “requirement” is used to mean a <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> dependency specification. The following tables are added to the <code class="docutils literal notranslate">project</code> table specified in <a class="pep reference internal" href="../pep-0621/" title="PEP 621 – Storing project metadata in pyproject.toml">PEP 621</a>. <section id="dependencies"> <h3><a class="toc-backref" href="#dependencies" role="doc-backlink"><code class="docutils literal notranslate">dependencies</code></a></h3> Format: table The keys inside this table are the names of the required distribution. The values can have one of the following types: <ul class="simple"> <li>string: the requirement is defined only by a version requirement, with same specification as <code class="docutils literal notranslate">version</code> in the requirement table, except allowing the empty string <code class="docutils literal notranslate">""</code> to place no restriction on the version.</li> <li>table: a requirement table.</li> <li>array: an array of requirement tables. It is an error to specify an empty array <code class="docutils literal notranslate">[]</code> as a value.</li> </ul> <section id="requirement-table"> <h4><a class="toc-backref" href="#requirement-table" role="doc-backlink">Requirement table</a></h4> The keys of the requirement table are as follows (all are optional): <ul class="simple"> <li><code class="docutils literal notranslate">version</code> (string): a <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a> version specifier, which is a comma-delimited list of version specifier clauses. The string MUST be non-empty.</li> <li><code class="docutils literal notranslate">extras</code> (array of strings): a list of <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> extras declarations for the distribution. The list MUST be non-empty.</li> <li><code class="docutils literal notranslate">markers</code> (string): a <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> environment marker expression. The string MUST be non-empty.</li> <li><code class="docutils literal notranslate">url</code> (string): the URL of the artifact to install and satisfy the requirement. Note that <code class="docutils literal notranslate">file://</code> is the prefix used for packages to be retrieved from the local filesystem.</li> <li><code class="docutils literal notranslate">git</code>, <code class="docutils literal notranslate">hg</code>, <code class="docutils literal notranslate">bzr</code> or <code class="docutils literal notranslate">svn</code> (string): the URL of a VCS repository (as specified in <a class="pep reference internal" href="../pep-0440/" title="PEP 440 – Version Identification and Dependency Specification">PEP 440</a>) to clone, whose tree will be installed to satisfy the requirement. Further VCS keys will be added via amendments to <a class="pep reference internal" href="../pep-0610/" title="PEP 610 – Recording the Direct URL Origin of installed distributions">PEP 610</a>, however tools MAY opt to support other VCS’s using their command-line command prior to the acceptance of the amendment.</li> <li><code class="docutils literal notranslate">revision</code> (string): the identifier for a specific revision of the specified VCS repository to check-out before installation. Users MUST only provide this when one of <code class="docutils literal notranslate">git</code>, <code class="docutils literal notranslate">hg</code>, <code class="docutils literal notranslate">bzr</code>, <code class="docutils literal notranslate">svn</code>, or another VCS key is used to identify the distribution to install. Revision identifiers are suggested in <a class="pep reference internal" href="../pep-0610/" title="PEP 610 – Recording the Direct URL Origin of installed distributions">PEP 610</a>.</li> </ul> At most one of the following keys can be specified simultaneously, as they logically conflict with each other in the requirement: <code class="docutils literal notranslate">version</code>, <code class="docutils literal notranslate">url</code>, <code class="docutils literal notranslate">git</code>, <code class="docutils literal notranslate">hg</code>, <code class="docutils literal notranslate">bzr</code>, <code class="docutils literal notranslate">svn</code>, and any other VCS key. An empty requirement table <code class="docutils literal notranslate">{}</code> places no restriction on the requirement, in addition to the empty string <code class="docutils literal notranslate">""</code>. Any keys provided which are not specified in this document MUST cause an error in parsing. </section> </section> <section id="optional-dependencies"> <h3><a class="toc-backref" href="#optional-dependencies" role="doc-backlink"><code class="docutils literal notranslate">optional-dependencies</code></a></h3> Format: table The keys inside this table are the names of an extra’s required distribution. The values can have one of the following types: <ul class="simple"> <li>table: a requirement table.</li> <li>array: an array of requirement tables.</li> </ul> These requirement tables have <a class="reference internal" href="#requirement-table">the same specification as above</a>, with the addition of the following required key: <ul class="simple"> <li><code class="docutils literal notranslate">for-extra</code> (string): the name of the <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> extra that this requirement is required for.</li> </ul> </section> </section> <section id="reference-implementation"> <h2><a class="toc-backref" href="#reference-implementation" role="doc-backlink">Reference implementation</a></h2> Tools will need to convert this format to <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> requirement strings. Below is an example implementation of that conversion (assuming validation is already performed): <div class="highlight-default notranslate"><div class="highlight"><pre>def convert_requirement_to_pep508(name, requirement): if isinstance(requirement, str): requirement = {"version": requirement} pep508 = name if "extras" in requirement: pep508 += " [" + ", ".join(requirement["extras"]) + "]" if "version" in requirement: pep508 += " " + requirement["version"] if "url" in requirement: pep508 += " @ " + requirement["url"] for vcs in ("git", "hg", "bzr", "svn"): if vcs in requirement: pep508 += " @ " + vcs + "+" + requirement[vcs] if "revision" in requirement: pep508 += "@" + requirement["revision"] extra = None if "for-extra" in requirement: extra = requirement["for-extra"] if "markers" in requirement: markers = requirement["markers"] if extra: markers = "extra = '" + extra + "' and (" + markers + ")" pep508 += "; " + markers return pep508, extra def convert_requirements_to_pep508(dependencies): pep508s = [] extras = set() for name, req in dependencies.items(): if isinstance(req, list): for sub_req in req: pep508, extra = convert_requirement_to_pep508(name, sub_req) pep508s.append(pep508) if extra: extras.add(extra) else: pep508, extra = convert_requirement_to_pep508(name, req) pep508s.append(pep508) if extra: extras.add(extra) return pep508s, extras def convert_project_requirements_to_pep508(project): reqs, _ = convert_requirements_to_pep508(project.get("dependencies", {})) optional_reqs, extras = convert_requirements_to_pep508( project.get("optional-dependencies", {}) ) reqs += optional_reqs return reqs, extras </pre></div> </div> <section id="id1"> <h3><a class="toc-backref" href="#id1" role="doc-backlink">JSON schema</a></h3> For initial validation, a JSON-schema can be used. Not only does this help tools have a consistent validation, but it allows code editors to highlight validation errors as users are building the dependencies list. <div class="highlight-default notranslate"><div class="highlight"><pre>{ "$id": "spam", "$schema": "http://json-schema.org/draft-07/schema#", "title": "Project metadata", "type": "object", "definitions": { "requirementTable": { "title": "Full project dependency specification", "type": "object", "properties": { "extras": { "title": "Dependency extras", "type": "array", "items": { "title": "Dependency extra", "type": "string" } }, "markers": { "title": "Dependency environment markers", "type": "string" } }, "propertyNames": { "enum": [ "extras", "markers", "version", "url", "git", "hg", "bzr", "svn", "for-extra" ] }, "oneOf": [ { "title": "Version requirement", "properties": { "version": { "title": "Version", "type": "string" } } }, { "title": "URL requirement", "properties": { "url": { "title": "URL", "type": "string", "format": "uri" } }, "required": [ "url" ] }, { "title": "VCS requirement", "properties": { "revision": { "title": "VCS repository revision", "type": "string" } }, "oneOf": [ { "title": "Git repository", "properties": { "git": { "title": "Git URL", "type": "string", "format": "uri" } }, "required": [ "git" ] }, { "title": "Mercurial repository", "properties": { "hg": { "title": "Mercurial URL", "type": "string", "format": "uri" } }, "required": [ "hg" ] }, { "title": "Bazaar repository", "properties": { "bzr": { "title": "Bazaar URL", "type": "string", "format": "uri" } }, "required": [ "bzr" ] }, { "title": "Subversion repository", "properties": { "svn": { "title": "Subversion URL", "type": "string", "format": "uri" } }, "required": [ "svn" ] } ] } ] }, "requirementVersion": { "title": "Version project dependency specification", "type": "string" }, "requirement": { "title": "Project dependency specification", "oneOf": [ { "$ref": "#/definitions/requirementVersion" }, { "$ref": "#/definitions/requirementTable" }, { "title": "Multiple specifications", "type": "array", "items": { "$ref": "#/definitions/requirementTable" }, "minLength": 1 } ] }, "optionalRequirementTable": { "title": "Project optional dependency specification table", "allOf": [ { "$ref": "#/definitions/requirementTable" }, { "properties": { "for-extra": { "title": "Dependency's extra", "type": "string" } }, "required": [ "for-extra" ] } ] }, "optionalRequirement": { "title": "Project optional dependency specification", "oneOf": [ { "$ref": "#/definitions/optionalRequirementTable" }, { "title": "Multiple specifications", "type": "array", "items": { "$ref": "#/definitions/optionalRequirementTable" }, "minLength": 1 } ] } }, "properties": { "dependencies": { "title": "Project dependencies", "type": "object", "additionalProperties": { "$ref": "#/definitions/requirement" } }, "optional-dependencies": { "title": "Project dependencies", "type": "object", "additionalProperties": { "$ref": "#/definitions/optionalRequirement" } } } } </pre></div> </div> </section> </section> <section id="examples"> <h2><a class="toc-backref" href="#examples" role="doc-backlink">Examples</a></h2> Full artificial example: <div class="highlight-default notranslate"><div class="highlight"><pre>[project.dependencies] flask = { } django = { } requests = { version = ">= 2.8.1, == 2.8.*", extras = ["security", "tests"], markers = "python_version < '2.7'" } pip = { url = "https://github.com/pypa/pip/archive/1.3.1.zip" } sphinx = { git = "ssh://git@github.com/sphinx-doc/sphinx.git" } numpy = "~=1.18" pytest = [ { version = "<6", markers = "python_version < '3.5'" }, { version = ">=6", markers = "python_version >= '3.5'" }, ] [project.optional-dependencies] pytest-timout = { for-extra = "dev" } pytest-mock = [ { version = "<6", markers = "python_version < '3.5'", for-extra = "dev" }, { version = ">=6", markers = "python_version >= '3.5'", for-extra = "dev" }, ] </pre></div> </div> In homage to <a class="pep reference internal" href="../pep-0631/" title="PEP 631 – Dependency specification in pyproject.toml based on PEP 508">PEP 631</a>, the following is an equivalent dependencies specification for <a class="reference external" href="https://github.com/docker/compose/blob/789bfb0e8b2e61f15f423d371508b698c64b057f/setup.py#L28-L61">docker-compose</a>: <div class="highlight-default notranslate"><div class="highlight"><pre>[project.dependencies] cached-property = ">= 1.2.0, < 2" distro = ">= 1.2.0, < 2" docker = { extras = ["ssh"], version = ">= 4.2.2, < 5" } docopt = ">= 0.6.1, < 1" jsonschema = ">= 2.5.1, < 4" PyYAML = ">= 3.10, < 6" python-dotenv = ">= 0.13.0, < 1" requests = ">= 2.20.0, < 3" texttable = ">= 0.9.0, < 2" websocket-client = ">= 0.32.0, < 1" # Conditional "backports.shutil_get_terminal_size" = { version = "== 1.0.0", markers = "python_version < '3.3'" } "backports.ssl_match_hostname" = { version = ">= 3.5, < 4", markers = "python_version < '3.5'" } colorama = { version = ">= 0.4, < 1", markers = "sys_platform == 'win32'" } enum34 = { version = ">= 1.0.4, < 2", markers = "python_version < '3.4'" } ipaddress = { version = ">= 1.0.16, < 2", markers = "python_version < '3.3'" } subprocess32 = { version = ">= 3.5.4, < 4", markers = "python_version < '3.2'" } [project.optional-dependencies] PySocks = { version = ">= 1.5.6, != 1.5.7, < 2", for-extra = "socks" } ddt = { version = ">= 1.2.2, < 2", for-extra = "tests" } pytest = { version = "< 6", for-extra = "tests" } mock = { version = ">= 1.0.1, < 4", markers = "python_version < '3.4'", for-extra = "tests" } </pre></div> </div> </section> <section id="compatibility-examples"> <h2><a class="toc-backref" href="#compatibility-examples" role="doc-backlink">Compatibility Examples</a></h2> The authors of this PEP recognise that various tools need to both read from and write to this format for dependency specification. This section aims to provide direct comparison with and examples for translating to/from the currently used standard, <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a>. <div class="admonition note"> Note For simplicity and clarity, various ways in which TOML allows you to specify each specification is not represented. These examples use the standard inline representation. For example, while following are considered equivalent in TOML, we choose the second form for the examples in this section. <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp.version = "== 3.6.2" aiohttp = { version = "== 3.6.2" } </pre></div> </div> </div> <section id="version-constrained-dependencies"> <h3><a class="toc-backref" href="#version-constrained-dependencies" role="doc-backlink">Version Constrained Dependencies</a></h3> No Version Constraint <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp = {} </pre></div> </div> Simple Version Constraint <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp >= 3.6.2, < 4.0.0 </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp = { version = ">= 3.6.2, < 4.0.0" } </pre></div> </div> <div class="admonition note"> Note This can, for conciseness, be also represented as a string. <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp = ">= 3.6.2, < 4.0.0" </pre></div> </div> </div> </section> <section id="direct-reference-dependencies"> <h3><a class="toc-backref" href="#direct-reference-dependencies" role="doc-backlink">Direct Reference Dependencies</a></h3> URL Dependency <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp @ https://files.pythonhosted.org/packages/97/d1/1cc7a1f84097d7abdc6c09ee8d2260366f081f8e82da36ebb22a25cdda9f/aiohttp-3.6.2-cp35-cp35m-macosx_10_13_x86_64.whl </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp = { url = "https://files.pythonhosted.org/packages/97/d1/1cc7a1f84097d7abdc6c09ee8d2260366f081f8e82da36ebb22a25cdda9f/aiohttp-3.6.2-cp35-cp35m-macosx_10_13_x86_64.whl" } </pre></div> </div> VCS Dependency <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp @ git+ssh://git@github.com/aio-libs/aiohttp.git@master </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp = { git = "ssh://git@github.com/aio-libs/aiohttp.git", revision = "master" } </pre></div> </div> </section> <section id="environment-markers"> <h3><a class="toc-backref" href="#environment-markers" role="doc-backlink">Environment Markers</a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp >= 3.6.1; python_version >= '3.8' </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp = { version = ">= 3.6.1", markers = "python_version >= '3.8'" } </pre></div> </div> A slightly extended example of the above, where a particular version of <code class="docutils literal notranslate">aiohttp</code> is required based on the interpreter version. <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp >= 3.6.1; python_version >= '3.8' aiohttp >= 3.0.0, < 3.6.1; python_version < '3.8' </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp = [ { version = ">= 3.6.1", markers = "python_version >= '3.8'" }, { version = ">= 3.0.0, < 3.6.1", markers = "python_version < '3.8'" } ] </pre></div> </div> </section> <section id="package-extras"> <h3><a class="toc-backref" href="#package-extras" role="doc-backlink">Package Extras</a></h3> Specifying dependency for a package extra <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp >= 3.6.2; extra == 'http' </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp = { version = ">= 3.6.2", for-extra = "http" } </pre></div> </div> Using extras from a dependency <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp [speedups] >= 3.6.2 </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp = { version = ">= 3.6.2", extras = ["speedups"] } </pre></div> </div> </section> <section id="complex-examples"> <h3><a class="toc-backref" href="#complex-examples" role="doc-backlink">Complex Examples</a></h3> Version Constraint <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp [speedups] >= 3.6.2; python_version >= '3.8' and extra == 'http' </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp = { version = ">= 3.6.2", extras = ["speedups"], markers = "python_version >= '3.8'", for-extra = "http" } </pre></div> </div> Direct Reference (VCS) <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp [speedups] @ git+ssh://git@github.com/aio-libs/aiohttp.git@master ; python_version >= '3.8' and extra == 'http' </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre>aiohttp = { git = "ssh://git@github.com/aio-libs/aiohttp.git", revision = "master", extras = ["speedups"], markers = "python_version >= '3.8'", for-extra = "http" } </pre></div> </div> </section> </section> <section id="rejected-ideas"> <h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2> <section id="switch-to-an-array-for-dependencies"> <h3><a class="toc-backref" href="#switch-to-an-array-for-dependencies" role="doc-backlink">Switch to an array for <code class="docutils literal notranslate">dependencies</code></a></h3> Use an array instead of a table in order to have each element only be a table (with a <code class="docutils literal notranslate">name</code> key) and no arrays of requirement tables. This was very verbose and restrictive in the TOML format, and having multiple requirements for a given distribution isn’t very common. </section> <section id="replace-optional-dependencies-with-extras"> <h3><a class="toc-backref" href="#replace-optional-dependencies-with-extras" role="doc-backlink">Replace <code class="docutils literal notranslate">optional-dependencies</code> with <code class="docutils literal notranslate">extras</code></a></h3> Remove the <code class="docutils literal notranslate">optional-dependencies</code> table in favour of both including an <code class="docutils literal notranslate">optional</code> key in the requirement and an <code class="docutils literal notranslate">extras</code> table which specifies which (optional) requirements are needed for a project’s extra. This reduces the number of table with the same specification (to 1) and allows for requirements to be specified once but used in multiple extras, but distances some of the requirement’s properties (which extra(s) it belongs to), groups required and optional dependencies together (possibly mixed), and there may not be a simple way to choose a requirement when a distribution has multiple requirements. This was rejected as <code class="docutils literal notranslate">optional-dependencies</code> has already been used in the <a class="pep reference internal" href="../pep-0621/" title="PEP 621 – Storing project metadata in pyproject.toml">PEP 621</a> draft. </section> <section id="direct-table-in-requirement"> <h3><a class="toc-backref" href="#direct-table-in-requirement" role="doc-backlink"><code class="docutils literal notranslate">direct</code> table in requirement</a></h3> Include the direct-reference keys in a <code class="docutils literal notranslate">direct</code> table, have the VCS specified as the value of a <code class="docutils literal notranslate">vcs</code> key. This was more explicit and easier to include in a JSON-schema validation, but was decided to be too verbose and not as readable. </section> <section id="include-hash"> <h3><a class="toc-backref" href="#include-hash" role="doc-backlink">Include hash</a></h3> Include hash in direct-reference requirements. This was only for package lock-files, and didn’t really have a place in the project’s metadata. </section> <section id="dependency-tables-for-each-extra"> <h3><a class="toc-backref" href="#dependency-tables-for-each-extra" role="doc-backlink">Dependency tables for each extra</a></h3> Have the <code class="docutils literal notranslate">optional-dependencies</code> be a table of dependency tables for each extra, with the table name being the extra’s name. This made <code class="docutils literal notranslate">optional-dependencies</code> a different type (table of tables of requirements) from <code class="docutils literal notranslate">dependencies</code> (table of requirements), which could be jarring for users and harder to parse. </section> <section id="environment-marker-keys"> <h3><a class="toc-backref" href="#environment-marker-keys" role="doc-backlink">Environment marker keys</a></h3> Make each <a class="pep reference internal" href="../pep-0508/" title="PEP 508 – Dependency specification for Python Software Packages">PEP 508</a> environment marker as a key (or child-table key) in the requirement. This arguably increases readability and ease of parsing. The <code class="docutils literal notranslate">markers</code> key would still be allowed for more advanced specification, with which the key-specified environment markers are <code class="docutils literal notranslate">and</code>’d with the result of. This was deferred as more design needs to be undertaken. </section> <section id="multiple-extras-which-one-requirement-can-satisfy"> <h3><a class="toc-backref" href="#multiple-extras-which-one-requirement-can-satisfy" role="doc-backlink">Multiple extras which one requirement can satisfy</a></h3> Replace the <code class="docutils literal notranslate">for-extra</code> key with <code class="docutils literal notranslate">for-extras</code>, with the value being an array of extras which the requirement satisfies. This reduces some duplication, but in this case that duplication makes explicit which extras have which dependencies. </section> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0633.rst">https://github.com/python/peps/blob/main/peps/pep-0633.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0633.rst">2025-02-01 08:55:40 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#rejection-notice">Rejection Notice</a></li> <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="#dependencies"><code class="docutils literal notranslate">dependencies</code></a><ul> <li><a class="reference internal" href="#requirement-table">Requirement table</a></li> </ul> </li> <li><a class="reference internal" href="#optional-dependencies"><code class="docutils literal notranslate">optional-dependencies</code></a></li> </ul> </li> <li><a class="reference internal" href="#reference-implementation">Reference implementation</a><ul> <li><a class="reference internal" href="#id1">JSON schema</a></li> </ul> </li> <li><a class="reference internal" href="#examples">Examples</a></li> <li><a class="reference internal" href="#compatibility-examples">Compatibility Examples</a><ul> <li><a class="reference internal" href="#version-constrained-dependencies">Version Constrained Dependencies</a></li> <li><a class="reference internal" href="#direct-reference-dependencies">Direct Reference Dependencies</a></li> <li><a class="reference internal" href="#environment-markers">Environment Markers</a></li> <li><a class="reference internal" href="#package-extras">Package Extras</a></li> <li><a class="reference internal" href="#complex-examples">Complex Examples</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#switch-to-an-array-for-dependencies">Switch to an array for <code class="docutils literal notranslate">dependencies</code></a></li> <li><a class="reference internal" href="#replace-optional-dependencies-with-extras">Replace <code class="docutils literal notranslate">optional-dependencies</code> with <code class="docutils literal notranslate">extras</code></a></li> <li><a class="reference internal" href="#direct-table-in-requirement"><code class="docutils literal notranslate">direct</code> table in requirement</a></li> <li><a class="reference internal" href="#include-hash">Include hash</a></li> <li><a class="reference internal" href="#dependency-tables-for-each-extra">Dependency tables for each extra</a></li> <li><a class="reference internal" href="#environment-marker-keys">Environment marker keys</a></li> <li><a class="reference internal" href="#multiple-extras-which-one-requirement-can-satisfy">Multiple extras which one requirement can satisfy</a></li> </ul> </li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0633.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>

CINXE.COM

PEP 633 – Dependency specification in pyproject.toml using an exploded TOML table | peps.python.org