Overhaul for better visibility of warnings (#3849)

3 files changed, 117 insertions, 16 deletions

diff --git a/setuptools/tests/config/test_apply_pyprojecttoml.py b/setuptools/tests/config/test_apply_pyprojecttoml.py
index 0a814a34..c9c521be 100644
--- a/setuptools/tests/config/test_apply_pyprojecttoml.py
+++ b/setuptools/tests/config/test_apply_pyprojecttoml.py
@@ -15,12 +15,12 @@ import pytest
 from ini2toml.api import Translator
 
 import setuptools  # noqa ensure monkey patch to metadata
-from setuptools._deprecation_warning import SetuptoolsDeprecationWarning
 from setuptools.dist import Distribution
 from setuptools.config import setupcfg, pyprojecttoml
 from setuptools.config import expand
 from setuptools.config._apply_pyprojecttoml import _WouldIgnoreField, _some_attrgetter
 from setuptools.command.egg_info import write_requirements
+from setuptools.warnings import SetuptoolsDeprecationWarning
 
 from .downloads import retrieve_file, urls_from_file
 
diff --git a/setuptools/tests/config/test_setupcfg.py b/setuptools/tests/config/test_setupcfg.py
index a47138c8..69b75a89 100644
--- a/setuptools/tests/config/test_setupcfg.py
+++ b/setuptools/tests/config/test_setupcfg.py
@@ -7,10 +7,10 @@ from unittest.mock import Mock, patch
 import pytest
 
 from distutils.errors import DistutilsOptionError, DistutilsFileError
-from setuptools._deprecation_warning import SetuptoolsDeprecationWarning
 from setuptools.dist import Distribution, _Distribution
 from setuptools.config.setupcfg import ConfigHandler, read_configuration
 from setuptools.extern.packaging.requirements import InvalidRequirement
+from setuptools.warnings import SetuptoolsDeprecationWarning
 from ..textwrap import DALS
 
 
@@ -468,12 +468,8 @@ class TestMetadata:
             'author-email = test@test.com\n'
             'maintainer_email = foo@foo.com\n',
         )
-        msg = (
-            "Usage of dash-separated 'author-email' will not be supported "
-            "in future versions. "
-            "Please use the underscore name 'author_email' instead"
-        )
-        with pytest.warns(UserWarning, match=msg):
+        msg = "Usage of dash-separated 'author-email' will not be supported"
+        with pytest.warns(SetuptoolsDeprecationWarning, match=msg):
             with get_dist(tmpdir) as dist:
                 metadata = dist.metadata
 
@@ -486,12 +482,8 @@ class TestMetadata:
         fake_env(
             tmpdir, '[metadata]\n' 'Name = foo\n' 'description = Some description\n'
         )
-        msg = (
-            "Usage of uppercase key 'Name' in 'metadata' will be deprecated in "
-            "future versions. "
-            "Please use lowercase 'name' instead"
-        )
-        with pytest.warns(UserWarning, match=msg):
+        msg = "Usage of uppercase key 'Name' in 'metadata' will not be supported"
+        with pytest.warns(SetuptoolsDeprecationWarning, match=msg):
             with get_dist(tmpdir) as dist:
                 metadata = dist.metadata
 
@@ -755,7 +747,7 @@ class TestOptions:
             r"One of the parsed requirements in `(install_requires|extras_require.+)` "
             "looks like a valid environment marker.*"
         )
-        with pytest.warns(UserWarning, match=match):
+        with pytest.warns(SetuptoolsDeprecationWarning, match=match):
             with get_dist(tmpdir) as _:
                 pass
 
@@ -774,12 +766,14 @@ class TestOptions:
             "[options]\ninstall_requires =\n    bar\n    python_version<3\n",
         ],
     )
+    @pytest.mark.filterwarnings("error::setuptools.SetuptoolsDeprecationWarning")
     def test_nowarn_accidental_env_marker_misconfig(self, config, tmpdir, recwarn):
         fake_env(tmpdir, config)
