Proposal include an optional `build-state` field

[LecrisUT]

Context

I was considering how this can interact with PEP791 when addressing the recent licensing discussion on PEP639 about needing different license context for license to distinguish between the project and the wheel license. Reading the PyPA page about dynamic field ¹, I don't actually see a mention of how the dynamic fields are to be interpreted when you have pre-computed values from the sdist. For the license example the sdist metadata might indicate the additional license of the test files, but then how do we indicate that the field needs to be recalculated? Currently whether to use the bundled metadata or recalculate it, is it up to the build backend or the metadata provider?

Proposal

Add an additional field build-state (please find a better name) to the tool.dynamic-metadata array (see requirement section), that would indicate when the metadata should be expanded and when the pre-computed values are valid.

Values

The values that build-state field can have is to be a list of string with default [ "all" ]. The allowed string values can be one of sdist, wheel, all.

If it's possible, to allow the field to be either a list or a string, then it would be a nice user experience to allow the usage of a string in place of an array with only one element. Currently with only the sdist, wheel effective values this could also be exclusively a string, but it might be prudent to allow future expansions of this (e.g. in the context of wheel variants?)?

Behavior

When building the metadata for the sdist, the provider will check for the tool.dynamic-metadata entry that matches the field that is being evaluated and has one of the build_state values be sdist or all.

When building the wheel without a PKG-INFO present, do the same as above, but with build_state checking for wheel or all.

When building the wheel with a PKG-INFO present, then the build-backend (or currently dynamic-metadata if it can?) would check for each list item's build-state value and do:

• Workflow A:
  • If both sdist and wheel are present in the list item, then reuse the value in the sdist without pulling in the provider
  • If only wheel is present in the list item, then pull in the provider and calculate from scratch
• Workflow B:
  • Same as A, but when only wheel is present, the provider decides whether to calculate from scratch or take the sdist values
  • The providers must also be aware of the build-state. The value is the current list item that contains wheel in the build-state.
    I suppose they are still able to do so if it's passed in settings as a normal key, but that would break the check in the implementations like dynamic_metadata/plugins/regex.py
• Workflow C:
  • Similar to workflow B, but it's always the provider that decides if they should use the sdist values
  • Downside is that the provider is always added as a build-requires.

Validation checks

• Each pair of (field, build_state) must be unique (after expanding the all keyword)
• If the field key points to a required field, both sdist and wheel pairs must be present

Example

An example for handling different sdist/wheel licenses it can look like:

[[tool.dynamic-metadata]]
field = "license"
build-state = "sdist"
provider = "bundle_license"
bundled-licenses = "MIT AND Unlicense"

[[tool.dynamic-metadata]]
field = "license"
build-state = "wheel"
provider = "bundle_license"
bundled-licenses = "MIT"

Requirement

Refactoring the tool.dynamic-metadata to accept toml arrays in order to allow to have multiple providers

Footnotes

1. https://packaging.python.org/en/latest/specifications/pyproject-toml/#dynamic ↩