PEP 639: Simply conversion guidance and don't focus on at build-time

Author: CAM-Gerlach

pep-0639.rst

@@ -596,11 +596,6 @@ Build tools SHOULD validate the expression as described in the
 an error or warning as specified. When generating the core metadata, tools
 MUST perform case normalization.
 
-If and only if the ``license-expression`` key is listed as ``dynamic``
-(and is not specified), tools MAY infer a value for the ``License-Expression``
-field if they can do so unambiguously, but MUST follow the provisions in the
-:ref:`639-spec-converting-metadata` section.
-
 If the ``license-expression`` key is present and valid (and the ``license``
 key is not specified), for purposes of backward compatibility, tools MAY
 back-fill the ``License`` core metadata field with the case-normalized value
@@ -776,37 +771,13 @@ each format, per the :ref:`639-spec-field-license-file` section.
 Converting legacy metadata
 --------------------------
 
-If the contents of the ``license.text``
-``[project]`` table key in ``pyproject.toml``
-(or equivalent for tool-specific config formats) is a valid license expression
-containing solely known, non-deprecated license identifiers, and
-(if the ``[project]`` table is present)
-the ``license-expression`` key is listed as ``dynamic``,
-build tools MAY use it to fill the ``License-Expression`` field.
-
-Similarly, if the ``classifiers`` ``[project]`` table key (or equivalent
-for tool-specific config formats) contains exactly one license classifier
-that unambiguously maps to exactly one valid, non-deprecated SPDX license
-identifier, tools MAY fill the ``License-Expression`` field with the latter.
-
-If both a ``license.text`` or equivalent value and a single license classifier
-are present, the contents of the former, including capitalization
-(but excluding leading and trailing whitespace), MUST exactly match the SPDX
-license identifier mapped to the license classifier to be considered
-unambiguous for the purposes of automatically filling the
-``License-Expression`` field.
-
-If tools have filled the ``License-Expression`` field as described here,
-they MUST output a prominent, user-visible warning informing package authors
-of that fact, including the ``License-Expression`` string they have output,
-and recommending that the project source metadata be updated accordingly
-with the indicated license expression.
-
-In any other case, tools MUST NOT use the contents of the ``license.text``
-key (or equivalent) or license classifiers to fill the
-``License-Expression`` field without informing the user and requiring
-unambiguous, affirmative user action to select and confirm the desired
-``License-Expression`` value before proceeding.
+Tools MUST NOT use the contents of the ``license.text`` ``[project]`` key
+(or equivalent tool-specific format),
+license classifiers or the value of the core metadata ``License`` field
+to fill the top-level string value of the ``license`` key ``
+or the core metadata ``License-Expression`` field
+without informing the user and requiring unambiguous, affirmative user action
+to select and confirm the desired license expression value before proceeding.
 
 
 .. _639-spec-mapping-classifiers-identifiers:
