From af990401236973b7f9c1cd319c0d180741d1fe2e Mon Sep 17 00:00:00 2001 From: Mahesh Vashishtha Date: Tue, 7 Feb 2023 16:27:34 -0600 Subject: [PATCH] Add a note about -W vs filterwarnings. (#10713) Closes #10687 Signed-off-by: mvashishtha --- doc/en/how-to/capture-warnings.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/en/how-to/capture-warnings.rst b/doc/en/how-to/capture-warnings.rst index 51e85badd..0390230b8 100644 --- a/doc/en/how-to/capture-warnings.rst +++ b/doc/en/how-to/capture-warnings.rst @@ -109,6 +109,18 @@ When a warning matches more than one option in the list, the action for the last is performed. +.. note:: + + The ``-W`` flag and the ``filterwarnings`` ini option use warning filters that are + similar in structure, but each configuration option interprets its filter + differently. For example, *message* in ``filterwarnings`` is a string containing a + regular expression that the start of the warning message must match, + case-insensitively, while *message* in ``-W`` is a literal string that the start of + the warning message must contain (case-insensitively), ignoring any whitespace at + the start or end of message. Consult the `warning filter`_ documentation for more + details. + + .. _`filterwarnings`: ``@pytest.mark.filterwarnings``