From a2a610075a327e00dd3ca23eed83fd558b0851aa Mon Sep 17 00:00:00 2001 From: Kevin Locke Date: Thu, 5 Nov 2020 12:54:51 -0700 Subject: [PATCH 1/3] bpo-42272: improve message/module warning filter docs "The Warnings Filter" section of the warnings module documentation describes the message and module filters as "a string containing a regular expression". While that is true when they are arguments to the filterwarnings function, it is not true when they appear in -W or $PYTHONWARNINGS where they are matched literally (after stripping any starting/ending whitespace). Update the documentation to note when they are matched literally. Also clarify that module matches the "fully-qualified module name", rather than "module name" which is ambiguous. skip news (since this is a doc fix) Signed-off-by: Kevin Locke --- Doc/library/warnings.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index a481a3509d4ec8..02eec8fedc9563 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -154,14 +154,19 @@ the disposition of the match. Each entry is a tuple of the form (*action*, +---------------+----------------------------------------------+ * *message* is a string containing a regular expression that the start of - the warning message must match. The expression is compiled to always be - case-insensitive. + the warning message must match, case-insensitively. In :option:`-W` and + :envvar:`PYTHONWARNINGS`, *message* 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*. * *category* is a class (a subclass of :exc:`Warning`) of which the warning category must be a subclass in order to match. -* *module* is a string containing a regular expression that the module name must - match. The expression is compiled to be case-sensitive. +* *module* is a string containing a regular expression that the start of the + fully-qualified module name must match, case-sensitively. In :option:`-W` and + :envvar:`PYTHONWARNINGS`, *module* is a literal string that the + fully-qualified module name must be equal to (case-sensitively), ignoring any + whitespace at the start or end of *module*. * *lineno* is an integer that the line number where the warning occurred must match, or ``0`` to match all line numbers. From 1767ef9ed9384ef447e97f1194401c0d084c7ea1 Mon Sep 17 00:00:00 2001 From: Kevin Locke Date: Thu, 5 Nov 2020 13:00:05 -0700 Subject: [PATCH 2/3] bpo-42272: remove bad submodule warning filter doc The `error:::mymodule[.*]` example in the "Describing Warning Filters" section of the warnings module documentation does not behave as the comment describes. Since the module portion of the filter string is interpreted literally, it would match a module with a fully-qualified name that is literally `mymodule[.*]`. Unfortunately, there is not a way to match '"module" and any subpackages of "mymodule"' as documented, since the module part of a filter string is matched literally. Instead, update the filter and comment to match only "mymodule". skip news (since this is a doc fix) Signed-off-by: Kevin Locke --- Doc/library/warnings.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index 02eec8fedc9563..b63b0073aafeff 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -212,8 +212,7 @@ Some examples:: error::ResourceWarning # Treat ResourceWarning messages as errors default::DeprecationWarning # Show DeprecationWarning messages ignore,default:::mymodule # Only report warnings triggered by "mymodule" - error:::mymodule[.*] # Convert warnings to errors in "mymodule" - # and any subpackages of "mymodule" + error:::mymodule # Convert warnings to errors in "mymodule" .. _default-warning-filter: From b15ea56a41b549086ca76a4a2ed173b14d678ddd Mon Sep 17 00:00:00 2001 From: Kevin Locke Date: Thu, 26 May 2022 11:59:02 -0600 Subject: [PATCH 3/3] bpo-42272: add warning filter doc changes to NEWS Signed-off-by: Kevin Locke --- .../2022-05-26-11-33-23.gh-issue-86438.kEGGmK.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2022-05-26-11-33-23.gh-issue-86438.kEGGmK.rst diff --git a/Misc/NEWS.d/next/Documentation/2022-05-26-11-33-23.gh-issue-86438.kEGGmK.rst b/Misc/NEWS.d/next/Documentation/2022-05-26-11-33-23.gh-issue-86438.kEGGmK.rst new file mode 100644 index 00000000000000..75abfdd63b8b2e --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2022-05-26-11-33-23.gh-issue-86438.kEGGmK.rst @@ -0,0 +1,3 @@ +Clarify that :option:`-W` and :envvar:`PYTHONWARNINGS` are matched literally +and case-insensitively, rather than as regular expressions, in +:mod:`warnings`.