Finish the job

src/_pytest/hookspec.py

@@ -62,7 +62,7 @@ def pytest_addhooks(pluginmanager: "PytestPluginManager") -> None:
     Use in conftest plugins
     =======================
 
-    If a conftest file implements this hook, it will be called immediately
+    If a conftest plugin implements this hook, it will be called immediately
     when the conftest is registered.
     """
 
@@ -85,7 +85,7 @@ def pytest_plugin_registered(
     Use in conftest plugins
     =======================
 
-    If a conftest file implements this hook, it will be called immediately
+    If a conftest plugin implements this hook, it will be called immediately
     when the conftest is registered, once for each plugin registered thus far
     (including itself!), and for all plugins thereafter when they are
     registered.
@@ -126,12 +126,10 @@ def pytest_addoption(parser: "Parser", pluginmanager: "PytestPluginManager") ->
     Use in conftest plugins
     =======================
 
-    If a conftest file implements this hook, it will be called immediately
+    If a conftest plugin implements this hook, it will be called immediately
     when the conftest is registered.
 
-    This hook is only called for conftest files situated at the tests root
+    This hook is only called for :ref:`initial conftests <pluginorder>`.
-    directory due to how pytest :ref:`discovers plugins during startup
-    <pluginorder>`.
     """
 
 
@@ -147,9 +145,9 @@ def pytest_configure(config: "Config") -> None:
     Use in conftest plugins
     =======================
 
-    This hook is called for every plugin and initial conftest file after command
+    This hook is called for every :ref:`initial conftest <pluginorder>` file
-    line options have been parsed. After that, the hook is called for other
+    after command line options have been parsed. After that, the hook is called
-    conftest files as they are registered.
+    for other conftest files as they are registered.
     """
 
 
@@ -186,8 +184,8 @@ def pytest_cmdline_parse(
 def pytest_load_initial_conftests(
     early_config: "Config", parser: "Parser", args: List[str]
 ) -> None:
-    """Called to implement the loading of initial conftest files ahead
+    """Called to implement the loading of :ref:`initial conftest files
-    of command line option parsing.
+    <pluginorder>` ahead of command line option parsing.
 
     :param early_config: The pytest config object.
     :param args: Arguments passed on the command line.
@@ -215,8 +213,7 @@ def pytest_cmdline_main(config: "Config") -> Optional[Union["ExitCode", int]]:
     Use in conftest plugins
     =======================
 
-    This hook is only called for conftest files situated at the tests root
+    This hook is only called for :ref:`initial conftests <pluginorder>`.
-    directory. It is not called for other conftest files.
     """
 
 
@@ -263,8 +260,7 @@ def pytest_collection(session: "Session") -> Optional[object]:
     Use in conftest plugins
     =======================
 
-    This hook is only called for conftest files situated at the tests root
+    This hook is only called for :ref:`initial conftests <pluginorder>`.
-    directory. It is not called for other conftest files.
     """
 
 
@@ -345,6 +341,14 @@ def pytest_collect_directory(path: Path, parent: "Collector") -> "Optional[Colle
 
     See :ref:`custom directory collectors` for a simple example of use of this
     hook.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given collection path, only
+    conftest files in parent directories of the collection path are consulted
+    (if the path is a directory, its own conftest file is *not* consulted - a
+    directory cannot collect itself!).
     """
 
 
@@ -479,6 +483,13 @@ def pytest_pycollect_makemodule(module_path: Path, parent) -> Optional["Module"]
 
     .. versionchanged:: 8.0.0
         The ``path`` parameter has been removed in favor of ``module_path``.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given parent collector,
+    only conftest files in the collector's directory and its parent directories
+    are consulted.
     """
 
 
@@ -498,6 +509,13 @@ def pytest_pycollect_makeitem(
         The object.
     :returns:
         The created items/collectors.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given collector, only
+    conftest files in the collector's directory and its parent directories
+    are consulted.
     """
 
 
@@ -509,6 +527,13 @@ def pytest_pyfunc_call(pyfuncitem: "Function") -> Optional[object]:
 
     :param pyfuncitem:
         The function item.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only
