Deprecate tools.setuptools.license-files

Author: cdce8p

docs/userguide/miscellaneous.rst

@@ -24,7 +24,7 @@ files are included in a source distribution by default:
   in ``pyproject.toml`` and/or equivalent in ``setup.cfg``/``setup.py``;
   note that if you don't explicitly set this parameter, ``setuptools``
   will include any files that match the following glob patterns:
-  ``LICENSE*``, ``LICENCE*``, ``COPYING*``, ``NOTICE*``, ``AUTHORS**``;
+  ``LICEN[CS]E*``, ``COPYING*``, ``NOTICE*``, ``AUTHORS**``;
 - ``pyproject.toml``;
 - ``setup.cfg``;
 - ``setup.py``;

docs/userguide/pyproject_config.rst

@@ -99,7 +99,7 @@ Key                       Value Type (TOML)           Notes
                                                       See :doc:`/userguide/datafiles`.
 ``exclude-package-data``  table/inline-table          Empty by default. See :doc:`/userguide/datafiles`.
 ------------------------- --------------------------- -------------------------
-``license-files``         array of glob patterns      **Provisional** - likely to change with :pep:`639`
+``license-files``         array of glob patterns      **Deprecated** - use ``project.license-files`` instead. See :doc:`PyPUG:guides/writing-pyproject-toml/#license-files`
                                                       (by default: ``['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*']``)
 ``data-files``            table/inline-table          **Discouraged** - check :doc:`/userguide/datafiles`.
                                                       Whenever possible, consider using data files inside the package directories.

newsfragments/4837.feature.rst

@@ -0,0 +1,3 @@
+Deprecated ``tools.setuptools.license-files`` in favor of ``project.license-files``
+and added exception if ``project.license-files`` and ``tools.setuptools.license-files``
+are used together. -- by :user:`cdce8p`

setuptools/config/_apply_pyprojecttoml.py

@@ -22,9 +22,9 @@
 
 from .. import _static
 from .._path import StrPath
-from ..errors import RemovedConfigError
+from ..errors import InvalidConfigError, RemovedConfigError
 from ..extension import Extension
-from ..warnings import SetuptoolsWarning
+from ..warnings import SetuptoolsDeprecationWarning, SetuptoolsWarning
 
 if TYPE_CHECKING:
     from typing_extensions import TypeAlias
