Help testing experimental features in setuptools

The license.file subkey in PEP 621 is rather under-specified, leading to substantial ambiguity and potential confusion over the specific intended behavior and mapping (not the least for me when writing PEP 639). However, after far too much time carefully combing through the PEP, actual implementations and discussions with some of the authors, what I believe their intent here (not entirely sure whether and how all implementations follow it; it would seem like @abravalheri 's implementation in Setuptools omits this functionality) was that the contents of the file listed under license.file get loaded and dumped as a string into the License metadata field; that’s the reason it is mutually exclusive with the text subkey, since only one or the other is used for the field value.

Therefore, at least per PEP 621, if you want to specify a SPDX expression for your package, you would list it under license.text, and your license file (and any others) should get picked up automatically by the de-facto standard li[cs]ense*, copying*, notice*, authors* glob I helped implement in Wheel some time back, and it looks like the main tools setuptools, wheel, etc. adopted as a de-facto standard (unless you have license files that don’t fit that pattern, in which case you’ll have to continue to rely on the Setuptools license_files option in the tool section until PEP 639 is accepted). If @abravalheri doesn’t implement the license key entirely to allow a clean transition when PEP 639 is approved in final form, which is a fair decision, then you’ll just list that under license in the tool section instead.

PEP 639 will resolve and simplify this, at least as presently designed; you’ll just put your SPDX license expression as the flat value of license, and list your license files under license-files (if not relying on the de-facto standard default glob which this PEP also now makes de-jure).

Actually, the consensus plan for some time (and as implemented in the PEP) has been to deprecate the old License core metadata field and store the license expression in a new License-Expression field instead, due to the ambiguity that storing it in License would create (which is at cross-purposes to the PEP’s main goal of improving clarity here).

Also, I’m working on finally updating the PEP to reflect this as we speak, but the current consensus approach to the PEP 621 keys is to have a SPDX expression be the flat string value of license, as the PEP 621 authors originally intended, rather than introducing a new top-level license-expression key, and thus naturally deprecating (and being mutually exclusive with) the license.text and license.file keys.

I’m assuming this is a result of choosing not to support the license key entirely until PEP 639 is resolved. I don’t object to that decision, but if you do go that route, please make specifying license an informative error until that’s the case, or people’s license metadata will get silently dropped.

See above, this took many re-readings, analysis and discussion to get clarity on due to substantial ambiguity in the original PEP, but this appears to be ultimately because license.file appears to be intended to do something very different from Wheel and Setuptools license_file and license_files options, namely loading the text of a single file and injecting that as the License core metadata field, rather than including multiple listed files in the distribution. Thus, it is not possible to specify the text and file subkeys to license simultaneously, as they get routed to the same core metadata field.

2 Likes