Skip to content

Commit 93bdbf7

Browse files
nicoddemusnicoddemus
authored
Merge pull request #4173 from nicoddemus/warning-docs-update
Update warnings docs
2 parents ab8907f + 215a2ed commit 93bdbf7

1 file changed

Lines changed: 84 additions & 97 deletions

File tree

‎doc/en/warnings.rst‎

Lines changed: 84 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -75,8 +75,54 @@ Both ``-W`` command-line option and ``filterwarnings`` ini option are based on P
7575
`-W option`_ and `warnings.simplefilter`_, so please refer to those sections in the Python
7676
documentation for other examples and advanced usage.
7777

78-
Disabling warning summary
79-
-------------------------
78+
.. _`filterwarnings`:
79+
80+
``@pytest.mark.filterwarnings``
81+
-------------------------------
82+
83+
.. versionadded:: 3.2
84+
85+
You can use the ``@pytest.mark.filterwarnings`` to add warning filters to specific test items,
86+
allowing you to have finer control of which warnings should be captured at test, class or
87+
even module level:
88+
89+
.. code-block:: python
90+
91+
import warnings
92+
93+
94+
def api_v1():
95+
warnings.warn(UserWarning("api v1, should use functions from v2"))
96+
return 1
97+
98+
99+
@pytest.mark.filterwarnings("ignore:api v1")
100+
def test_one():
101+
assert api_v1() == 1
102+
103+
104+
Filters applied using a mark take precedence over filters passed on the command line or configured
105+
by the ``filterwarnings`` ini option.
106+
107+
You may apply a filter to all tests of a class by using the ``filterwarnings`` mark as a class
108+
decorator or to all tests in a module by setting the ``pytestmark`` variable:
109+
110+
.. code-block:: python
111+
112+
# turns all warnings into errors for this module
113+
pytestmark = pytest.mark.filterwarnings("error")
114+
115+
116+
117+
*Credits go to Florian Schulze for the reference implementation in the* `pytest-warnings`_
118+
*plugin.*
119+
120+
.. _`-W option`: https://docs.python.org/3/using/cmdline.html?highlight=#cmdoption-W
121+
.. _warnings.simplefilter: https://docs.python.org/3/library/warnings.html#warnings.simplefilter
122+
.. _`pytest-warnings`: https://github.com/fschulze/pytest-warnings
123+
124+
Disabling warnings summary
125+
--------------------------
80126

81127
Although not recommended, you can use the ``--disable-warnings`` command-line option to suppress the
82128
warning summary entirely from the test run output.
@@ -103,10 +149,14 @@ DeprecationWarning and PendingDeprecationWarning
103149
.. versionadded:: 3.8
104150
.. versionchanged:: 3.9
105151

106-
By default pytest will display ``DeprecationWarning`` and ``PendingDeprecationWarning``.
152+
By default pytest will display ``DeprecationWarning`` and ``PendingDeprecationWarning`` warnings from
153+
user code and third-party libraries, as recommended by `PEP-0506 <https://www.python.org/dev/peps/pep-0565>`_.
154+
This helps users keep their code modern and avoid breakages when deprecated warnings are effectively removed.
107155

108156
Sometimes it is useful to hide some specific deprecation warnings that happen in code that you have no control over
109-
(such as third-party libraries), in which case you might use the standard warning filters options (ini or marks).
157+
(such as third-party libraries), in which case you might use the warning filters options (ini or marks) to ignore
158+
those warnings.
159+
110160
For example:
111161

112162
.. code-block:: ini
@@ -116,83 +166,57 @@ For example:
116166
ignore:.*U.*mode is deprecated:DeprecationWarning
117167
118168
169+
This will ignore all warnings of type ``DeprecationWarning`` where the start of the message matches
170+
the regular expression ``".*U.*mode is deprecated"``.
171+
119172
.. note::
120173
If warnings are configured at the interpreter level, using
121174
the `PYTHONWARNINGS <https://docs.python.org/3/using/cmdline.html#envvar-PYTHONWARNINGS>`_ environment variable or the
122175
``-W`` command-line option, pytest will not configure any filters by default.
123176

124-
.. note::
125-
This feature makes pytest more compliant with `PEP-0506 <https://www.python.org/dev/peps/pep-0565/#recommended-filter-settings-for-test-runners>`_ which suggests that those warnings should
126-
be shown by default by test runners, but pytest doesn't follow ``PEP-0506`` completely because resetting all
127-
warning filters like suggested in the PEP will break existing test suites that configure warning filters themselves
177+
Also pytest doesn't follow ``PEP-0506`` suggestion of resetting all warning filters because
178+
it might break test suites that configure warning filters themselves
128179
by calling ``warnings.simplefilter`` (see issue `#2430 <https://github.com/pytest-dev/pytest/issues/2430>`_
129180
for an example of that).
130181

131182

