Use new warnings in setuptools/command/editable_wheel.py

1 files changed, 66 insertions, 65 deletions

diff --git a/setuptools/command/editable_wheel.py b/setuptools/command/editable_wheel.py
index 6fddf03d..fc0f4c56 100644
--- a/setuptools/command/editable_wheel.py
+++ b/setuptools/command/editable_wheel.py
@@ -15,7 +15,6 @@ import os
 import shutil
 import sys
 import traceback
-import warnings
 from contextlib import suppress
 from enum import Enum
 from inspect import cleandoc
@@ -37,7 +36,6 @@ from typing import (
 
 from .. import (
     Command,
-    SetuptoolsDeprecationWarning,
     _normalization,
     _path,
     errors,
@@ -45,6 +43,11 @@ from .. import (
 )
 from ..discovery import find_package_path
 from ..dist import Distribution
+from ..warnings import (
+    InformationOnly,
+    SetuptoolsDeprecationWarning,
+    SetuptoolsWarning,
+)
 from .build_py import build_py as build_py_cls
 
 if TYPE_CHECKING:
@@ -84,16 +87,21 @@ class _EditableMode(Enum):
             raise errors.OptionError(f"Invalid editable mode: {mode!r}. Try: 'strict'.")
 
         if _mode == "COMPAT":
-            msg = """
-            The 'compat' editable mode is transitional and will be removed
-            in future versions of `setuptools`.
-            Please adapt your code accordingly to use either the 'strict' or the
-            'lenient' modes.
-
-            For more information, please check:
-            https://setuptools.pypa.io/en/latest/userguide/development_mode.html
-            """
-            warnings.warn(msg, SetuptoolsDeprecationWarning)
+            SetuptoolsDeprecationWarning.emit(
+                "Compat editable installs",
+                """
+                The 'compat' editable mode is transitional and will be removed
+                in future versions of `setuptools`.
+                Please adapt your code accordingly to use either the 'strict' or the
+                'lenient' modes.
+                """,
+                see_docs="userguide/development_mode.html",
+                # TODO: define due_date
+                # There is a series of shortcomings with the available editable install
+                # methods, and they are very controversial. This is something that still
+                # needs work.
+                # Moreover, `pip` is still hiding this warning, so users are not aware.
+            )
 
         return _EditableMode[_mode]
 
@@ -148,7 +156,7 @@ class editable_wheel(Command):
         except Exception:
             traceback.print_exc()
             project = self.distribution.name or self.distribution.get_name()
-            _DebuggingTips.warn(project)
+            _DebuggingTips.emit(project=project)
             raise
 
     def _ensure_dist_info(self):
@@ -289,21 +297,29 @@ class editable_wheel(Command):
         try:
             return self.run_command(cmd_name)
         except Exception:
-            msg = f"""{traceback.format_exc()}\n
-            If you are seeing this warning it is very likely that a setuptools
-            plugin or customization overrides the `{cmd_name}` command, without
-            taking into consideration how editable installs run build steps
-            starting from v64.0.0.
-
-            Plugin authors and developers relying on custom build steps are encouraged
-            to update their `{cmd_name}` implementation considering the information in
-            https://setuptools.pypa.io/en/latest/userguide/extension.html
-            about editable installs.
-
-            For the time being `setuptools` will silence this error and ignore
-            the faulty command, but this behaviour will change in future versions.\n
-            """
-            warnings.warn(msg, SetuptoolsDeprecationWarning, stacklevel=2)
+            SetuptoolsDeprecationWarning.emit(
+                "Customization incompatible with editable install",
+                f"""
+                {traceback.format_exc()}
+
+                If you are seeing this warning it is very likely that a setuptools
+                plugin or customization overrides the `{cmd_name}` command, without
+                taking into consideration how editable installs run build steps
+                starting from v64.0.0.
+
+                Plugin authors and developers relying on custom build steps are
+                encouraged to update their `{cmd_name}` implementation considering the
+                information about editable installs in
+                https://setuptools.pypa.io/en/latest/userguide/extension.html.
+
+                For the time being `setuptools` will silence this error and ignore
+                the faulty command, but this behaviour will change in future versions.
+                """,
+                # TODO: define due_date
+                # There is a series of shortcomings with the available editable install
+                # methods, and they are very controversial. This is something that still
+                # needs work.
+            )
 
     def _create_wheel_file(self, bdist_wheel):
         from wheel.wheelfile import WheelFile
@@ -468,7 +484,7 @@ class _LinkTree(_StaticPth):
         Please be careful to not remove this directory, otherwise you might not be able
         to import/use your package.
         """
-        warnings.warn(msg, InformationOnly)
+        InformationOnly.emit("Editable installation.", msg)
 
 
 class _TopLevelFinder:
@@ -505,7 +521,7 @@ class _TopLevelFinder:
         Please be careful with folders in your working directory with the same
         name as your package as they may take precedence during imports.
         """
-        warnings.warn(msg, InformationOnly)
+        InformationOnly.emit("Editable installation.", msg)
 
 
 def _can_symlink_files(base_dir: Path) -> bool:
@@ -811,46 +827,31 @@ def _finder_template(
     return _FINDER_TEMPLATE.format(name=name, mapping=mapping, namespaces=namespaces)
 
 
-class InformationOnly(UserWarning):
-    """Currently there is no clear way of displaying messages to the users
-    that use the setuptools backend directly via ``pip``.
-    The only thing that might work is a warning, although it is not the
-    most appropriate tool for the job...
-    """
-
-
 class LinksNotSupported(errors.FileError):
     """File system does not seem to support either symlinks or hard links."""
 
 
-class _DebuggingTips(InformationOnly):
-    @classmethod
-    def warn(cls, project: str):
-        msg = f"""An error happened while installing {project!r} in editable mode.
-
-        ************************************************************************
-        The following steps are recommended to help debugging this problem:
+class _DebuggingTips(SetuptoolsWarning):
+    _SUMMARY = "Problem in editable installation."
+    _DETAILS = """
+    An error happened while installing `{project}` in editable mode.
 
-        - Try to install the project normally, without using the editable mode.
-          Does the error still persists?
-          (If it does, try fixing the problem before attempting the editable mode).
-        - If you are using binary extensions, make sure you have all OS-level
-          dependencies installed (e.g. compilers, toolchains, binary libraries, ...).
-        - Try the latest version of setuptools (maybe the error was already fixed).
-        - If you (or your project dependencies) are using any setuptools extension
-          or customization, make sure they support the editable mode.
+    The following steps are recommended to help debugging this problem:
 
-        After following the steps above, if the problem still persist and
-        you think this is related to how setuptools handles editable installations,
-        please submit a reproducible example
-        (see https://stackoverflow.com/help/minimal-reproducible-example) to:
+    - Try to install the project normally, without using the editable mode.
+      Does the error still persists?
+      (If it does, try fixing the problem before attempting the editable mode).
+    - If you are using binary extensions, make sure you have all OS-level
+      dependencies installed (e.g. compilers, toolchains, binary libraries, ...).
+    - Try the latest version of setuptools (maybe the error was already fixed).
+    - If you (or your project dependencies) are using any setuptools extension
+      or customization, make sure they support the editable mode.
 
-            https://github.com/pypa/setuptools/issues
+    After following the steps above, if the problem still persist and
+    you think this is related to how setuptools handles editable installations,
+    please submit a reproducible example
+    (see https://stackoverflow.com/help/minimal-reproducible-example) to:
 
-        More information about editable installs can be found in the docs:
-
-            https://setuptools.pypa.io/en/latest/userguide/development_mode.html
-        ************************************************************************
-        """
-        # We cannot use `add_notes` since pip hides PEP 678 notes
-        warnings.warn(msg, cls, stacklevel=2)
+        https://github.com/pypa/setuptools/issues
+    """
+    _SEE_DOCS = "userguide/development_mode.html"