PEP 9999: Convert optional-deps to table of reqs with extra key

pep-9999.rst

@@ -85,8 +85,6 @@ in :pep:`621`.
 
 .. _toml: https://toml.io/
 
-.. _dependencies-spec:
-
 dependencies
 ------------
 
@@ -104,6 +102,8 @@ values can have one of the following types:
 - array: an array of requirement tables. It is an error to specify an empty
   array ``[]`` as a value.
 
+.. _requirement-spec:
+
 Requirement table
 ^^^^^^^^^^^^^^^^^
 
@@ -145,10 +145,19 @@ optional-dependencies
 
 Format: table
 
-The keys inside this table are the names of the project's :pep:`508` extras.
-The values each specify the list of requirements required by the extra, and are
-tables. These requirement lists are described with the same as
-`the dependencies specification <#dependencies-spec>`_ above.
+The keys inside this table are the names of an extra's required distribution.
+The values can have one of the following types:
+
+- table: a requirement table.
+
+- array: an array of requirement tables.
+
+These requirement tables have
+`the same specification as above <#requirement-spec>`_, with the addition of
+the following required key:
+
+- ``for-extra`` (string): the name of the :pep:`508` extra that this
+  requirement is required for.
 
 
 Reference implementation
@@ -243,13 +252,11 @@ specification for `docker-compose`_:
     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.socks]
-    PySocks = { version = ">= 1.5.6, != 1.5.7, < 2" }
-
-    [project.optional-dependencies.tests]
-    ddt = { version = ">= 1.2.2, < 2" }
-    pytest = { version = "< 6" }
-    mock = { version = ">= 1.0.1, < 4", markers = "python_version < '3.4'" }
+    [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" }
 
 .. _docker-compose: https://github.com/docker/compose/blob/789bfb0e8b2e61f15f423d371508b698c64b057f/setup.py#L28-L61
 
@@ -281,22 +288,22 @@ Rejected Ideas
 - 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.
 
+- Have the ``optional-dependencies`` be a table of dependency tables for each
+  extra, with the table name being the extra's name. This made
+  ``optional-dependencies`` a different type (table of tables of requirements)
+  from ``dependencies`` (table of requirements), which could be jarring for
+  users and harder to parse.
+
 - Making each :pep:`508` environment marker as a key (or child-table key) in
   the requirement. This arguably increases readability and ease of parsing.
   The ``markers`` key would still be allowed for more advanced specification,
   with which the key-specified environment markers are ``and``'d with the
   result of. This was deferred as more design needs to be undertaken.
 
-
-Open Issues
-===========
-
-- Including a required ``for-extra`` key in extra requirements, which specifies
-  the extra for which the requirement is required for. This allows the
-  ``optional-dependencies`` table to be the same type as ``dependencies``
-  (table of requirements), and matches the ``extra`` environment marker. The
-  user then needs to specify the extra for each requirement, where typos can
-  cause a mis-specification of the project's extras.
+- Replacing the `for-extra` key with `for-extras`, with the value being an
+  array of extras to makr the requirement a dependency for. This reduces some
+  duplication, but in this case that duplication makes explicit which extras
+  have which dependencies.
 
 
 Copyright