Merge pull request #2082 from henryiii/henryiii/chore/pep808

feat: add METADATA 2.6 (PEP 808)

Author: webknjaz

source/specifications/core-metadata.rst

@@ -6,7 +6,7 @@
 Core metadata specifications
 ============================
 
-This page describes version 2.5, approved in September 2025.
+This page describes version 2.6, approved in May 2026.
 
 Fields defined in the following specification should be considered valid,
 complete and not subject to change. The required fields are:
@@ -50,7 +50,7 @@ Metadata-Version
 .. versionadded:: 1.0
 
 Version of the file format; legal values are "1.0", "1.1", "1.2", "2.1",
-"2.2", "2.3", "2.4", and "2.5".
+"2.2", "2.3", "2.4", "2.5", and "2.6".
 
 Automated tools consuming metadata SHOULD warn if ``metadata-version`` is
 greater than the highest version they support, and MUST fail if
@@ -109,6 +109,10 @@ Dynamic (multiple use)
 ======================
 
 .. versionadded:: 2.2
+.. versionchanged:: 2.6
+   A multiple use field that is present in the sdist and also marked
+   ``Dynamic`` may only be appended to in a wheel built from the sdist.
+   Previously any field listed in Dynamic was ignored in an sdist.
 
 A string containing the name of another core metadata field. The field
 names ``Name``, ``Version``, and ``Metadata-Version`` may not be specified
@@ -121,8 +125,12 @@ rules apply:
    in any wheel built from the sdist MUST match the value in the sdist.
    If the field is not in the sdist, and not marked as ``Dynamic``, then
    it MUST NOT be present in the wheel.
-2. If a field is marked as ``Dynamic``, it may contain any valid value in
-   a wheel built from the sdist (including not being present at all).
+2. If a single-use field is marked as ``Dynamic``, it may contain any valid
+   value in a wheel built from the sdist (including not being present at all).
+3. If a multiple use field is present in the sdist and also marked ``Dynamic``,
+   then a wheel built from the sdist MUST include the value(s) present in the
+   sdist. The wheel MAY add further values, but it MUST NOT remove, reorder, or
+   modify the values present in the sdist.
 
 If the sdist metadata version is older than version 2.2, then all fields should
 be treated as if they were specified with ``Dynamic`` (i.e. there are no special
@@ -1074,6 +1082,12 @@ History
 - January 2026: Replaced outdated direct reference to :pep:`508` with a
   reference to :ref:`dependency-specifiers`.
 
+- May 2026: Core metadata 2.6 was approved through :pep:`808`.
+
+  - Allowed a multiple use field marked ``Dynamic`` to be appended to in a
+    wheel built from a sdist, requiring the wheel to preserve the value(s)
+    present in the sdist.
+
 ----
 
 .. [1] reStructuredText markup:

source/specifications/pyproject-toml.rst

@@ -114,6 +114,13 @@ by the metadata). Dynamic metadata is listed via the ``dynamic`` key
 (defined later in this specification) and represents metadata that a
 tool will later provide.
 
+A key whose value is a list or a table of arbitrary entries MAY be
+specified statically *and* listed in ``dynamic`` at the same time. In
+that case the entries given statically are fixed and a build back-end
+MAY only *append* further entries to them; the back-end MUST NOT
+remove, reorder, or modify any statically-specified entries. See the
+:ref:`dynamic <pyproject-toml-dynamic>` key for details.
+
 The lack of a ``[project]`` table implicitly means the :term:`build backend <Build Backend>`
 will dynamically provide all keys.
 
@@ -619,8 +626,9 @@ provided via tooling later on.
   field as "Optional", the metadata MAY list it in ``dynamic`` if the
   expectation is a build back-end will provide the data for the key
   later.
-- Build back-ends MUST raise an error if the metadata specifies a
-  key statically as well as being listed in ``dynamic``.
+- Build back-ends MUST raise an error if the metadata specifies a key
+  statically as well as being listed in ``dynamic``, *unless* the key
+  represents a list or arbitrary table that can be extended, listed below.
 - If the metadata does not list a key in ``dynamic``, then a build
   back-end CANNOT fill in the requisite metadata on behalf of the user
   (i.e. ``dynamic`` is the only way to allow a tool to fill in
@@ -630,6 +638,35 @@ provided via tooling later on.
   the data for it (omitting the data, if determined to be the accurate
   value, is acceptable).
 
+A key whose value is a list or a table of arbitrary entries MAY be
+specified statically and listed in ``dynamic`` simultaneously. The
+keys fitting that description are:
+
+- ``authors``
+- ``classifiers``
+- ``dependencies``
+- ``entry-points``
+- ``gui-scripts``
+- ``import-names``
+- ``import-namespaces``
+- ``keywords``
+- ``license-files``
+- ``maintainers``
+- ``optional-dependencies``
+- ``scripts``
+- ``urls``
+
+When such a key is specified both statically and listed in
+``dynamic``:
+
+- A build back-end MAY only *append* entries to the value; it MUST NOT
+  remove, reorder, or modify any statically-specified entries. For
+  tables (such as ``optional-dependencies`` or ``entry-points``) this
+  means a back-end MAY add new keys and MAY append to the values of
+  existing keys (in the case of a list), but MUST NOT change or remove the
+  entries given statically.
+- A build back-end SHOULD raise an error if a key is listed in
+  ``dynamic`` and it does not support extending that key.
 
 
 .. _pyproject-tool-table:
@@ -673,4 +710,8 @@ History
 - January 2026: Replaced outdated direct reference to :pep:`508` with a
   reference to :ref:`dependency-specifiers`.
 
+- May 2026: Allowed list and table keys to be specified statically as well
+  as listed in ``dynamic``, with build back-ends only able to append
+  entries, through :pep:`808`.
+
 .. _TOML: https://toml.io