@@ -100,6 +100,23 @@ def _apply_tool_table(dist: Distribution, config: dict, filename: StrPath):
             """
             raise RemovedConfigError("\n".join([cleandoc(msg), suggestion]))
 
+        if norm_key == "license_files":
+            if dist.metadata.license_files:
+                raise InvalidConfigError(
+                    "'project.license-files' is defined already. "
+                    "Remove 'tool.setuptools.license-files'."
+                )
+
+            pypa_guides = "guides/writing-pyproject-toml/#license-files"
+            SetuptoolsDeprecationWarning.emit(
+                "'tool.setuptools.license-files' is deprecated in favor of "
+                "'project.license-files'",
+                see_url=f"https://packaging.python.org/en/latest/{pypa_guides}",
+            )
+            # Warning introduced on 2025-02-18
+            # TODO: Should we add a due date? It may affect old/unmaintained
+            #       packages in the ecosystem and cause problems...
+
         norm_key = TOOL_TABLE_RENAMES.get(norm_key, norm_key)
         corresp = TOOL_TABLE_CORRESPONDENCE.get(norm_key, norm_key)
         if callable(corresp):

setuptools/tests/config/test_apply_pyprojecttoml.py

@@ -24,7 +24,7 @@
 from setuptools.config import expand, pyprojecttoml, setupcfg
 from setuptools.config._apply_pyprojecttoml import _MissingDynamic, _some_attrgetter
 from setuptools.dist import Distribution
-from setuptools.errors import RemovedConfigError
+from setuptools.errors import InvalidConfigError, RemovedConfigError
 from setuptools.warnings import SetuptoolsDeprecationWarning
 
 from .downloads import retrieve_file, urls_from_file
@@ -366,7 +366,7 @@ def base_pyproject(self, tmp_path, additional_text):
         pyproject.write_text(text, encoding="utf-8")
         return pyproject
 
-    def base_pyproject_license_pep639(self, tmp_path):
+    def base_pyproject_license_pep639(self, tmp_path, additional_text=""):
         pyproject = _pep621_example_project(tmp_path, "README")
         text = pyproject.read_text(encoding="utf-8")
 
@@ -381,6 +381,8 @@ def base_pyproject_license_pep639(self, tmp_path):
             text,
             count=1,
         )
+        if additional_text:
+            text = f"{text}\n{additional_text}\n"
         pyproject.write_text(text, encoding="utf-8")
         return pyproject
 
@@ -396,7 +398,9 @@ def test_both_license_and_license_files_defined(self, tmp_path):
         license = tmp_path / "LICENSE.txt"
         license.write_text("LicenseRef-Proprietary\n", encoding="utf-8")
 
-        dist = pyprojecttoml.apply_configuration(makedist(tmp_path), pyproject)
+        msg = "'tool.setuptools.license-files' is deprecated in favor of 'project.license-files'"
+        with pytest.warns(SetuptoolsDeprecationWarning, match=msg):
+            dist = pyprojecttoml.apply_configuration(makedist(tmp_path), pyproject)
         assert set(dist.metadata.license_files) == {"_FILE.rst", "_FILE.txt"}
         assert dist.metadata.license == "LicenseRef-Proprietary\n"
 
@@ -412,6 +416,15 @@ def test_both_license_and_license_files_defined_pep639(self, tmp_path):
         assert dist.metadata.license is None
         assert dist.metadata.license_expression == "LicenseRef-Proprietary"
 
+    def test_license_files_defined_twice(self, tmp_path):
+        # Set project.license-files and tools.setuptools.license-files
+        setuptools_config = '[tool.setuptools]\nlicense-files = ["_FILE*"]'
+        pyproject = self.base_pyproject_license_pep639(tmp_path, setuptools_config)
+
+        msg = "'project.license-files' is defined already. Remove 'tool.setuptools.license-files'"
+        with pytest.raises(InvalidConfigError, match=msg):
+            pyprojecttoml.apply_configuration(makedist(tmp_path), pyproject)
+
     def test_default_patterns(self, tmp_path):
         setuptools_config = '[tool.setuptools]\nzip-safe = false'
         # ^ used just to trigger section validation

setuptools/tests/test_build_meta.py

@@ -6,6 +6,7 @@
 import signal
 import sys
 import tarfile
+import warnings
 from concurrent import futures
 from pathlib import Path
 from typing import Any, Callable
@@ -15,6 +16,8 @@
 from jaraco import path
 from packaging.requirements import Requirement
 
+from setuptools.warnings import SetuptoolsDeprecationWarning
+
 from .textwrap import DALS
 
 SETUP_SCRIPT_STUB = "__import__('setuptools').setup()"
@@ -384,8 +387,11 @@ def test_build_with_pyproject_config(self, tmpdir, setup_script):
         build_backend = self.get_build_backend()
         with tmpdir.as_cwd():
             path.build(files)
-            sdist_path = build_backend.build_sdist("temp")
-            wheel_file = build_backend.build_wheel("temp")
+            with warnings.catch_warnings():
+                msg = "'tool.setuptools.license-files' is deprecated in favor of 'project.license-files'"
+                warnings.filterwarnings("ignore", msg, SetuptoolsDeprecationWarning)
+                sdist_path = build_backend.build_sdist("temp")
+                wheel_file = build_backend.build_wheel("temp")
 
         with tarfile.open(os.path.join(tmpdir, "temp", sdist_path)) as tar:
             sdist_contents = set(tar.getnames())