From 128f29ee353550958826993cb788e99daa3461b3 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sun, 14 Nov 2021 23:11:22 +0200 Subject: [PATCH 1/2] Categorize deprecation warnings to `PytestRemovedInXWarning` Closes #7480. This allows us to more easily follow our deprecation policy of turning warnings into errors for the X.0 releases before complete removal in X.1. It also makes the deprecation timeline clear to both the users and pytest developers -- it can be hard to keep track. Note that the designation is not meant to be a binding contract - if the time comes for removal of a specific deprecation but we decide it's too soon, can just bump it to the next major. Inspired by Django: https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/submitting-patches/#deprecating-a-feature --- changelog/7480.improvement.rst | 5 ++++ doc/en/backwards-compatibility.rst | 4 ++- src/_pytest/deprecated.py | 39 +++++++++++++++++------------- src/_pytest/warning_types.py | 15 +++++++++++- src/pytest/__init__.py | 4 +++ testing/deprecated_test.py | 12 ++++----- 6 files changed, 54 insertions(+), 25 deletions(-) create mode 100644 changelog/7480.improvement.rst diff --git a/changelog/7480.improvement.rst b/changelog/7480.improvement.rst new file mode 100644 index 00000000000..296e6e7fb54 --- /dev/null +++ b/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. diff --git a/doc/en/backwards-compatibility.rst b/doc/en/backwards-compatibility.rst index 0c3521533a1..922fdbd7f72 100644 --- a/doc/en/backwards-compatibility.rst +++ b/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. diff --git a/src/_pytest/deprecated.py b/src/_pytest/deprecated.py index d768d0770c5..5f1edd60727 100644 --- a/src/_pytest/deprecated.py +++ b/src/_pytest/deprecated.py @@ -11,6 +11,8 @@ 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 @@ 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 = 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 @@ 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", ) diff --git a/src/_pytest/warning_types.py b/src/_pytest/warning_types.py index 4139225d7f5..2a97a319789 100644 --- a/src/_pytest/warning_types.py +++ b/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. diff --git a/src/pytest/__init__.py b/src/pytest/__init__.py index 18e40ceae6a..7a596cd3783 100644 --- a/src/pytest/__init__.py +++ b/src/pytest/__init__.py @@ -68,6 +68,8 @@ 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 @@ "PytestConfigWarning", "PytestDeprecationWarning", "PytestExperimentalApiWarning", + "PytestRemovedIn7Warning", + "PytestRemovedIn8Warning", "Pytester", "PytestPluginManager", "PytestUnhandledCoroutineWarning", diff --git a/testing/deprecated_test.py b/testing/deprecated_test.py index fb465e1e0dd..38af26d589d 100644 --- a/testing/deprecated_test.py +++ b/testing/deprecated_test.py @@ -115,7 +115,7 @@ def test_foo(): pass 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 @@ def test_skipping_msg(): 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 @@ def test_failing_msg(): 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 @@ def test_exit_msg(): 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 pytest_cmdline_preparse(config, args): 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.*", ] ) From a172a4141be59313569358c5d0077f4d326b78a4 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sun, 14 Nov 2021 23:39:56 +0200 Subject: [PATCH 2/2] Change PytestRemovedIn7Warning to error by default Per our backward compatibility policy. Co-authored-by: Bruno Oliveira --- changelog/9308.breaking.rst | 22 ++++++++++++++++++++++ src/_pytest/warnings.py | 2 ++ testing/test_mark.py | 4 +++- testing/test_terminal.py | 4 +++- testing/test_warnings.py | 13 +++++-------- 5 files changed, 35 insertions(+), 10 deletions(-) create mode 100644 changelog/9308.breaking.rst diff --git a/changelog/9308.breaking.rst b/changelog/9308.breaking.rst new file mode 100644 index 00000000000..ca062e5a2a7 --- /dev/null +++ b/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`. diff --git a/src/_pytest/warnings.py b/src/_pytest/warnings.py index 4f831548d89..c0c946cbde5 100644 --- a/src/_pytest/warnings.py +++ b/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 diff --git a/testing/test_mark.py b/testing/test_mark.py index 19eff00f37c..da67d1ea7bc 100644 --- a/testing/test_mark.py +++ b/testing/test_mark.py @@ -831,7 +831,9 @@ def test_two(): assert 1 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 diff --git a/testing/test_terminal.py b/testing/test_terminal.py index 0f14c4d0cbf..32f32ff5ee9 100644 --- a/testing/test_terminal.py +++ b/testing/test_terminal.py @@ -682,7 +682,9 @@ def test_three(): 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 ..*"] ) diff --git a/testing/test_warnings.py b/testing/test_warnings.py index 11678383548..cac716680f4 100644 --- a/testing/test_warnings.py +++ b/testing/test_warnings.py @@ -518,11 +518,8 @@ def test_hidden_by_system(self, pytester: Pytester, monkeypatch) -> None: @pytest.mark.parametrize("change_default", [None, "ini", "cmdline"]) -@pytest.mark.skip( - reason="This test should be enabled again before pytest 7.0 is released" -) -def test_deprecation_warning_as_error(pytester: Pytester, change_default) -> None: - """This ensures that PytestDeprecationWarnings raised by pytest are turned into errors. +def test_removed_in_x_warning_as_error(pytester: Pytester, change_default) -> None: + """This ensures that PytestRemovedInXWarnings 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(): """ [pytest] filterwarnings = - ignore::pytest.PytestDeprecationWarning + ignore::pytest.PytestRemovedIn7Warning """ ) args = ( - ("-Wignore::pytest.PytestDeprecationWarning",) + ("-Wignore::pytest.PytestRemovedIn7Warning",) if change_default == "cmdline" else () )