+    conftest files in the item's directory and its parent directories
+    are consulted.
     """
 
 
@@ -517,6 +542,13 @@ def pytest_generate_tests(metafunc: "Metafunc") -> None:
 
     :param metafunc:
         The :class:`~pytest.Metafunc` helper for the test function.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given function definition,
+    only conftest files in the functions's directory and its parent directories
+    are consulted.
     """
 
 
@@ -535,6 +567,11 @@ def pytest_make_parametrize_id(
     :param config: The pytest config object.
     :param val: The parametrized value.
     :param argname: The automatic parameter name produced by pytest.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook.
     """
 
 
@@ -561,6 +598,11 @@ def pytest_runtestloop(session: "Session") -> Optional[object]:
 
     Stops at first non-None result, see :ref:`firstresult`.
     The return value is not used, but only stops further processing.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook.
     """
 
 
@@ -599,6 +641,11 @@ def pytest_runtest_protocol(
 
     Stops at first non-None result, see :ref:`firstresult`.
     The return value is not used, but only stops further processing.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook.
     """
 
 
@@ -613,6 +660,12 @@ def pytest_runtest_logstart(
     :param location: A tuple of ``(filename, lineno, testname)``
         where ``filename`` is a file path relative to ``config.rootpath``
         and ``lineno`` is 0-based.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
     """
 
 
@@ -627,6 +680,12 @@ def pytest_runtest_logfinish(
     :param location: A tuple of ``(filename, lineno, testname)``
         where ``filename`` is a file path relative to ``config.rootpath``
         and ``lineno`` is 0-based.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
     """
 
 
@@ -640,6 +699,12 @@ def pytest_runtest_setup(item: "Item") -> None:
 
     :param item:
         The item.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
     """
 
 
@@ -650,6 +715,12 @@ def pytest_runtest_call(item: "Item") -> None:
 
     :param item:
         The item.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
     """
 
 
@@ -668,6 +739,12 @@ def pytest_runtest_teardown(item: "Item", nextitem: Optional["Item"]) -> None:
         scheduled). This argument is used to perform exact teardowns, i.e.
         calling just enough finalizers so that nextitem only needs to call
         setup functions.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
     """
 
 
@@ -684,6 +761,12 @@ def pytest_runtest_makereport(
     :param call: The :class:`~pytest.CallInfo` for the phase.
 
     Stops at first non-None result, see :ref:`firstresult`.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
     """
 
 
@@ -692,6 +775,12 @@ def pytest_runtest_logreport(report: "TestReport") -> None:
     of the setup, call and teardown runtest phases of an item.
 
     See :hook:`pytest_runtest_protocol` for a description of the runtest protocol.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
     """
 
 
@@ -705,6 +794,12 @@ def pytest_report_to_serializable(
 
     :param config: The pytest config object.
     :param report: The report.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. The exact details may depend
+    on the plugin which calls the hook.
     """
 
 
@@ -717,6 +812,12 @@ def pytest_report_from_serializable(
     :hook:`pytest_report_to_serializable`.
 
     :param config: The pytest config object.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. The exact details may depend
+    on the plugin which calls the hook.
     """
 
 
@@ -744,6 +845,13 @@ def pytest_fixture_setup(
         If the fixture function returns None, other implementations of
         this hook function will continue to be called, according to the
         behavior of the :ref:`firstresult` option.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given fixture, only
+    conftest files in the fixture scope's directory and its parent directories
+    are consulted.
     """
 
 
@@ -758,6 +866,13 @@ def pytest_fixture_post_finalizer(
         The fixture definition object.
     :param request:
         The fixture request object.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given fixture, only
+    conftest files in the fixture scope's directory and its parent directories
+    are consulted.
     """
 
 
@@ -771,6 +886,11 @@ def pytest_sessionstart(session: "Session") -> None:
     and entering the run test loop.
 
     :param session: The pytest session object.
+
+    Use in conftest plugins
+    =======================
+
+    This hook is only called for :ref:`initial conftests <pluginorder>`.
     """
 
 
@@ -782,6 +902,11 @@ def pytest_sessionfinish(
 
     :param session: The pytest session object.
     :param exitstatus: The status which pytest will return to the system.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook.
     """
 
 
@@ -789,6 +914,11 @@ def pytest_unconfigure(config: "Config") -> None:
     """Called before test process is exited.
 
     :param config: The pytest config object.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook.
     """
 
 
@@ -811,6 +941,12 @@ def pytest_assertrepr_compare(
     :param op: The operator, e.g. `"=="`, `"!="`, `"not in"`.
     :param left: The left operand.
     :param right: The right operand.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
     """
 
 
@@ -839,6 +975,12 @@ def pytest_assertion_pass(item: "Item", lineno: int, orig: str, expl: str) -> No
     :param lineno: Line number of the assert statement.
     :param orig: String with the original assertion.
     :param expl: String with the assert explanation.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
     """
 
 
@@ -863,18 +1005,17 @@ def pytest_report_header(  # type:ignore[empty-body]
         If you want to have your line(s) displayed first, use
         :ref:`trylast=True <plugin-hookorder>`.
 
-    .. note::
-
-        This function should be implemented only in plugins or ``conftest.py``
-        files situated at the tests root directory due to how pytest
-        :ref:`discovers plugins during startup <pluginorder>`.
-
     .. versionchanged:: 7.0.0
         The ``start_path`` parameter was added as a :class:`pathlib.Path`
         equivalent of the ``startdir`` parameter.
 
     .. versionchanged:: 8.0.0
         The ``startdir`` parameter has been removed.
+
+    Use in conftest plugins
+    =======================
+
+    This hook is only called for :ref:`initial conftests <pluginorder>`.
     """
 
 
@@ -908,6 +1049,11 @@ def pytest_report_collectionfinish(  # type:ignore[empty-body]
 
     .. versionchanged:: 8.0.0
         The ``startdir`` parameter has been removed.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
     """
 
 
@@ -936,6 +1082,11 @@ def pytest_report_teststatus(  # type:ignore[empty-body]
     :returns: The test status.
 
     Stops at first non-None result, see :ref:`firstresult`.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
     """
 
 
@@ -952,6 +1103,11 @@ def pytest_terminal_summary(
 
     .. versionadded:: 4.2
         The ``config`` parameter.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
     """
 
 
@@ -976,7 +1132,8 @@ def pytest_warning_recorded(
         * ``"runtest"``: during test execution.
 
     :param nodeid:
-        Full id of the item.
+        Full id of the item. Empty string for warnings that are not specific to
+        a particular node.
 
     :param location:
         When available, holds information about the execution context of the captured
@@ -984,6 +1141,13 @@ def pytest_warning_recorded(
         when the execution context is at the module level.
 
     .. versionadded:: 6.0
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. If the warning is specific to a
+    particular node, only conftest files in parent directories of the node are
+    consulted.
     """
 
 
@@ -1007,6 +1171,12 @@ def pytest_markeval_namespace(  # type:ignore[empty-body]
 
     :param config: The pytest config object.
     :returns: A dictionary of additional globals to add.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in parent directories of the item are consulted.
     """
 
 
@@ -1026,6 +1196,11 @@ def pytest_internalerror(
 
     :param excrepr: The exception repr object.
     :param excinfo: The exception info.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
     """
 
 
@@ -1035,6 +1210,11 @@ def pytest_keyboard_interrupt(
     """Called for keyboard interrupt.
 
     :param excinfo: The exception info.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
     """
 
 
@@ -1061,6 +1241,12 @@ def pytest_exception_interact(
         The call information. Contains the exception.
     :param report:
         The collection or test report.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given node, only conftest
+    files in parent directories of the node are consulted.
     """
 
 
@@ -1072,6 +1258,11 @@ def pytest_enter_pdb(config: "Config", pdb: "pdb.Pdb") -> None:
 
     :param config: The pytest config object.
     :param pdb: The Pdb instance.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
     """
 
 
@@ -1083,4 +1274,9 @@ def pytest_leave_pdb(config: "Config", pdb: "pdb.Pdb") -> None:
 
     :param config: The pytest config object.
     :param pdb: The Pdb instance.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
     """