@@ -16,8 +16,8 @@ Abstract
1616
1717This PEP relaxes the constraint on dynamic metadata listed in the ``[project] ``
1818section in ``pyproject.toml `` to allow the static portion of mixed metadata to
19- be defined in the normal location if the field is a table, array or `` license ``
20- by having the dynamic fields extend the static ones.
19+ be defined in the normal location if the field is a table or array by having
20+ the dynamic fields extend the static ones.
2121
2222This allows users to opt into allowing a backend to extend metadata while still
2323keeping the static portions of the metadata defined in the standard location in
@@ -92,9 +92,7 @@ Every list and every table with arbitrary keys will now be allowed to be
9292specified both statically, in the ``[project] `` table, and in the
9393``project.dynamic `` list. If it is present in both places, the build backend
9494can extend list items and add new keys, but not modify existing list items or
95- strings. We are also including one special case; the ``license `` field when
96- specified as a string is an SPDX expression, which has a similar concept of
97- extension with ``AND ``.
95+ strings.
9896
9997
10098Use Cases
@@ -122,17 +120,13 @@ cases that have come up:
122120 and inject them (Poetry _ being the best known example).
123121- Adding license files to the wheel based on what libraries are linked in (this
124122 is an active discussion in followup to :pep: `639 `).
125- - Similarly, adding licenses based on vendored code (the setuptools _ repo might be
126- able to use this.)
127123- Adding SBom's when building - :pep: `770 ` had to remove the ``pyproject.toml ``
128124 field specifically because you _want_ the build tool to add these, so the
129125 ``[project] `` table setting would be useless, you'd almost never be able to
130126 use it.
131127
132128All of these use cases have a similar feature: they are adding something
133129dynamically to a fixed list (possibly a narrower pin for the dependency case).
134- With the exception of the recently added ``license `` field, these are all lists
135- or tables that need extending.
136130
137131You can implement these today, but it requires providing a completely separate
138132configuration location for the non-extended portion, and static analysis tools
@@ -195,40 +189,10 @@ longer needs to create and document a new location for the standard
195189example).
196190
197191
198- Example: licenses
199- -----------------
200-
201- As another example, a package could specify its license(s):
202-
203- .. code-block :: toml
204-
205- [project]
206- license = "MIT"
207- license-files = ["LICENSE"]
208-
209- dynamic = ["license", "license-files"]
210-
211- [tool.my-build-backend]
212- license-search-sdist = ["vendor/*"]
213- linked-wheel-licenses = true
214-
215-
216- Now a build-backend can search for licenses in the vendor folder, and add them
217- automatically to the license expression and/or file list. If it supports this
218- when creating the wheel, it can specify the necessary fields in the ``Dynamic ``
219- ``METADATA `` (2.2+) field and then add the licenses that are linked in when
220- creating the wheel. While you can do this today, you can't specify the
221- project's own license statically when you do this; this PEP allows both.
222-
223192
224193Future Updates
225194--------------
226195
227- New fields added to the ``[project] `` table in future PEPs should include how
228- to handle additive dynamic metadata if they need special handling. Currently,
229- there is only one special case (``license ``), so this is not expected to be
230- common.
231-
232196Loosening this rule to allow purely additive metadata should address many of
233197the use cases that have been seen in practice. If further changes are needed,
234198this can be revisited in a future PEP; this PEP neither recommends or precludes
@@ -250,8 +214,6 @@ now be allowed to be present in both the ``[project]`` table and the
250214backend is allowed to insert entries into the list or table, but not remove
251215entries, reorder entries, or modify the entries. Tables of arrays allow adding
252216a new table entry or extending an existing array according to the rules above.
253- As a special case, the ``license `` field, when set to a string SPDX expression,
254- can be extended logically, as well.
255217
256218The fields that are arrays or tables with arbitrary entries are:
257219
@@ -266,8 +228,6 @@ The fields that are arrays or tables with arbitrary entries are:
266228 be changed or removed.
267229* ``keywords ``: Keywords can be added to the list.
268230* ``license-files ``: Files can be added to the list.
269- * ``license `` (string, special case): The license expression can be extended.
270- An existing license cannot be logically excluded.
271231* ``optional-dependencies ``: A new extra or new items can be added to a
272232 existing extra.
273233* ``urls ``: New urls can be added. Existing ones cannot be changed or removed.
@@ -338,9 +298,7 @@ introductory packaging.
338298
339299The ``pyproject.toml `` `specification <pyprojectspec >`__ will be updated to
340300include the behavior of fields when specified and also listed in the dynamic
341- field. An example of such an update for the license field:
342-
343- * When also listed in ``dynamic ``: Can be extended with ``AND ``
301+ field.
344302
345303It should also be noted that specifying something in dynamic will require any
346304tool that requires the full metadata to invoke the backend even if it is
@@ -359,13 +317,16 @@ the use cases seen, though, and an explicit, opt-in approach is better for
359317static tooling.
360318
361319
362- Include more string fields
363- --------------------------
320+ Include string fields
321+ ---------------------
322+
323+ Some string fields could also be extended. Most notably, the ``license `` field
324+ would benefit from being extendable, and due to the semantics of SPDX
325+ expressions, extension could be defined through ``AND ``. This was not added to
326+ this PEP to keep it purely focused on arrays and tables.
364327
365- There are two more string fields, namely ``version `` and ``requires-python ``
366- (``name `` is not allowed to be specified dynamically). There did not seem to be
367- a pressing practical need to allow these to be extended as with ``license ``,
368- and logical extensions are not as clear, so they are not included in this PEP.
328+ The other string fields, namely ``version `` and ``requires-python `` (``name ``
329+ is not allowed to be specified dynamically), have less reason to be extended.
369330Fixed key tables, like the deprecated ``license.text ``/``license.file `` or
370331``readme.text ``/``readme.file `` also have no clear benefit being partially
371332dynamic.
0 commit comments