PEP 639: Incorporate the latest discussion feedback (#3866)

befeleme · hroncok · web-flow · commit db2a96f8e1a7 · 2024-07-25T14:07:53.000-07:00
* Remove the requirement of license-files defaults

* Cover all rejected subkeysideas in one paragraph

* Change the deprecation policy around classifiers

* Flatten the value of the license-files key, only globs are specified

* Update the Rejected ideas to match the current license-files proposal

---------

Co-authored-by: Miro Hrončok &lt;miro@hroncok.cz&gt;
diff --git a/peps/pep-0639.rst b/peps/pep-0639.rst
@@ -451,22 +451,18 @@ in the ``Classifier`` :term:`Core Metadata field`
 (`described in the Core Metadata specification <coremetadataclassifiers_>`__)
 is deprecated and replaced by the more precise ``License-Expression`` field.
 
-If the ``License-Expression`` field is present, build tools SHOULD and
-publishing tools MUST raise an error if one or more license classifiers
+If the ``License-Expression`` field is present, build tools MAY raise an error
+if one or more license classifiers
 is included in a ``Classifier`` field, and MUST NOT add
 such classifiers themselves.
 
-Otherwise, if this field contains a license classifier, build tools MAY
-and publishing tools SHOULD issue a warning informing users such classifiers
+Otherwise, if this field contains a license classifier,
+tools MAY issue a warning informing users such classifiers
 are deprecated, and recommending ``License-Expression`` instead.
 For compatibility with existing publishing and installation processes,
 the presence of license classifiers SHOULD NOT raise an error unless
 ``License-Expression`` is also provided.
 
-For all newly-uploaded distributions that include a
-``License-Expression`` field, the `Python Package Index (PyPI) <pypi_>`__ MUST
-reject any that also specify any license classifiers.
-
 New license classifiers MUST NOT be `added to PyPI <classifiersrepo_>`__;
 users needing them SHOULD use the ``License-Expression`` field instead.
 License classifiers may be removed from a new version of the specification
@@ -524,104 +520,62 @@ paths in the project source tree relative to ``pyproject.toml`` to file(s)
 containing licenses and other legal notices to be distributed with the package.
 It corresponds to the ``License-File`` fields in the Core Metadata.
 
-Its value is a table, which if present MUST contain one of two optional,
-mutually exclusive subkeys, ``paths`` and ``globs``; if both are specified,
-tools MUST raise an error. Both are arrays of strings; the ``paths`` subkey
-contains verbatim file paths, and the ``globs`` subkey valid glob patterns,
-which MUST be parsable by the ``glob`` `module <globmodule_>`__ in the
-Python standard library.
-
+Its value is an array of strings which MUST contain valid glob patterns,
+as specified below.
+The glob patterns MAY contain special glob characters: ``*``, ``?``, ``**``
+and character ranges: ``[]``, and tools MUST support them.
 Path delimiters MUST be the forward slash character (``/``),
 and parent directory indicators (``..``) MUST NOT be used.
 Tools MUST assume that license file content is valid UTF-8 encoded text,
 and SHOULD validate this and raise an error if it is not.
 
-If the ``paths`` subkey is a non-empty array, build tools:
-
-- MUST treat each value as a verbatim, literal file path, and
-  MUST NOT treat them as glob patterns.
-
-- MUST include each listed file in all distribution archives.
-
-- MUST NOT match any additional license files beyond those explicitly
-  statically specified by the user under the ``paths`` subkey.
+Literal paths (e.g. ``LICENSE``) are treated as valid globs which means they
+can also be defined.
 
-- MUST list each file path under a ``License-File`` field in the Core Metadata.
+To achieve better portability, the filenames to match should only contain
+the alphanumeric characters, underscores (``_``), hyphens (``-``)
+and dots (``.``).
 
-- MUST raise an error if one or more paths do not correspond to a valid file
-  in the project source that can be copied into the distribution archive.
-
-If the ``globs`` subkey is a non-empty array, build tools:
+Build tools:
 
 - MUST treat each value as a glob pattern, and MUST raise an error if the
   pattern contains invalid glob syntax.
 
-- MUST include all files matched by at least one listed pattern in all
+- MUST include all files matched by a listed pattern in all
   distribution archives.
 
-- MAY exclude files matched by glob patterns that can be unambiguously
-  determined to be backup, temporary, hidden, OS-generated or VCS-ignored.
-
 - MUST list each matched file path under a ``License-File`` field in the
   Core Metadata.
 
-- SHOULD issue a warning and MAY raise an error if no files are matched.
-
-- MAY issue a warning if any individual user-specified pattern
+- MUST raise an error if any individual user-specified pattern
   does not match at least one file.
 
-If the ``license-files`` key is present, and the ``paths`` or ``globs`` subkey
+If the ``license-files`` key is present and
 is set to a value of an empty array, then tools MUST NOT include any
 license files and MUST NOT raise an error.
 
-.. _639-default-patterns:
-
-If the ``license-files`` key is not present and not explicitly marked as
-``dynamic``, tools MUST assume a default value of the following:
-
-.. code-block:: toml
-
-    license-files.globs = ["LICEN[CS]E*", "COPYING*", "NOTICE*", "AUTHORS*"]
-
-In this case, tools MAY issue a warning if no license files are matched,
-but MUST NOT raise an error.
-
-If the ``license-files`` key is marked as ``dynamic`` (and not present),
-to preserve consistent behavior with current tools and help ensure the packages
-they create are legally distributable, build tools SHOULD default to
-including at least the license files matching the above patterns, unless the
-user has explicitly specified their own.
-
 Examples of valid license files declaration:
 
 .. code-block:: toml
 
     [project]
-    license-files = { globs = ["LICEN[CS]E*", "AUTHORS*"] }
+    license-files = ["LICEN[CS]E*", "AUTHORS*"]
 
     [project]
-    license-files.paths = ["licenses/LICENSE.MIT", "licenses/LICENSE.CC0"]
+    license-files = ["licenses/LICENSE.MIT", "licenses/LICENSE.CC0"]
 
     [project]
-    license-files = { paths = [] }
+    license-files = ["LICENSE.txt", "licenses/*"]
 
     [project]
-    license-files.globs = []
+    license-files = []
 
 Examples of invalid license files declaration:
 
 .. code-block:: toml
 
     [project]
-    license-files.globs = ["LICEN[CS]E*", "AUTHORS*"]
-    license-files.paths = ["LICENSE.MIT"]
-
-Reason: license-files.paths and license-files.globs are mutually exclusive.
-
-.. code-block:: toml
-
-    [project]
-    license-files = { paths = ["..\LICENSE.MIT"] }
+    license-files = ["..\LICENSE.MIT"]
 
 Reason: ``..`` must not be used.
 ``\`` is an invalid path delimiter, ``/`` must be used.
@@ -630,7 +584,7 @@ Reason: ``..`` must not be used.
 .. code-block:: toml
 
     [project]
-    license-files = { globs = ["LICEN{CSE*"] }
+    license-files = ["LICEN{CSE*"]
 
 Reason: "LICEN{CSE*" is not a valid glob.
 
@@ -659,14 +613,9 @@ the ``license-files`` key instead.
 If the specified license ``file`` is present in the source tree,
 build tools SHOULD use it to fill the ``License-File`` field
 in the core metadata, and MUST include the specified file
-as if it were specified in a ``license-file.paths`` field.
+as if it were specified in a ``license-file`` field.
 If the file does not exist at the specified path,
 tools MUST raise an informative error as previously specified.
-However, tools MUST also still assume the
-:ref:`specified default value <639-default-patterns>`
-for the ``license-files`` key and also include,
-in addition to a license file specified under the ``license.file`` subkey,
-any license files that match the specified list of patterns.
 
 Table values for the ``license`` key MAY be removed
 from a new version of the specification in a future PEP.
@@ -751,9 +700,9 @@ and license classifiers retain backwards compatibility. A removal is
 left to a future PEP and a new version of the Core Metadata specification.
 
 Specification of the new ``License-File`` Core Metadata field and adding the
-files in the distribution codifies the existing practices of many packaging
-tools. It is designed to be largely backwards-compatible with their existing
-use of that field. The new ``license-files`` key in the ``[project]`` table of
+files in the distribution is designed to be largely backwards-compatible with
+the existing use of that field in many packaging tools.
+The new ``license-files`` key in the ``[project]`` table of
 ``pyproject.toml`` will only have an effect once users and tools adopt it.
 
 This PEP specifies that license files should be placed in a dedicated
@@ -807,7 +756,8 @@ If an invalid ``License-Expression`` is used, the users will not be able
 to publish their package to PyPI and an error message will help them
 understand they need to use SPDX identifiers.
 It will be possible to generate a distribution with incorrect license metadata,
-but not to publish one on PyPI or any other index server that enforces ``License-Expression`` validity.
+but not to publish one on PyPI or any other index server that enforces
+``License-Expression`` validity.
 For authors using the now-deprecated ``License`` field or license classifiers,
 packaging tools may warn them and inform them of the replacement,
 ``License-Expression``.
diff --git a/peps/pep-0639/appendix-examples.rst b/peps/pep-0639/appendix-examples.rst
@@ -127,29 +127,30 @@ Putting it all together, our ``setup.cfg`` would be:
         setuptools/_vendor/packaging/LICENSE.APACHE
         setuptools/_vendor/packaging/LICENSE.BSD
 
-In the ``[project]`` table of ``pyproject.toml``, with license files
-specified explicitly via the ``paths`` subkey, this would look like:
+In the ``[project]`` table of ``pyproject.toml``, license files
+can be specified via glob patterns:
 
 .. code-block:: toml
 
     [project]
     license = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
-    license-files.paths = [
-        "LICENSE",
-        "setuptools/_vendor/LICENSE",
-        "setuptools/_vendor/LICENSE.APACHE",
-        "setuptools/_vendor/LICENSE.BSD",
+    license-files = [
+        "LICENSE*",
+        "setuptools/_vendor/LICENSE*",
     ]
 
-Or alternatively, matched via glob patterns, this could be:
+Or alternatively, they can be specified explicitly (paths will be interpreted
+as glob patterns):
 
 .. code-block:: toml
 
     [project]
     license = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
-    license-files.globs = [
-        "LICENSE*",
-        "setuptools/_vendor/LICENSE*",
+    license-files = [
+        "LICENSE",
+        "setuptools/_vendor/LICENSE",
+        "setuptools/_vendor/LICENSE.APACHE",
+        "setuptools/_vendor/LICENSE.BSD",
     ]
 
 With either approach, the output Core Metadata in the distribution
@@ -211,6 +212,7 @@ Some additional examples of valid ``License-Expression`` values:
     License-Expression: GPL-3.0-only WITH Classpath-Exception-2.0 OR BSD-3-Clause
     License-Expression: LicenseRef-Public-Domain OR CC0-1.0 OR Unlicense
     License-Expression: LicenseRef-Proprietary
+    License-Expression: LicenseRef-Custom-License
 
 
 .. _packaginglicense: https://github.com/pypa/packaging/blob/21.2/LICENSE
diff --git a/peps/pep-0639/appendix-rejected-ideas.rst b/peps/pep-0639/appendix-rejected-ideas.rst