@@ -815,19 +786,19 @@ Mapping license classifiers to SPDX identifiers
 '''''''''''''''''''''''''''''''''''''''''''''''
 
 Most single license classifiers (namely, all those not mentioned below)
-map to a single valid SPDX license identifier, allowing tools to insert them
-into the ``License-Expression`` field following the
-:ref:`specification above <639-spec-converting-metadata>`.
-
-Many legacy license classifiers intend to specify a particular license,
+map to a single valid SPDX license identifier,
+allowing tools to infer the SPDX license identifier they correspond to,
+both for use when analyzing and auditing packages,
+and providing a semi-automated mechanism of filling the ``license`` key
+or the  the ``License-Expression`` field
+following the :ref:`specification above <639-spec-converting-metadata>`.
+
+Some legacy license classifiers intend to specify a particular license,
 but do not specify the particular version or variant, leading to a
-`critical ambiguity <classifierissue_>`__ as to their terms, compatibility
-and acceptability. Tools MUST NOT attempt to automatically infer a
-``License-Expression`` when one of these classifiers is used, and SHOULD
-instead prompt the user to affirmatively select and confirm their intended
-license choice.
-
-These classifiers are the following:
+`critical ambiguity <classifierissue_>`__
+as to their terms, compatibility and acceptability.
+Tools MUST NOT attempt to automatically infer a ``License-Expression``
+when one of these classifiers is used without affirmative user action:
 
 - ``License :: OSI Approved :: Academic Free License (AFL)``
 - ``License :: OSI Approved :: Apache Software License``
@@ -850,12 +821,14 @@ MAY use as a reference for the identifier selection options to offer users
 when prompting the user to explicitly select the license identifier
 they intended for their project.
 
-**Note**: Several additional classifiers, namely the "or later" variants of
-the AGPLv3, GPLv2, GPLv3 and LGPLv3, are also listed in the aforementioned
-mapping, but as they were merely proposed for textual harmonization and
-still unambiguously map to their respective licenses,
-they were not included here; LGPLv2 is, however, as it could ambiguously
-refer to either the distinct v2.0 or v2.1 variants of that license.
+.. note::
+
+    Several additional classifiers, namely the "or later" variants of
+    the AGPLv3, GPLv2, GPLv3 and LGPLv3, are also listed in the aforementioned
+    mapping, but unambiguously map to their respective licenses,
+    and so are not listed here.
+    However, LGPLv2 is included above, as it could ambiguously
+    refer to either the distinct v2.0 or v2.1 variants of that license.
 
 In addition, for the various special cases, the following mappings are
 considered canonical and normative for the purposes of this specification:
@@ -870,38 +843,39 @@ considered canonical and normative for the purposes of this specification:
   since the meaning associated with the term "public domain" is thoroughly
   dependent on the specific legal jurisdiction involved,
   some of which lack the concept entirely.
-  Alternatively, tools MAY choose to treat these classifiers as ambiguous and
-  require user confirmation to fill ``License-Expression`` in these cases.
-
-- The generic and sometimes ambiguous classifiers
-  ``License :: Free For Educational Use``,
-  ``License :: Free For Home Use``,
-  ``License :: Free for non-commercial use``,
-  ``License :: Freely Distributable``,
-  ``License :: Free To Use But Restricted``,
-  ``License :: Freeware``, and
-  ``License :: Other/Proprietary License`` MAY be mapped to the generic
+  Alternatively, tools MAY choose to treat these classifiers as ambiguous.
+
+- The generic and sometimes ambiguous classifiers:
+
+  - ``License :: Free For Educational Use``
+  - ``License :: Free For Home Use``
+  - ``License :: Free for non-commercial use``
+  - ``License :: Freely Distributable``
+  - ``License :: Free To Use But Restricted``
+  - ``License :: Freeware``
+  - ``License :: Other/Proprietary License``
+
+  MAY be mapped to the generic
   ``License-Expression: LicenseRef-Proprietary``,
   but tools MUST issue a prominent, informative warning if they do so.
-  Alternatively, tools MAY choose to treat these classifiers as ambiguous and
-  require user confirmation to fill ``License-Expression`` in these cases.
+  Alternatively, tools MAY choose to treat these classifiers as ambiguous.
 
 - The generic and ambiguous classifiers ``License :: OSI Approved`` and
   ``License :: DFSG approved`` do not map to any license expression,
-  and thus tools MUST treat them as ambiguous and require user intervention
-  to fill ``License-Expression``.
+  and thus tools SHOULD treat them as ambiguous, or if not MUST ignore them.
 
 - The classifiers ``License :: GUST Font License 1.0`` and
   ``License :: GUST Font License 2006-09-30`` have no mapping to SPDX license
-  identifiers and no PyPI package uses them, as of the writing of this PEP.
-  Therefore, tools MUST treat them as ambiguous when attempting to fill
-  ``License-Expression``.
+  identifiers, and no PyPI package uses them as of 2022-07-09.
 
 When multiple license classifiers are used, their relationship is ambiguous,
 and it is typically not possible to determine if all the licenses apply or if
-there is a choice that is possible among the licenses. In this case, tools
-MUST NOT automatically infer a license expression, and SHOULD suggest that the
-package author construct one which expresses their intent.
+there is a choice that is possible among the licenses,
+In this case, tools MUST NOT automatically infer a license expression,
+unless one license classifier is a parent of the other,
+i.e. the child contains all ``::``-delineated components of the parent,
+in which case tools MAY ignore the parent classifier
+but SHOULD issue an informative warning when doing so.
 
 
 .. _639-backwards-compatibility:
@@ -1014,12 +988,19 @@ many, if not most common cases:
   tool authors with guidelines on how to suggest a license expression produced
   from legacy classifiers.
 
-- Tools may also be able to infer and suggest how to update an existing
-  ``License`` value and convert that to a ``License-Expression``.
-  For instance, a tool may suggest converting from a ``License`` field with
-  ``Apache2`` (which is not a valid license expression as defined in this PEP)
-  to a ``License-Expression`` field with ``Apache-2.0`` (which is a valid
-  license expression using an SPDX license identifier).
+- Tools may also be able to infer and suggest how to update
+  an existing ``License`` value in project source metadata
+  and convert that to a license expression,
+  as also :ref:`specified in this PEP <639-spec-converting-metadata>`.
+  For instance, a tool may suggest converting a value of ``MIT``
+  in the ``license.text`` key in ``[project]``
+  (or the equivalent in tool-specific formats)
+  to a top-level string value of the ``license`` key (or equivalent).
+  Likewise, a tool could suggest converting from a ``License`` of ``Apache2``
+  (which is not a valid license expression
+  as :ref:`defined in this PEP <639-spec-field-license-expression>`)
+  to a ``License-Expression`` of ``Apache-2.0``
+  (the equivalent valid license expression using an SPDX license identifier).
 
 
 .. _639-reference-implementation:
@@ -1319,25 +1300,15 @@ ultimately rejected, as it shared most of the downsides identified with
 adding new subkeys under the existing ``license`` table, as well as several
 of its own, with again minimal advantage over separating both.
 
-Most importantly, it still means that per the
+Also, this still means that per the
 `project source metadata spec <pep621specdynamic_>`__,
 it is not possible to separately mark the ``[project]`` keys
 corresponding to the ``License`` and ``License-Expression`` metadata fields
 as ``dynamic``.
-This, in turn, still
-renders specifying metadata following that standard incompatible with
-conversion of legacy metadata, as specified in this PEP's
-:ref:`639-spec-converting-metadata`,
-as the project source metadata spec strictly prohibits the ``license`` key
-from being both present (to define the existing value of
-the ``License`` field, or the path to a license file, and thus able to be
-converted), and specified as ``dynamic`` (which would allow tools to
-use the generated value for the ``License-Expression`` field.
-
-For the same reasons, this would make it impossible to back-fill the
-``License`` field from the ``License-Expression`` field as this PEP
-currently allows (without making an exception from strict
-``dynamic`` behavior in this case), as again, marking ``license`` as dynamic
+This raises a potential concern with back-filling the ``License`` field
+from the ``License-Expression`` field as this PEP currently allows
+(without making an exception from strict ``dynamic`` behavior in this case),
+as marking ``license`` as dynamic
 would mean it cannot be specified in the ``[project]`` table at all.
 
 Furthermore, this would mean existing project source metadata specifying
@@ -2024,8 +1995,8 @@ determined to be unnecessary or too problematic in practice.
 
 .. _639-examples:
 
-Appendix: License Expression Examples
-=====================================
+Appendix: Examples
+==================
 
 .. _639-example-basic:
 
@@ -2207,37 +2178,6 @@ and ``{version}`` as the previous, the license files would be installed to:
     site-packages/setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.BSD
 
 
-.. _639-example-conversion:
-
-Conversion example
-------------------
-
-Suppose we were to return to our simple Setuptools case.
-Per the specification, given it only has the following license classifier:
-
-.. code-block:: email
-
-    Classifier: License :: OSI Approved :: MIT License
-
-And no value for the ``License`` field, or equivalently, if it had a
-value of:
-
-.. code-block:: email
-
-    License: MIT
-
-Then the suggested value for the ``License-Expression`` field would be:
-
-.. code-block:: email
-
-    License-Expression: MIT
-
-For the more complex case, assuming it was currently expressed as multiple
-license classifiers, no automatic conversion could be performed due to the
-inherent ambiguity, and the user would be prompted on how to handle the
-situation themselves.
-
-
 .. _639-example-expression:
 
 Expression examples