hookspec: deprecate hookimpls requesting py.path parameters

Author: bluetech

changelog/12069.deprecation.rst

@@ -0,0 +1,12 @@
+A deprecation warning is now raised when implementations of one of the following hooks request a deprecated ``py.path.local`` parameter instead of the ``pathlib.Path`` parameter which replaced it::
+
+- :hook:`pytest_ignore_collect` - the ``path`` parameter - use ``collection_path`` instead.
+- :hook:`pytest_collect_file` - the ``path`` parameter - use ``file_path`` instead.
+- :hook:`pytest_pycollect_makemodule` - the ``path`` parameter - use ``module_path`` instead.
+- :hook:`pytest_report_header` - the ``startdir`` parameter - use ``start_path`` instead.
+- :hook:`pytest_report_collectionfinish` - the ``startdir`` parameter - use ``start_path`` instead.
+
+The replacement parameters are available since pytest 7.0.0.
+The old parameters will be removed in pytest 9.0.0.
+
+See :ref:`legacy-path-hooks-deprecated` for more details.

src/_pytest/hookspec.py

@@ -15,6 +15,8 @@
 
 from pluggy import HookspecMarker
 
+from .deprecated import HOOK_LEGACY_PATH_ARG
+
 
 if TYPE_CHECKING:
     import pdb
@@ -297,7 +299,14 @@ def pytest_collection_finish(session: "Session") -> None:
     """
 
 
-@hookspec(firstresult=True)
+@hookspec(
+    firstresult=True,
+    warn_on_impl_args={
+        "path": HOOK_LEGACY_PATH_ARG.format(
+            pylib_path_arg="path", pathlib_path_arg="collection_path"
+        ),
+    },
+)
 def pytest_ignore_collect(
     collection_path: Path, path: "LEGACY_PATH", config: "Config"
 ) -> Optional[bool]:
@@ -356,6 +365,13 @@ def pytest_collect_directory(path: Path, parent: "Collector") -> "Optional[Colle
     """
 
 
+@hookspec(
+    warn_on_impl_args={
+        "path": HOOK_LEGACY_PATH_ARG.format(
+            pylib_path_arg="path", pathlib_path_arg="file_path"
+        ),
+    },
+)
 def pytest_collect_file(
     file_path: Path, path: "LEGACY_PATH", parent: "Collector"
 ) -> "Optional[Collector]":
@@ -468,7 +484,14 @@ def pytest_make_collect_report(collector: "Collector") -> "Optional[CollectRepor
 # -------------------------------------------------------------------------
 
 
-@hookspec(firstresult=True)
+@hookspec(
+    firstresult=True,
+    warn_on_impl_args={
+        "path": HOOK_LEGACY_PATH_ARG.format(
+            pylib_path_arg="path", pathlib_path_arg="module_path"
+        ),
+    },
+)
 def pytest_pycollect_makemodule(
     module_path: Path, path: "LEGACY_PATH", parent
 ) -> Optional["Module"]:
@@ -994,6 +1017,13 @@ def pytest_assertion_pass(item: "Item", lineno: int, orig: str, expl: str) -> No
 # -------------------------------------------------------------------------
 
 
+@hookspec(
+    warn_on_impl_args={
+        "startdir": HOOK_LEGACY_PATH_ARG.format(
+            pylib_path_arg="startdir", pathlib_path_arg="start_path"
+        ),
+    },
+)
 def pytest_report_header(  # type:ignore[empty-body]
     config: "Config", start_path: Path, startdir: "LEGACY_PATH"
 ) -> Union[str, List[str]]:
@@ -1022,6 +1052,13 @@ def pytest_report_header(  # type:ignore[empty-body]
     """
 
 
+@hookspec(
+    warn_on_impl_args={
+        "startdir": HOOK_LEGACY_PATH_ARG.format(
+            pylib_path_arg="startdir", pathlib_path_arg="start_path"
+        ),
+    },
+)
 def pytest_report_collectionfinish(  # type:ignore[empty-body]
     config: "Config",
     start_path: Path,

testing/deprecated_test.py

@@ -121,6 +121,32 @@ def test_hookproxy_warnings_for_pathlib(tmp_path, hooktype, request):
             )
 
 
+def test_hookimpl_warnings_for_pathlib() -> None:
+    class Plugin:
+        def pytest_ignore_collect(self, path: object) -> None:
+            return None
+
+        def pytest_collect_file(self, path: object) -> None:
+            return None
+
+        def pytest_pycollect_makemodule(self, path: object) -> None:
+            return None
+
+        def pytest_report_header(self, startdir: object) -> str:
+            return ""
+
+        def pytest_report_collectionfinish(self, startdir: object) -> str:
+            return ""
+
+    pm = pytest.PytestPluginManager()
+    with pytest.warns(
+        pytest.PytestRemovedIn9Warning,
+        match=r"py\.path\.local.* argument is deprecated",
+    ) as wc:
+        pm.register(Plugin())
+    assert len(wc.list) == 5
+
+
 def test_node_ctor_fspath_argument_is_deprecated(pytester: Pytester) -> None:
     mod = pytester.getmodulecol("")