Document that item parameter of pytest_warning_captured hook is deprecated

Our policy is to not deprecate features during bugfix releases, but in this
case I believe it makes sense as we are only documenting it as deprecated,
without issuing warnings which might potentially break test suites.

This will get the word out that hook implementers should not use this parameter
at all.

Fix #4036
This commit is contained in:
Bruno Oliveira 2018-09-25 17:38:22 -03:00
parent b1fbb2ab92
commit 1636522563
2 changed files with 12 additions and 0 deletions

View File

@ -0,0 +1,9 @@
The ``item`` parameter of ``pytest_warning_captured`` hook is now documented as deprecated. We realized only after
the ``3.8`` release that this parameter is incompatible with ``pytest-xdist``.
Our policy is to not deprecate features during bugfix releases, but in this case we believe it makes sense as we are
only documenting it as deprecated, without issuing warnings which might potentially break test suites. This will get
the word out that hook implementers should not use this parameter at all.
In a future release ``item`` will always be ``None`` and will emit a proper warning when a hook implementation
makes use of it.

View File

@ -562,6 +562,9 @@ def pytest_warning_captured(warning_message, when, item):
* ``"runtest"``: during test execution.
:param pytest.Item|None item:
**DEPRECATED**: This parameter is incompatible with ``pytest-xdist``, and will always receive ``None``
in a future release.
The item being executed if ``when`` is ``"runtest"``, otherwise ``None``.
"""