Deprecate pytest_cmdline_preparse

Close #8592 

PR #8956

Author: symonk

changelog/8592.deprecation.rst

@@ -0,0 +1 @@
+:func:`pytest_cmdline_preparse <_pytest.hookspec.pytest_cmdline_preparse>` has been officially deprecated.  It will be removed in a future release.  Use :func:`pytest_load_initial_conftests <_pytest.hookspec.pytest_load_initial_conftests>` instead.

doc/en/deprecations.rst

@@ -33,6 +33,29 @@ In order to support the transition to :mod:`pathlib`, the following hooks now re
 The accompanying ``py.path.local`` based paths have been deprecated: plugins which manually invoke those hooks should only pass the new ``pathlib.Path`` arguments, and users should change their hook implementations to use the new ``pathlib.Path`` arguments.
 
 
+Implementing the ``pytest_cmdline_preparse`` hook
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 7.0
+
+Implementing the :func:`pytest_cmdline_preparse <_pytest.hookspec.pytest_cmdline_preparse>` hook has been officially deprecated.
+Implement the :func:`pytest_load_initial_conftests <_pytest.hookspec.pytest_load_initial_conftests>` hook instead.
+
+.. code-block:: python
+
+    def pytest_cmdline_preparse(config: Config, args: List[str]) -> None:
+        ...
+
+
+    # becomes:
+
+
+    def pytest_load_initial_conftests(
+        early_config: Config, parser: Parser, args: List[str]
+    ) -> None:
+        ...
+
+
 Diamond inheritance between :class:`pytest.File` and :class:`pytest.Item`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

src/_pytest/deprecated.py

@@ -53,6 +53,11 @@
     "Please use pytest_warning_recorded instead."
 )
 
+WARNING_CMDLINE_PREPARSE_HOOK = PytestDeprecationWarning(
+    "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(
     "The gethookproxy() and isinitpath() methods of FSCollector and Package are deprecated; "
     "use self.session.gethookproxy() and self.session.isinitpath() instead. "

src/_pytest/hookspec.py

@@ -14,6 +14,7 @@
 from pluggy import HookspecMarker
 
 from _pytest.deprecated import WARNING_CAPTURED_HOOK
+from _pytest.deprecated import WARNING_CMDLINE_PREPARSE_HOOK
 
 if TYPE_CHECKING:
     import pdb
@@ -157,6 +158,7 @@ def pytest_cmdline_parse(
     """
 
 
+@hookspec(warn_on_impl=WARNING_CMDLINE_PREPARSE_HOOK)
 def pytest_cmdline_preparse(config: "Config", args: List[str]) -> None:
     """(**Deprecated**) modify command line arguments before option parsing.
 

testing/deprecated_test.py

@@ -190,3 +190,20 @@ def test_warns_none_is_deprecated():
     ):
         with pytest.warns(None):  # type: ignore[call-overload]
             pass
+
+
+def test_deprecation_of_cmdline_preparse(pytester: Pytester) -> None:
+    pytester.makeconftest(
+        """
+        def pytest_cmdline_preparse(config, args):
+            ...
+
+        """
+    )
+    result = pytester.runpytest()
+    result.stdout.fnmatch_lines(
+        [
+            "*PytestDeprecationWarning: The pytest_cmdline_preparse hook is deprecated*",
+            "*Please use pytest_load_initial_conftests hook instead.*",
+        ]
+    )