Skip to content

Commit d42cef1

Browse files
jakkdlbluetech
authored andcommitted
doc: undocument legacy forms of raises, warns, deprecated_call
We don't intend to deprecate the legacy forms, but there is no reason to use them anymore, and they add complexity/confusion, so let's just mostly pretend they don't exist in the docs.
1 parent 2b5952c commit d42cef1

4 files changed

Lines changed: 8 additions & 39 deletions

File tree

doc/en/how-to/assert.rst

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -322,13 +322,9 @@ will then execute the function with those arguments and assert that the given ex
322322
323323
pytest.raises(ValueError, func, x=-1)
324324
325-
The reporter will provide you with helpful output in case of failures such as *no
326-
exception* or *wrong exception*.
327-
328325
This form was the original :func:`pytest.raises` API, developed before the ``with`` statement was
329326
added to the Python language. Nowadays, this form is rarely used, with the context-manager form (using ``with``)
330327
being considered more readable.
331-
Nonetheless, this form is fully supported and not deprecated in any way.
332328

333329
xfail mark and pytest.raises
334330
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/en/how-to/capture-warnings.rst

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -371,13 +371,6 @@ Some examples:
371371
... warnings.warn("issue with foo() func")
372372
...
373373
374-
You can also call :func:`pytest.warns` on a function or code string:
375-
376-
.. code-block:: python
377-
378-
pytest.warns(expected_warning, func, *args, **kwargs)
379-
pytest.warns(expected_warning, "func(*args, **kwargs)")
380-
381374
The function also returns a list of all raised warnings (as
382375
``warnings.WarningMessage`` objects), which you can query for
383376
additional information:

src/_pytest/raises.py

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -237,25 +237,6 @@ def raises(
237237
238238
:ref:`assertraises` for more examples and detailed discussion.
239239
240-
**Legacy form**
241-
242-
It is possible to specify a callable by passing a to-be-called lambda::
243-
244-
>>> raises(ZeroDivisionError, lambda: 1/0)
245-
<ExceptionInfo ...>
246-
247-
or you can specify an arbitrary callable with arguments::
248-
249-
>>> def f(x): return 1/x
250-
...
251-
>>> raises(ZeroDivisionError, f, 0)
252-
<ExceptionInfo ...>
253-
>>> raises(ZeroDivisionError, f, x=0)
254-
<ExceptionInfo ...>
255-
256-
The form above is fully supported but discouraged for new code because the
257-
context manager form is regarded as more readable and less error-prone.
258-
259240
.. note::
260241
Similar to caught exception objects in Python, explicitly clearing
261242
local references to returned ``ExceptionInfo`` objects can

src/_pytest/recwarn.py

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -67,16 +67,15 @@ def deprecated_call(
6767
>>> import pytest
6868
>>> with pytest.deprecated_call():
6969
... assert api_call_v2() == 200
70+
>>> with pytest.deprecated_call(match="^use v3 of this api$") as warning_messages:
71+
... assert api_call_v2() == 200
7072
71-
It can also be used by passing a function and ``*args`` and ``**kwargs``,
72-
in which case it will ensure calling ``func(*args, **kwargs)`` produces one of
73-
the warnings types above. The return value is the return value of the function.
74-
75-
In the context manager form you may use the keyword argument ``match`` to assert
73+
You may use the keyword argument ``match`` to assert
7674
that the warning matches a text or regex.
7775
78-
The context manager produces a list of :class:`warnings.WarningMessage` objects,
79-
one for each warning raised.
76+
The return value is a list of :class:`warnings.WarningMessage` objects,
77+
one for each warning emitted
78+
(regardless of whether it is an ``expected_warning`` or not).
8079
"""
8180
__tracebackhide__ = True
8281
if func is not None:
@@ -119,13 +118,13 @@ def warns(
119118
each warning emitted (regardless of whether it is an ``expected_warning`` or not).
120119
Since pytest 8.0, unmatched warnings are also re-emitted when the context closes.
121120
122-
This function can be used as a context manager::
121+
This function should be used as a context manager::
123122
124123
>>> import pytest
125124
>>> with pytest.warns(RuntimeWarning):
126125
... warnings.warn("my warning", RuntimeWarning)
127126
128-
In the context manager form you may use the keyword argument ``match`` to assert
127+
The ``match`` keyword argument can be used to assert
129128
that the warning matches a text or regex::
130129
131130
>>> with pytest.warns(UserWarning, match='must be 0 or None'):

0 commit comments

Comments
 (0)