diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index 41d30c33d4..6fe03c6d89 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -85,11 +85,21 @@ extensions). ``url`` A string specifying the URL for the package homepage. + .. warning:: + ``url`` is deprecated as it generates the ``Home-page`` metadata. + Please use ``project_urls`` instead, with the relevant labels. + See :pep:`753`. + .. _keyword/download_url: ``download_url`` A string specifying the URL to download the package. + .. warning:: + ``download_url`` is deprecated as it generates the ``Download-URL`` metadata. + Please use ``project_urls`` instead, with the relevant labels. + See :pep:`753`. + .. _keyword/packages: ``packages`` @@ -257,14 +267,14 @@ extensions). ``requires`` .. warning:: - ``requires`` is superseded by ``install_requires`` and should not be used - anymore. + ``requires`` is deprecated and superseded by ``install_requires``. + It should not be used anymore. .. _keyword/obsoletes: ``obsoletes`` .. warning:: - ``obsoletes`` is currently ignored by ``pip``. + ``obsoletes`` is deprecated and currently ignored by ``pip``. List of strings describing packages which this package renders obsolete, meaning that the two projects should not be installed at the same time. @@ -283,7 +293,7 @@ extensions). ``provides`` .. warning:: - ``provides`` is currently ignored by ``pip``. + ``provides`` is currently considered deprecated and is ignored by ``pip``. List of strings describing package- and virtual package names contained within this package. diff --git a/setuptools/dist.py b/setuptools/dist.py index 0249651267..97f6859c0f 100644 --- a/setuptools/dist.py +++ b/setuptools/dist.py @@ -231,6 +231,18 @@ def check_packages(dist, attr, value): ) +def _check_deprecated_metadata_field( + dist: Distribution, attr: str, value: object +) -> None: + if value: + SetuptoolsDeprecationWarning.emit( + f"Deprecated usage of `{attr}` in setuptools configuration.", + see_docs=f"references/keywords.html#keyword-{attr.replace('_', '-')}", + due_date=(2027, 1, 25), + # Warning initially introduced in 14 Jan 2025 + ) + + if TYPE_CHECKING: # Work around a mypy issue where type[T] can't be used as a base: https://github.com/python/mypy/issues/10962 from distutils.core import Distribution as _Distribution @@ -294,6 +306,14 @@ class Distribution(_Distribution): 'extras_require': dict, } + _DEPRECATED_FIELDS = ( + "url", + "download_url", + "requires", + "provides", + "obsoletes", + ) + # Used by build_py, editable_wheel and install_lib commands for legacy namespaces namespace_packages: list[str] #: :meta private: DEPRECATED @@ -318,6 +338,9 @@ def __init__(self, attrs: MutableMapping[str, Any] | None = None) -> None: dist_attrs = {k: v for k, v in attrs.items() if k not in metadata_only} _Distribution.__init__(self, dist_attrs) + for attr in self._DEPRECATED_FIELDS: + _check_deprecated_metadata_field(self, attr, dist_attrs.get(attr)) + # Private API (setuptools-use only, not restricted to Distribution) # Stores files that are referenced by the configuration and need to be in the # sdist (e.g. `version = file: VERSION.txt`) diff --git a/setuptools/tests/test_dist.py b/setuptools/tests/test_dist.py index 533eb9f45e..2524a92e93 100644 --- a/setuptools/tests/test_dist.py +++ b/setuptools/tests/test_dist.py @@ -5,7 +5,7 @@ import pytest -from setuptools import Distribution +from setuptools import Distribution, SetuptoolsDeprecationWarning from setuptools.dist import check_package_data, check_specifier from .test_easy_install import make_nspkg_sdist @@ -276,3 +276,22 @@ def test_dist_default_name(tmp_path, dist_name, package_dir, package_files): dist.set_defaults() assert dist.py_modules or dist.packages assert dist.get_name() == dist_name + + +@pytest.mark.parametrize( + ("field", "value"), + [ + ("requires", ["setuptools"]), + ("provides", ["setuptools"]), + ("obsoletes", ["setuptools"]), + ("url", "www.setuptools.com.br"), + ("download_url", "www.setuptools.com.br/42"), + ], +) +def test_deprecated_fields(tmpdir_cwd, field, value): + """See discussion in https://github.com/pypa/setuptools/issues/4797""" + attrs = {"name": "test", "version": "0.42", field: value} + match = f"Deprecated usage of `{field}`" + with pytest.warns(SetuptoolsDeprecationWarning, match=match): + dist = Distribution(attrs) + assert getattr(dist.metadata, field, None) == value