PEP 621 & 631: pull in details from PEP 631 into PEP 621 (#1647)

Along the way, update PEP 631 as accepted and add a note about it contributing to PEP 621.

pep-0621.rst

@@ -3,7 +3,6 @@ Title: Storing project metadata in pyproject.toml
 Author: Brett Cannon <brett@python.org>,
         Dustin Ingram <di@python.org>,
         Paul Ganssle <paul at ganssle.io>,
-        Paul Moore <p.f.moore@gmail.com>,
         Pradyun Gedam <pradyunsg@gmail.com>,
         Sébastien Eustace <sebastien@eustace.io>,
         Thomas Kluyver <thomas@kluyver.me.uk>,
@@ -377,9 +376,12 @@ be ambiguous in the face of ``[project.scripts]`` and
 
 ``dependencies``/``optional-dependencies``
 ''''''''''''''''''''''''''''''''''''''''''
-- Format: TBD
+- Format: Array of :pep:`508` strings (``dependencies``) and a table
-- `Core metadata`_: ``Requires-Dist``
+  with values of arrays of :pep:`508` strings
-  (`link <https://packaging.python.org/specifications/core-metadata/#requires-dist-multiple-use>`__)
+  (``optional-dependencies``)
+- `Core metadata`_: ``Requires-Dist`` and ``Provides-Extra``
+  (`link <https://packaging.python.org/specifications/core-metadata/#requires-dist-multiple-use>`__,
+  `link <https://packaging.python.org/specifications/core-metadata/#provides-extra-multiple-use>`__)
 - Synonyms
 
   - Flit_: ``requires`` for required dependencies, ``requires-extra``
@@ -393,8 +395,19 @@ be ambiguous in the face of ``[project.scripts]`` and
     ``extras_require`` for optional dependencies
     (`link <https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata>`__)
 
-See the open issue on `How to specify dependencies?`_ for a
+The (optional) dependencies of the project.
-discussion of the options of how to specify a project's dependencies.
+
+For ``dependencies``, 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 :pep:`508` string. Each string maps directly to
+a ``Requires-Dist`` entry in the `core metadata`_.
+
+For ``optional-dependencies``, 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 :pep:`508` strings. The keys MUST be valid values
+for the ``Provides-Extra`` `core metadata`_. Each value in the array
+thus becomes a corresponding ``Requires-Dist`` entry for the matching
+``Provides-Extra`` metadata.
 
 ``dynamic``
 '''''''''''
@@ -454,9 +467,18 @@ Example
     "Programming Language :: Python"
   ]
 
-  # Using 'dependencies' and 'optional-dependencies' as an example
+  dependencies = [
-  # as those fields' format are an Open Issue.
+    "httpx",
-  dynamic = ["dependencies", "optional-dependencies"]
+    "gidgethub[httpx]>4.0.0",
+    "django>2.1; os_name != 'nt'",
+    "django>2.0; os_name == 'nt'"
+  ]
+
+  [project.optional-dependencies]
+  test = [
+    "pytest < 5.0.0",
+    "pytest-cov[all]"
+  ]
 
   [project.urls]
   homepage = "example.com"
@@ -652,44 +674,24 @@ Originally this PEP said that tools SHOULD backfill appropriate trove classifier
 This was changed to say it MAY occur to emphasize it was entirely optional for
 build back-ends to implement.
 
-Open Issues
+Using structured TOML dictionaries to specify dependencies
-===========
+----------------------------------------------------------
-
+The format for specifying the dependencies of a project was the most
-How to specify dependencies?
+hotly contested topic in terms of data format. It led to the creation
-----------------------------
+of both :pep:`631` and :pep:`633` which represent what is in this PEP
-People seem to fall into two camps on how to specify dependencies:
+and using TOML dictionaries more extensively, respectively. The
-using :pep:`508` strings or TOML tables (sometimes referred to as the
+decision on those PEPs can be found at
-"exploded table" format due to it being the equivalent of translating
+https://discuss.python.org/t/how-to-specify-dependencies-pep-508-strings-or-a-table-in-toml/5243/38.
-a :pep:`508` string into a table format). There is no question as to
-whether one format or another can fully represent what the other can.
-This very much comes down to a question of familiarity and (perceived)
-ease of use.
-
-Supporters of :pep:`508` strings believe familiarity is important as
-the format has been in use for 5 years and in some variant for 15
-years (since the introduction of :pep:`345`). This would facilitate
-transitioning people to using this PEP as there would be one less new
-concept to learn. Supporters also think the format is reasonably
-ergonomic and understandable upon first glance, so using a DSL for it
-is not a major drawback.
-
-Supporters of the exploded table format believe it has better
-ergonomics. Tooling which can validate TOML formats could also help
-detect errors in a ``pyproject.toml`` file while editing instead of
-waiting until the user has run a tool in the case of :pep:`508`'s DSL.
-Supporters also believe it is easier to read and reason (both in
-general and for first-time users). They also point out that other
-programming languages have adopted a format more like an exploded
-table thanks to their use of standardized configuration formats (e.g.
-`Rust <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html>`__,
-and `Dart <https://dart.dev/tools/pub/dependencies>`__). The thinking
-is that an exploded table format would be more familiar to people
-coming to Python from another programming language.
 
 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.
 
+
+Open Issues
+===========
+None at the moment.
+
 Copyright
 =========
 

pep-0631.rst

@@ -3,12 +3,12 @@ Title: Dependency specification in pyproject.toml based on PEP 508
 Author: Ofek Lev <ofekmeister@gmail.com>
 Sponsor: Paul Ganssle <paul@ganssle.io>
 Discussions-To: https://discuss.python.org/t/5018
-Status: Draft
+Status: Accepted
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 20-Aug-2020
 Post-History: 20-Aug-2020
-
+Resolution: https://discuss.python.org/t/how-to-specify-dependencies-pep-508-strings-or-a-table-in-toml/5243/38
 
 Abstract
 ========
@@ -17,6 +17,10 @@ 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`_.
 
+.. note::
+    This PEP has been accepted and is expected to be merged into
+    :pep:`621`.
+
 Entries
 =======