132-
.. _`filterwarnings`:
133-
134-
``@pytest.mark.filterwarnings``
135-
-------------------------------
136-
137-
.. versionadded:: 3.2
138-
139-
You can use the ``@pytest.mark.filterwarnings`` to add warning filters to specific test items,
140-
allowing you to have finer control of which warnings should be captured at test, class or
141-
even module level:
142-
143-
.. code-block:: python
144-
145-
import warnings
146-
147-
148-
def api_v1():
149-
warnings.warn(UserWarning("api v1, should use functions from v2"))
150-
return 1
151-
152-
153-
@pytest.mark.filterwarnings("ignore:api v1")
154-
def test_one():
155-
assert api_v1() == 1
156-
157-
158-
Filters applied using a mark take precedence over filters passed on the command line or configured
159-
by the ``filterwarnings`` ini option.
183+
.. _`ensuring a function triggers a deprecation warning`:
160184

161-
You may apply a filter to all tests of a class by using the ``filterwarnings`` mark as a class
162-
decorator or to all tests in a module by setting the ``pytestmark`` variable:
185+
.. _ensuring_function_triggers:
163186

164-
.. code-block:: python
187+
Ensuring code triggers a deprecation warning
188+
--------------------------------------------
165189

166-
# turns all warnings into errors for this module
167-
pytestmark = pytest.mark.filterwarnings("error")
190+
You can also call a global helper for checking
191+
that a certain function call triggers a ``DeprecationWarning`` or
192+
``PendingDeprecationWarning``::
168193

194+
import pytest
169195

170-
.. note::
196+
def test_global():
197+
pytest.deprecated_call(myfunction, 17)
171198

172-
Except for these features, pytest does not change the python warning filter; it only captures
173-
and displays the warnings which are issued with respect to the currently configured filter,
174-
including changes to the filter made by test functions or by the system under test.
199+
By default, ``DeprecationWarning`` and ``PendingDeprecationWarning`` will not be
200+
caught when using ``pytest.warns`` or ``recwarn`` because default Python warnings filters hide
201+
them. If you wish to record them in your own code, use the
202+
command ``warnings.simplefilter('always')``::
175203

176-
.. note::
204+
import warnings
205+
import pytest
177206

178-
``DeprecationWarning`` and ``PendingDeprecationWarning`` are hidden by the standard library
179-
by default so you have to explicitly configure them to be displayed in your ``pytest.ini``:
207+
def test_deprecation(recwarn):
208+
warnings.simplefilter('always')
209+
warnings.warn("deprecated", DeprecationWarning)
210+
assert len(recwarn) == 1
211+
assert recwarn.pop(DeprecationWarning)
180212

181-
.. code-block:: ini
213+
You can also use it as a contextmanager::
182214

183-
[pytest]
184-
filterwarnings =
185-
once::DeprecationWarning
186-
once::PendingDeprecationWarning
215+
def test_global():
216+
with pytest.deprecated_call():
217+
myobject.deprecated_method()
187218

188219

189-
*Credits go to Florian Schulze for the reference implementation in the* `pytest-warnings`_
190-
*plugin.*
191-
192-
.. _`-W option`: https://docs.python.org/3/using/cmdline.html?highlight=#cmdoption-W
193-
.. _warnings.simplefilter: https://docs.python.org/3/library/warnings.html#warnings.simplefilter
194-
.. _`pytest-warnings`: https://github.com/fschulze/pytest-warnings
195-
196220

197221
.. _`asserting warnings`:
198222

@@ -299,43 +323,6 @@ warnings, or index into it to get a particular recorded warning.
299323

300324
Full API: :class:`WarningsRecorder`.
301325

302-
.. _`ensuring a function triggers a deprecation warning`:
303-
304-
.. _ensuring_function_triggers:
305-
306-
Ensuring a function triggers a deprecation warning
307-
-------------------------------------------------------
308-
309-
You can also call a global helper for checking
310-
that a certain function call triggers a ``DeprecationWarning`` or
311-
``PendingDeprecationWarning``::
312-
313-
import pytest
314-
315-
def test_global():
316-
pytest.deprecated_call(myfunction, 17)
317-
318-
By default, ``DeprecationWarning`` and ``PendingDeprecationWarning`` will not be
319-
caught when using ``pytest.warns`` or ``recwarn`` because default Python warnings filters hide
320-
them. If you wish to record them in your own code, use the
321-
command ``warnings.simplefilter('always')``::
322-
323-
import warnings
324-
import pytest
325-
326-
def test_deprecation(recwarn):
327-
warnings.simplefilter('always')
328-
warnings.warn("deprecated", DeprecationWarning)
329-
assert len(recwarn) == 1
330-
assert recwarn.pop(DeprecationWarning)
331-
332-
You can also use it as a contextmanager::
333-
334-
def test_global():
335-
with pytest.deprecated_call():
336-
myobject.deprecated_method()
337-
338-
339326

340327
.. _internal-warnings:
341328

0 commit comments

Comments
 (0)