Deprecate tools.setuptools.license-files (pypa#4837)

Author: abravalheri

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`
                                                       (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
@@ -89,6 +89,21 @@ def _apply_tool_table(dist: Distribution, config: dict, filename: StrPath):
     if not tool_table:
         return  # short-circuit
 
+    if "license-files" in tool_table:
+        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}",
+            due_date=(2026, 2, 18),  # Warning introduced on 2025-02-18
+        )
+
     for field, value in tool_table.items():
         norm_key = json_compatible_key(field)
 

setuptools/tests/config/test_apply_pyprojecttoml.py

@@ -375,7 +375,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")
 
@@ -390,6 +390,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
 
@@ -405,7 +407,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"
 
@@ -421,6 +425,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())