From c27db3bd8e2f336747196ecaf72b153a160da21d Mon Sep 17 00:00:00 2001
From: Simon K <jackofspaces@gmail.com>
Date: Sat, 31 Jul 2021 14:53:43 +0100
Subject: [PATCH] Deprecate pytest_cmdline_preparse

Close #8592

PR #8956
---
 changelog/8592.deprecation.rst |  1 +
 doc/en/deprecations.rst        | 23 +++++++++++++++++++++++
 src/_pytest/deprecated.py      |  5 +++++
 src/_pytest/hookspec.py        |  2 ++
 testing/deprecated_test.py     | 17 +++++++++++++++++
 5 files changed, 48 insertions(+)
 create mode 100644 changelog/8592.deprecation.rst

diff --git a/changelog/8592.deprecation.rst b/changelog/8592.deprecation.rst
new file mode 100644
index 000000000..51b7a6b0d
--- /dev/null
+++ b/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.
diff --git a/doc/en/deprecations.rst b/doc/en/deprecations.rst
index 8136c60ae..95c2a8869 100644
--- a/doc/en/deprecations.rst
+++ b/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`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/src/_pytest/deprecated.py b/src/_pytest/deprecated.py
index e5fbc0129..0c5db6d53 100644
--- a/src/_pytest/deprecated.py
+++ b/src/_pytest/deprecated.py
@@ -53,6 +53,11 @@ WARNING_CAPTURED_HOOK = PytestDeprecationWarning(
     "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. "
diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py
index e8fcc3d73..4fe3cf4b4 100644
--- a/src/_pytest/hookspec.py
+++ b/src/_pytest/hookspec.py
@@ -14,6 +14,7 @@ from typing import Union
 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.
 
diff --git a/testing/deprecated_test.py b/testing/deprecated_test.py
index 479f1f26d..0a5adac56 100644
--- a/testing/deprecated_test.py
+++ b/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.*",
+        ]
+    )