+        num_warnings = len(recwarn)
         with get_dist(tmpdir) as _:
             pass
         # The examples are valid, no warnings shown
-        assert not any(w.category == UserWarning for w in recwarn)
+        assert len(recwarn) == num_warnings
 
     def test_dash_preserved_extras_require(self, tmpdir):
         fake_env(tmpdir, '[options.extras_require]\n' 'foo-a = foo\n' 'foo_b = test\n')
diff --git a/setuptools/tests/test_warnings.py b/setuptools/tests/test_warnings.py
new file mode 100644
index 00000000..013e2526
--- /dev/null
+++ b/setuptools/tests/test_warnings.py
@@ -0,0 +1,107 @@
+from inspect import cleandoc
+
+import pytest
+
+from setuptools.warnings import SetuptoolsDeprecationWarning, SetuptoolsWarning
+
+
+_EXAMPLES = {
+    "default": dict(
+        args=("Hello {x}", "\n\t{target} {v:.1f}"),
+        kwargs={"x": 5, "v": 3, "target": "World"},
+        expected = """
+    Hello 5
+    !!
+
+            ********************************************************************************
+            World 3.0
+            ********************************************************************************
+
+    !!
+    """  # noqa,
+    ),
+    "futue_due_date": dict(
+        args=("Summary", "Lorem ipsum"),
+        kwargs={"due_date": (9999, 11, 22)},
+        expected = """
+    Summary
+    !!
+
+            ********************************************************************************
+            Lorem ipsum
+
+            By 9999-Nov-22, you need to update your project and remove deprecated calls
+            or your builds will no longer be supported.
+            ********************************************************************************
+
+    !!
+    """  # noqa
+    ),
+    "past_due_date_with_docs": dict(
+        args=("Summary", "Lorem ipsum"),
+        kwargs={"due_date": (2000, 11, 22), "see_docs": "some_page.html"},
+        expected="""
+    Summary
+    !!
+
+            ********************************************************************************
+            Lorem ipsum
+
+            This deprecation is overdue, please update your project and remove deprecated
+            calls to avoid build errors in the future.
+
+            See https://setuptools.pypa.io/en/latest/some_page.html for details.
+            ********************************************************************************
+
+    !!
+    """ # noqa
+    ),
+}
+
+
+@pytest.mark.parametrize("example_name", _EXAMPLES.keys())
+def test_formatting(monkeypatch, example_name):
+    """
+    It should automatically handle indentation, interpolation and things like due date.
+    """
+    args = _EXAMPLES[example_name]["args"]
+    kwargs = _EXAMPLES[example_name]["kwargs"]
+    expected = _EXAMPLES[example_name]["expected"]
+
+    monkeypatch.setenv("SETUPTOOLS_ENFORCE_DEPRECATION", "false")
+    with pytest.warns(SetuptoolsWarning) as warn_info:
+        SetuptoolsWarning.emit(*args, **kwargs)
+    assert _get_message(warn_info) == cleandoc(expected)
+
+
+def test_due_date_enforcement(monkeypatch):
+    class _MyDeprecation(SetuptoolsDeprecationWarning):
+        _SUMMARY = "Summary"
+        _DETAILS = "Lorem ipsum"
+        _DUE_DATE = (2000, 11, 22)
+        _SEE_DOCS = "some_page.html"
+
+    monkeypatch.setenv("SETUPTOOLS_ENFORCE_DEPRECATION", "true")
+    with pytest.raises(SetuptoolsDeprecationWarning) as exc_info:
+        _MyDeprecation.emit()
+
+    expected="""
+    Summary
+    !!
+
+            ********************************************************************************
+            Lorem ipsum
+
+            This deprecation is overdue, please update your project and remove deprecated
+            calls to avoid build errors in the future.
+
+            See https://setuptools.pypa.io/en/latest/some_page.html for details.
+            ********************************************************************************
+
+    !!
+    """ # noqa
+    assert str(exc_info.value) == cleandoc(expected)
+
+
+def _get_message(warn_info):
+    return next(warn.message.args[0] for warn in warn_info)