[tanishmisra9]

Closes #9825

Adds a ResourceWarning section to the warnings how-to, immediately below the DeprecationWarning and PendingDeprecationWarning section.

Explains that ResourceWarning is emitted by the garbage collector at finalization time rather than at the leak site, which is why filterwarnings / @pytest.mark.filterwarnings / -W error::ResourceWarning often miss it. Documents error::pytest.PytestUnraisableExceptionWarning as the reliable workaround.

Includes a seealso cross-link to the existing tracemalloc Resource Warnings section.
tox -e docs passes with no new warnings

[LaTranquillum]

The examples in doc/en/how-to/capture-warnings.rst (lines 359–370) also need error::ResourceWarning. The PytestUnraisableExceptionWarning filter alone does not promote the original resource warning into an exception.

Minimal reproduction (test_resource_leak.py), using CPython 3.14.2 and pytest 9.1.1 on macOS:

import gc
import os

def test_resource_leak():
    leaked = open(os.devnull)
    del leaked
    gc.collect()

With third-party plugin autoload disabled, the isolated runs produced:

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q test_resource_leak.py -W error::pytest.PytestUnraisableExceptionWarning
# 1 passed, exit 0

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q test_resource_leak.py -W error::ResourceWarning -W error::pytest.PytestUnraisableExceptionWarning
# 1 failed, exit 1 (PytestUnraisableExceptionWarning from the ResourceWarning)

Could both configuration examples include both filters? The first makes the warning an exception during finalization; pytest then reports that unraisable exception, and the second makes that report fail the test.

The wording “reliably fail the test run when a resource is leaked” should also be qualified: these filters do not guarantee that finalization happens while pytest can capture it. This reproduction deliberately forces cleanup and only demonstrates the filter distinction.

Disclosure: Codex assisted with the investigation, ran the local reproduction, and drafted this feedback; I reviewed the explanation and authorized submission.