From 71baf24b6d41da6704433ca9909b5e6d954564b9 Mon Sep 17 00:00:00 2001 From: Dan Alvizu Date: Tue, 4 Jan 2022 06:55:01 -0700 Subject: [PATCH] Doc update: clarify -W syntax (#9464) Co-authored-by: Hugo van Kemenade Co-authored-by: Bruno Oliveira --- doc/en/how-to/capture-warnings.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/doc/en/how-to/capture-warnings.rst b/doc/en/how-to/capture-warnings.rst index 7e877b4d3..efdf10e33 100644 --- a/doc/en/how-to/capture-warnings.rst +++ b/doc/en/how-to/capture-warnings.rst @@ -42,8 +42,18 @@ Running pytest now produces this output: -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html ======================= 1 passed, 1 warning in 0.12s ======================= -The ``-W`` flag can be passed to control which warnings will be displayed or even turn -them into errors: +Controlling warnings +-------------------- + +Similar to Python's `warning filter`_ and :option:`-W option ` flag, pytest provides +its own ``-W`` flag to control which warnings are ignored, displayed, or turned into +errors. See the `warning filter`_ documentation for more +advanced use-cases. + +.. _`warning filter`: https://docs.python.org/3/library/warnings.html#warning-filter + +This code sample shows how to treat any ``UserWarning`` category class of warning +as an error: .. code-block:: pytest @@ -96,9 +106,6 @@ all other warnings into errors. When a warning matches more than one option in the list, the action for the last matching option is performed. -Both ``-W`` command-line option and ``filterwarnings`` ini option are based on Python's own -:option:`-W option ` and :func:`warnings.simplefilter`, so please refer to those sections in the Python -documentation for other examples and advanced usage. .. _`filterwarnings`: