warnings: fix missing None in existing hook & add some docs (#7288)

doc/en/deprecations.rst

@@ -20,6 +20,17 @@ Below is a complete list of all pytest features which are considered deprecated.
 :ref:`standard warning filters <warnings>`.
 
 
+The ``pytest_warning_captured`` hook
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 6.0
+
+This hook has an `item` parameter which cannot be serialized by ``pytest-xdist``.
+
+Use the ``pytest_warning_recored`` hook instead, which replaces the ``item`` parameter
+by a ``nodeid`` parameter.
+
+
 The ``pytest._fillfuncargs`` function
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

src/_pytest/hookspec.py

@@ -623,9 +623,16 @@ def pytest_terminal_summary(terminalreporter, exitstatus, config):
 
 
 @hookspec(historic=True, warn_on_impl=WARNING_CAPTURED_HOOK)
-def pytest_warning_captured(warning_message, when, item, location):
+def pytest_warning_captured(
+    warning_message: "warnings.WarningMessage",
+    when: str,
+    item,
+    location: Optional[Tuple[str, int, str]],
+) -> None:
     """(**Deprecated**) Process a warning captured by the internal pytest warnings plugin.
 
+    .. deprecated:: 6.0
+
     This hook is considered deprecated and will be removed in a future pytest version.
     Use :func:`pytest_warning_recorded` instead.
 
@@ -644,8 +651,9 @@ def pytest_warning_captured(warning_message, when, item, location):
         The item being executed if ``when`` is ``"runtest"``, otherwise ``None``.
 
     :param tuple location:
-        Holds information about the execution context of the captured warning (filename, linenumber, function).
+        When available, holds information about the execution context of the captured
-        ``function`` evaluates to <module> when the execution context is at the module level.
+        warning (filename, linenumber, function). ``function`` evaluates to <module>
+        when the execution context is at the module level.
     """
 
 
@@ -654,8 +662,8 @@ def pytest_warning_recorded(
     warning_message: "warnings.WarningMessage",
     when: str,
     nodeid: str,
-    location: Tuple[str, int, str],
+    location: Optional[Tuple[str, int, str]],
-):
+) -> None:
     """
     Process a warning captured by the internal pytest warnings plugin.
 
@@ -672,9 +680,12 @@ def pytest_warning_recorded(
 
     :param str nodeid: full id of the item
 
-    :param tuple location:
+    :param tuple|None location:
-        Holds information about the execution context of the captured warning (filename, linenumber, function).
+        When available, holds information about the execution context of the captured
-        ``function`` evaluates to <module> when the execution context is at the module level.
+        warning (filename, linenumber, function). ``function`` evaluates to <module>
+        when the execution context is at the module level.
+
+    .. versionadded:: 6.0
     """
 
 

src/_pytest/warnings.py

@@ -112,7 +112,12 @@ def catch_warnings_for_item(config, ihook, when, item):
 
         for warning_message in log:
             ihook.pytest_warning_captured.call_historic(
-                kwargs=dict(warning_message=warning_message, when=when, item=item)
+                kwargs=dict(
+                    warning_message=warning_message,
+                    when=when,
+                    item=item,
+                    location=None,
+                )
             )
             ihook.pytest_warning_recorded.call_historic(
                 kwargs=dict(