Change deprecation warnings into errors for 7.0 release, using a new mechanism (#9309)

changelog/7480.improvement.rst

@@ -0,0 +1,5 @@
+A deprecation scheduled to be removed in a major version X (e.g. pytest 7, 8, 9, ...) now uses warning category `PytestRemovedInXWarning`,
+a subclass of :class:`~pytest.PytestDeprecationWarning`,
+instead of :class:`PytestDeprecationWarning` directly.
+
+See :ref:`backwards-compatibility` for more details.

changelog/9308.breaking.rst

@@ -0,0 +1,22 @@
+**PytestRemovedIn7Warning deprecation warnings are now errors by default.**
+
+Following our plan to remove deprecated features with as little disruption as
+possible, all warnings of type ``PytestRemovedIn7Warning `` now generate errors
+instead of warning messages by default.
+
+**The affected features will be effectively removed in pytest 7.1**, so please consult the
+:ref:`deprecations` section in the docs for directions on how to update existing code.
+
+In the pytest ``7.0.X`` series, it is possible to change the errors back into warnings as a
+stopgap measure by adding this to your ``pytest.ini`` file:
+
+.. code-block:: ini
+
+    [pytest]
+    filterwarnings =
+        ignore::pytest.PytestRemovedIn7Warning
+
+But this will stop working when pytest ``7.1`` is released.
+
+**If you have concerns** about the removal of a specific feature, please add a
+comment to :issue:`9308`.

doc/en/backwards-compatibility.rst

@@ -22,7 +22,9 @@ b) transitional: the old and new API don't conflict
 
    We will only start the removal of deprecated functionality in major releases (e.g. if we deprecate something in 3.0 we will start to remove it in 4.0), and keep it around for at least two minor releases (e.g. if we deprecate something in 3.9 and 4.0 is the next release, we start to remove it in 5.0, not in 4.0).
 
-   When the deprecation expires (e.g. 4.0 is released), we won't remove the deprecated functionality immediately, but will use the standard warning filters to turn them into **errors** by default. This approach makes it explicit that removal is imminent, and still gives you time to turn the deprecated feature into a warning instead of an error so it can be dealt with in your own time. In the next minor release (e.g. 4.1), the feature will be effectively removed.
+   A deprecated feature scheduled to be removed in major version X will use the warning class `PytestRemovedInXWarning` (a subclass of `~pytest.PytestDeprecationwarning`).
+
+   When the deprecation expires (e.g. 4.0 is released), we won't remove the deprecated functionality immediately, but will use the standard warning filters to turn `PytestRemovedInXWarning` (e.g. `PytestRemovedIn4Warning`) into **errors** by default. This approach makes it explicit that removal is imminent, and still gives you time to turn the deprecated feature into a warning instead of an error so it can be dealt with in your own time. In the next minor release (e.g. 4.1), the feature will be effectively removed.
 
 
 c) true breakage: should only be considered when normal transition is unreasonably unsustainable and would offset important development/features by years.

src/_pytest/deprecated.py

@@ -11,6 +11,8 @@ in case of warnings which need to format their messages.
 from warnings import warn
 
 from _pytest.warning_types import PytestDeprecationWarning
+from _pytest.warning_types import PytestRemovedIn7Warning
+from _pytest.warning_types import PytestRemovedIn8Warning
 from _pytest.warning_types import UnformattedWarning
 
 # set of plugins which have been integrated into the core; we use this list to ignore
@@ -23,63 +25,66 @@ DEPRECATED_EXTERNAL_PLUGINS = {
 
 
 FILLFUNCARGS = UnformattedWarning(
-    PytestDeprecationWarning,
+    PytestRemovedIn7Warning,
     "{name} is deprecated, use "
     "function._request._fillfixtures() instead if you cannot avoid reaching into internals.",
 )
 
 PYTEST_COLLECT_MODULE = UnformattedWarning(
-    PytestDeprecationWarning,
+    PytestRemovedIn7Warning,
     "pytest.collect.{name} was moved to pytest.{name}\n"
     "Please update to the new name.",
 )
 
+# This can be* removed pytest 8, but it's harmless and common, so no rush to remove.
+# * If you're in the future: "could have been".
 YIELD_FIXTURE = PytestDeprecationWarning(
     "@pytest.yield_fixture is deprecated.\n"
     "Use @pytest.fixture instead; they are the same."
 )
 
-MINUS_K_DASH = PytestDeprecationWarning(
+MINUS_K_DASH = PytestRemovedIn7Warning(
     "The `-k '-expr'` syntax to -k is deprecated.\nUse `-k 'not expr'` instead."
 )
 
-MINUS_K_COLON = PytestDeprecationWarning(
+MINUS_K_COLON = PytestRemovedIn7Warning(
     "The `-k 'expr:'` syntax to -k is deprecated.\n"
     "Please open an issue if you use this and want a replacement."
 )
 
-WARNING_CAPTURED_HOOK = PytestDeprecationWarning(
+WARNING_CAPTURED_HOOK = PytestRemovedIn7Warning(
     "The pytest_warning_captured is deprecated and will be removed in a future release.\n"
     "Please use pytest_warning_recorded instead."
 )
 
-WARNING_CMDLINE_PREPARSE_HOOK = PytestDeprecationWarning(
+WARNING_CMDLINE_PREPARSE_HOOK = PytestRemovedIn8Warning(
     "The pytest_cmdline_preparse hook is deprecated and will be removed in a future release. \n"
     "Please use pytest_load_initial_conftests hook instead."
 )
 
-FSCOLLECTOR_GETHOOKPROXY_ISINITPATH = PytestDeprecationWarning(
+FSCOLLECTOR_GETHOOKPROXY_ISINITPATH = PytestRemovedIn8Warning(
     "The gethookproxy() and isinitpath() methods of FSCollector and Package are deprecated; "
     "use self.session.gethookproxy() and self.session.isinitpath() instead. "
 )
 
-STRICT_OPTION = PytestDeprecationWarning(
+STRICT_OPTION = PytestRemovedIn8Warning(
     "The --strict option is deprecated, use --strict-markers instead."
 )
 
+# This deprecation is never really meant to be removed.
 PRIVATE = PytestDeprecationWarning("A private pytest class or function was used.")
 
-UNITTEST_SKIP_DURING_COLLECTION = PytestDeprecationWarning(
+UNITTEST_SKIP_DURING_COLLECTION = PytestRemovedIn8Warning(
     "Raising unittest.SkipTest to skip tests during collection is deprecated. "
     "Use pytest.skip() instead."
 )
 
-ARGUMENT_PERCENT_DEFAULT = PytestDeprecationWarning(
+ARGUMENT_PERCENT_DEFAULT = PytestRemovedIn8Warning(
     'pytest now uses argparse. "%default" should be changed to "%(default)s"',
 )
 
 ARGUMENT_TYPE_STR_CHOICE = UnformattedWarning(
-    PytestDeprecationWarning,
+    PytestRemovedIn8Warning,
     "`type` argument to addoption() is the string {typ!r}."
     " For choices this is optional and can be omitted, "
     " but when supplied should be a type (for example `str` or `int`)."
@@ -87,7 +92,7 @@ ARGUMENT_TYPE_STR_CHOICE = UnformattedWarning(
 )
 
 ARGUMENT_TYPE_STR = UnformattedWarning(
-    PytestDeprecationWarning,
+    PytestRemovedIn8Warning,
     "`type` argument to addoption() is the string {typ!r}, "
     " but when supplied should be a type (for example `str` or `int`)."
     " (options: {names})",
@@ -95,31 +100,31 @@ ARGUMENT_TYPE_STR = UnformattedWarning(
 
 
 HOOK_LEGACY_PATH_ARG = UnformattedWarning(
-    PytestDeprecationWarning,
+    PytestRemovedIn8Warning,
     "The ({pylib_path_arg}: py.path.local) argument is deprecated, please use ({pathlib_path_arg}: pathlib.Path)\n"
     "see https://docs.pytest.org/en/latest/deprecations.html"
     "#py-path-local-arguments-for-hooks-replaced-with-pathlib-path",
 )
 
 NODE_CTOR_FSPATH_ARG = UnformattedWarning(
-    PytestDeprecationWarning,
+    PytestRemovedIn8Warning,
     "The (fspath: py.path.local) argument to {node_type_name} is deprecated. "
     "Please use the (path: pathlib.Path) argument instead.\n"
     "See https://docs.pytest.org/en/latest/deprecations.html"
     "#fspath-argument-for-node-constructors-replaced-with-pathlib-path",
 )
 
-WARNS_NONE_ARG = PytestDeprecationWarning(
+WARNS_NONE_ARG = PytestRemovedIn8Warning(
     "Passing None to catch any warning has been deprecated, pass no arguments instead:\n"
     " Replace pytest.warns(None) by simply pytest.warns()."
 )
 
 KEYWORD_MSG_ARG = UnformattedWarning(
-    PytestDeprecationWarning,
+    PytestRemovedIn8Warning,
     "pytest.{func}(msg=...) is now deprecated, use pytest.{func}(reason=...) instead",
 )
 
-INSTANCE_COLLECTOR = PytestDeprecationWarning(
+INSTANCE_COLLECTOR = PytestRemovedIn8Warning(
     "The pytest.Instance collector type is deprecated and is no longer used. "
     "See https://docs.pytest.org/en/latest/deprecations.html#the-pytest-instance-collector",
 )

src/_pytest/warning_types.py

@@ -42,13 +42,26 @@ class PytestCollectionWarning(PytestWarning):
     __module__ = "pytest"
 
 
-@final
 class PytestDeprecationWarning(PytestWarning, DeprecationWarning):
     """Warning class for features that will be removed in a future version."""
 
     __module__ = "pytest"
 
 
+@final
+class PytestRemovedIn7Warning(PytestDeprecationWarning):
+    """Warning class for features that will be removed in pytest 7."""
+
+    __module__ = "pytest"
+
+
+@final
+class PytestRemovedIn8Warning(PytestDeprecationWarning):
+    """Warning class for features that will be removed in pytest 8."""
+
+    __module__ = "pytest"
+
+
 @final
 class PytestExperimentalApiWarning(PytestWarning, FutureWarning):
     """Warning category used to denote experiments in pytest.

src/_pytest/warnings.py

@@ -49,6 +49,8 @@ def catch_warnings_for_item(
             warnings.filterwarnings("always", category=DeprecationWarning)
             warnings.filterwarnings("always", category=PendingDeprecationWarning)
 
+        warnings.filterwarnings("error", category=pytest.PytestRemovedIn7Warning)
+
         apply_warning_filters(config_filters, cmdline_filters)
 
         # apply filters from "filterwarnings" marks

src/pytest/__init__.py

@@ -68,6 +68,8 @@ from _pytest.warning_types import PytestCollectionWarning
 from _pytest.warning_types import PytestConfigWarning
 from _pytest.warning_types import PytestDeprecationWarning
 from _pytest.warning_types import PytestExperimentalApiWarning
+from _pytest.warning_types import PytestRemovedIn7Warning
+from _pytest.warning_types import PytestRemovedIn8Warning
 from _pytest.warning_types import PytestUnhandledCoroutineWarning
 from _pytest.warning_types import PytestUnhandledThreadExceptionWarning
 from _pytest.warning_types import PytestUnknownMarkWarning
@@ -127,6 +129,8 @@ __all__ = [
     "PytestConfigWarning",
     "PytestDeprecationWarning",
     "PytestExperimentalApiWarning",
+    "PytestRemovedIn7Warning",
+    "PytestRemovedIn8Warning",
     "Pytester",
     "PytestPluginManager",
     "PytestUnhandledCoroutineWarning",

testing/deprecated_test.py

@@ -115,7 +115,7 @@ def test_strict_option_is_deprecated(pytester: Pytester) -> None:
     result.stdout.fnmatch_lines(
         [
             "'unknown' not found in `markers` configuration option",
-            "*PytestDeprecationWarning: The --strict option is deprecated, use --strict-markers instead.",
+            "*PytestRemovedIn8Warning: The --strict option is deprecated, use --strict-markers instead.",
         ]
     )
 
@@ -154,7 +154,7 @@ def test_raising_unittest_skiptest_during_collection_is_deprecated(
     result = pytester.runpytest()
     result.stdout.fnmatch_lines(
         [
-            "*PytestDeprecationWarning: Raising unittest.SkipTest*",
+            "*PytestRemovedIn8Warning: Raising unittest.SkipTest*",
         ]
     )
 
@@ -213,7 +213,7 @@ class TestSkipMsgArgumentDeprecated:
         result = pytester.runpytest(p)
         result.stdout.fnmatch_lines(
             [
-                "*PytestDeprecationWarning: pytest.skip(msg=...) is now deprecated, "
+                "*PytestRemovedIn8Warning: pytest.skip(msg=...) is now deprecated, "
                 "use pytest.skip(reason=...) instead",
                 '*pytest.skip(msg="skippedmsg")*',
             ]
@@ -232,7 +232,7 @@ class TestSkipMsgArgumentDeprecated:
         result = pytester.runpytest(p)
         result.stdout.fnmatch_lines(
             [
-                "*PytestDeprecationWarning: pytest.fail(msg=...) is now deprecated, "
+                "*PytestRemovedIn8Warning: pytest.fail(msg=...) is now deprecated, "
                 "use pytest.fail(reason=...) instead",
                 '*pytest.fail(msg="failedmsg")',
             ]
@@ -251,7 +251,7 @@ class TestSkipMsgArgumentDeprecated:
         result = pytester.runpytest(p)
         result.stdout.fnmatch_lines(
             [
-                "*PytestDeprecationWarning: pytest.exit(msg=...) is now deprecated, "
+                "*PytestRemovedIn8Warning: pytest.exit(msg=...) is now deprecated, "
                 "use pytest.exit(reason=...) instead",
             ]
         )
@@ -269,7 +269,7 @@ def test_deprecation_of_cmdline_preparse(pytester: Pytester) -> None:
     result = pytester.runpytest()
     result.stdout.fnmatch_lines(
         [
-            "*PytestDeprecationWarning: The pytest_cmdline_preparse hook is deprecated*",
+            "*PytestRemovedIn8Warning: The pytest_cmdline_preparse hook is deprecated*",
             "*Please use pytest_load_initial_conftests hook instead.*",
         ]
     )

testing/test_mark.py

@@ -831,7 +831,9 @@ class TestKeywordSelection:
             def test_three(): assert 1
         """
         )
-        reprec = pytester.inline_run("-k", "test_two:", threepass)
+        reprec = pytester.inline_run(
+            "-Wignore::pytest.PytestRemovedIn7Warning", "-k", "test_two:", threepass
+        )
         passed, skipped, failed = reprec.listoutcomes()
         assert len(passed) == 2
         assert not failed

testing/test_terminal.py

@@ -682,7 +682,9 @@ class TestTerminalFunctional:
                     pass
            """
         )
-        result = pytester.runpytest("-k", "test_two:", testpath)
+        result = pytester.runpytest(
+            "-Wignore::pytest.PytestRemovedIn7Warning", "-k", "test_two:", testpath
+        )
         result.stdout.fnmatch_lines(
             ["collected 3 items / 1 deselected / 2 selected", "*test_deselected.py ..*"]
         )

testing/test_warnings.py

@@ -518,11 +518,8 @@ class TestDeprecationWarningsByDefault:
 
 
 @pytest.mark.parametrize("change_default", [None, "ini", "cmdline"])
-@pytest.mark.skip(
+def test_removed_in_x_warning_as_error(pytester: Pytester, change_default) -> None:
-    reason="This test should be enabled again before pytest 7.0 is released"
+    """This ensures that PytestRemovedInXWarnings raised by pytest are turned into errors.
-)
-def test_deprecation_warning_as_error(pytester: Pytester, change_default) -> None:
-    """This ensures that PytestDeprecationWarnings raised by pytest are turned into errors.
 
     This test should be enabled as part of each major release, and skipped again afterwards
     to ensure our deprecations are turning into warnings as expected.
@@ -531,7 +528,7 @@ def test_deprecation_warning_as_error(pytester: Pytester, change_default) -> Non
         """
         import warnings, pytest
         def test():
-            warnings.warn(pytest.PytestDeprecationWarning("some warning"))
+            warnings.warn(pytest.PytestRemovedIn7Warning("some warning"))
     """
     )
     if change_default == "ini":
@@ -539,12 +536,12 @@ def test_deprecation_warning_as_error(pytester: Pytester, change_default) -> Non
             """
             [pytest]
             filterwarnings =
-                ignore::pytest.PytestDeprecationWarning
+                ignore::pytest.PytestRemovedIn7Warning
         """
         )
 
     args = (
-        ("-Wignore::pytest.PytestDeprecationWarning",)
+        ("-Wignore::pytest.PytestRemovedIn7Warning",)
         if change_default == "cmdline"
         else ()
     )