Overhaul for better visibility of warnings (#3849)

Author: abravalheri

setuptools/__init__.py

@@ -3,15 +3,14 @@
 import functools
 import os
 import re
-import warnings
 
 import _distutils_hack.override  # noqa: F401
 
 import distutils.core
 from distutils.errors import DistutilsOptionError
 from distutils.util import convert_path as _convert_path
 
-from ._deprecation_warning import SetuptoolsDeprecationWarning
+from .warnings import SetuptoolsDeprecationWarning
 
 import setuptools.version
 from setuptools.extension import Extension
@@ -249,14 +248,17 @@ def findall(dir=os.curdir):
 
 @functools.wraps(_convert_path)
 def convert_path(pathname):
-    from inspect import cleandoc
+    SetuptoolsDeprecationWarning.emit(
+        "Access to implementation detail",
+        """
+        The function `convert_path` is not provided by setuptools itself,
+        and therefore not part of the public API.
 
-    msg = """
-    The function `convert_path` is considered internal and not part of the public API.
-    Its direct usage by 3rd-party packages is considered deprecated and the function
-    may be removed in the future.
-    """
-    warnings.warn(cleandoc(msg), SetuptoolsDeprecationWarning)
+        Its direct usage by 3rd-party packages is considered improper and the function
+        may be removed in the future.
+        """,
+        due_date=(2023, 12, 13)  # initial deprecation 2022-03-25, see #3201
+    )
     return _convert_path(pathname)
 
 

setuptools/_deprecation_warning.py

@@ -13,14 +13,17 @@ def disable_importlib_metadata_finder(metadata):
     except ImportError:
         return
     except AttributeError:
-        import warnings
-
-        msg = (
-            "`importlib-metadata` version is incompatible with `setuptools`.\n"
-            "This problem is likely to be solved by installing an updated version of "
-            "`importlib-metadata`."
-        )
-        warnings.warn(msg)  # Ensure a descriptive message is shown.
+        from .warnings import SetuptoolsWarning
+
+        SetuptoolsWarning.emit(
+            "Incompatibility problem.",
+            """
+            `importlib-metadata` version is incompatible with `setuptools`.
+            This problem is likely to be solved by installing an updated version of
+            `importlib-metadata`.
+            """,
+            see_url="https://github.com/python/importlib_metadata/issues/396"
+        )  # Ensure a descriptive message is shown.
         raise  # This exception can be suppressed by _distutils_hack
 
     if importlib_metadata is metadata:

setuptools/_importlib.py

@@ -3,14 +3,11 @@
 and core metadata
 """
 import re
-import warnings
-from inspect import cleandoc
 from pathlib import Path
 from typing import Union
 
-from setuptools.extern import packaging
-
-from ._deprecation_warning import SetuptoolsDeprecationWarning
+from .extern import packaging
+from .warnings import SetuptoolsDeprecationWarning
 
 _Path = Union[str, Path]
 
@@ -79,18 +76,18 @@ def best_effort_version(version: str) -> str:
     try:
         return safe_version(version)
     except packaging.version.InvalidVersion:
-        msg = f"""Invalid version: {version!r}.
-        !!\n\n
-        ###################
-        # Invalid version #
-        ###################
-        {version!r} is not valid according to PEP 440.\n
-        Please make sure specify a valid version for your package.
-        Also note that future releases of setuptools may halt the build process
-        if an invalid version is given.
-        \n\n!!
-        """
-        warnings.warn(cleandoc(msg), SetuptoolsDeprecationWarning)
+        SetuptoolsDeprecationWarning.emit(
+            f"Invalid version: {version!r}.",
+            f"""
+            Version {version!r} is not valid according to PEP 440.
+
+            Please make sure to specify a valid version for your package.
+            Also note that future releases of setuptools may halt the build process
+            if an invalid version is given.
+            """,
+            see_url="https://peps.python.org/pep-0440/",
+            due_date=(2023, 9, 26),  # See setuptools/dist _validate_version
+        )
         v = version.replace(' ', '.')
         return safe_name(v)
 

setuptools/_normalization.py

@@ -43,7 +43,7 @@
 from . import errors
 from ._path import same_path
 from ._reqs import parse_strings
-from ._deprecation_warning import SetuptoolsDeprecationWarning
+from .warnings import SetuptoolsDeprecationWarning
 from distutils.util import strtobool
 
 
@@ -299,12 +299,15 @@ def _arbitrary_args(self, config_settings: _ConfigSettings) -> Iterator[str]:
         yield from self._get_config("--build-option", config_settings)
 
         if bad_args:
-            msg = f"""
-            The arguments {bad_args!r} were given via `--global-option`.
-            Please use `--build-option` instead,
-            `--global-option` is reserved to flags like `--verbose` or `--quiet`.
-            """
-            warnings.warn(msg, SetuptoolsDeprecationWarning)
+            SetuptoolsDeprecationWarning.emit(
+                "Incompatible `config_settings` passed to build backend.",
+                f"""
+                The arguments {bad_args!r} were given via `--global-option`.
+                Please use `--build-option` instead,
+                `--global-option` is reserved for flags like `--verbose` or `--quiet`.
+                """,
+                due_date=(2023, 9, 26),  # Warning introduced in v64.0.1, 11/Aug/2022.
+            )
 
 
 class _BuildMetaBackend(_ConfigSettingsTranslator):

setuptools/build_meta.py

@@ -1,7 +1,6 @@
 import distutils.command.bdist_rpm as orig
-import warnings
 
-from setuptools import SetuptoolsDeprecationWarning
+from ..warnings import SetuptoolsDeprecationWarning
 
 
 class bdist_rpm(orig.bdist_rpm):
@@ -14,10 +13,14 @@ class bdist_rpm(orig.bdist_rpm):
     """
 
     def run(self):
-        warnings.warn(
-            "bdist_rpm is deprecated and will be removed in a future "
-            "version. Use bdist_wheel (wheel packages) instead.",
-            SetuptoolsDeprecationWarning,
+        SetuptoolsDeprecationWarning.emit(
+            "Deprecated command",
+            """
+            bdist_rpm is deprecated and will be removed in a future version.
+            Use bdist_wheel (wheel packages) instead.
+            """,
+            see_url="https://github.com/pypa/setuptools/issues/1988",
+            due_date=(2023, 10, 30)  # Deprecation introduced in 22 Oct 2021.
         )
 
         # ensure distro name is up-to-date

setuptools/command/bdist_rpm.py

@@ -1,9 +1,8 @@
 import sys
-import warnings
 from typing import TYPE_CHECKING, List, Dict
 from distutils.command.build import build as _build
 
-from setuptools import SetuptoolsDeprecationWarning
+from ..warnings import SetuptoolsDeprecationWarning
 
 if sys.version_info >= (3, 8):
     from typing import Protocol
@@ -23,12 +22,16 @@ class build(_build):
     def get_sub_commands(self):
         subcommands = {cmd[0] for cmd in _build.sub_commands}
         if subcommands - _ORIGINAL_SUBCOMMANDS:
-            msg = """
-            It seems that you are using `distutils.command.build` to add
-            new subcommands. Using `distutils` directly is considered deprecated,
-            please use `setuptools.command.build`.
-            """
-            warnings.warn(msg, SetuptoolsDeprecationWarning)
+            SetuptoolsDeprecationWarning.emit(
+                "Direct usage of `distutils` commands",
+                """
+                It seems that you are using `distutils.command.build` to add
+                new subcommands. Using `distutils` directly is considered deprecated,
+                please use `setuptools.command.build`.
+                """,
+                due_date=(2023, 12, 13),  # Warning introduced in 13 Jun 2022.
+                see_url="https://peps.python.org/pep-0632/",
+            )
             self.sub_commands = _build.sub_commands
         return super().get_sub_commands()
 

setuptools/command/build.py

@@ -9,12 +9,11 @@
 import distutils.errors
 import itertools
 import stat
-import warnings
 from pathlib import Path
 from typing import Dict, Iterable, Iterator, List, Optional, Tuple
 
-from setuptools._deprecation_warning import SetuptoolsDeprecationWarning
-from setuptools.extern.more_itertools import unique_everseen
+from ..extern.more_itertools import unique_everseen
+from ..warnings import SetuptoolsDeprecationWarning
 
 
 def make_writable(target):
@@ -325,28 +324,48 @@ def assert_relative(path):
 class _IncludePackageDataAbuse:
     """Inform users that package or module is included as 'data file'"""
 
-    MESSAGE = """\
-    Installing {importable!r} as data is deprecated, please list it in `packages`.
-    !!\n\n
-    ############################
-    # Package would be ignored #
-    ############################
-    Python recognizes {importable!r} as an importable package,
-    but it is not listed in the `packages` configuration of setuptools.
-
-    {importable!r} has been automatically added to the distribution only
-    because it may contain data files, but this behavior is likely to change
-    in future versions of setuptools (and therefore is considered deprecated).
-
-    Please make sure that {importable!r} is included as a package by using
-    the `packages` configuration field or the proper discovery methods
-    (for example by using `find_namespace_packages(...)`/`find_namespace:`
-    instead of `find_packages(...)`/`find:`).
-
-    You can read more about "package discovery" and "data files" on setuptools
-    documentation page.
-    \n\n!!
-    """
+    class _Warning(SetuptoolsDeprecationWarning):
+        _SUMMARY = """
+        Package {importable!r} is absent from the `packages` configuration.
+        """
+
+        _DETAILS = """
+        ############################
+        # Package would be ignored #
+        ############################
+        Python recognizes {importable!r} as an importable package[^1],
+        but it is absent from setuptools' `packages` configuration.
+
+        This leads to an ambiguous overall configuration. If you want to distribute this
+        package, please make sure that {importable!r} is explicitly added
+        to the `packages` configuration field.
+
+        Alternatively, you can also rely on setuptools' discovery methods
+        (for example by using `find_namespace_packages(...)`/`find_namespace:`
+        instead of `find_packages(...)`/`find:`).
+
+        You can read more about "package discovery" on setuptools documentation page:
+
+        - https://setuptools.pypa.io/en/latest/userguide/package_discovery.html
+
+        If you don't want {importable!r} to be distributed and are
+        already explicitly excluding {importable!r} via
+        `find_namespace_packages(...)/find_namespace` or `find_packages(...)/find`,
+        you can try to use `exclude_package_data`, or `include-package-data=False` in
+        combination with a more fine grained `package-data` configuration.
+
+        You can read more about "package data files" on setuptools documentation page:
+
+        - https://setuptools.pypa.io/en/latest/userguide/datafiles.html
+
+
+        [^1]: For Python, any directory (with suitable naming) can be imported,
+              even if it does not contain any `.py` files.
+              On the other hand, currently there is no concept of package data
+              directory, all directories are treated like packages.
+        """
+        # _DUE_DATE: still not defined as this is particularly controversial.
+        # Warning initially introduced in May 2022. See issue #3340 for discussion.
 
     def __init__(self):
         self._already_warned = set()
@@ -363,6 +382,5 @@ def importable_subpackage(self, parent, file):
 
     def warn(self, importable):
         if importable not in self._already_warned:
-            msg = textwrap.dedent(self.MESSAGE).format(importable=importable)
-            warnings.warn(msg, SetuptoolsDeprecationWarning, stacklevel=2)
+            self._Warning.emit(importable=importable)
             self._already_warned.add(importable)

setuptools/command/build_py.py

@@ -6,14 +6,13 @@
 import os
 import shutil
 import sys
-import warnings
 from contextlib import contextmanager
 from distutils import log
 from distutils.core import Command
 from pathlib import Path
 
 from .. import _normalization
-from .._deprecation_warning import SetuptoolsDeprecationWarning
+from ..warnings import SetuptoolsDeprecationWarning
 
 
 class dist_info(Command):
@@ -51,7 +50,9 @@ def initialize_options(self):
     def finalize_options(self):
         if self.egg_base:
             msg = "--egg-base is deprecated for dist_info command. Use --output-dir."
-            warnings.warn(msg, SetuptoolsDeprecationWarning)
+            SetuptoolsDeprecationWarning.emit(msg, due_date=(2023, 9, 26))
+            # This command is internal to setuptools, therefore it should be safe
+            # to remove the deprecated support soon.
             self.output_dir = self.egg_base or self.output_dir
 
         dist = self.distribution