[Python-checkins] bpo-42272: fix misleading warning filter message/module docs (#23172)

ezio-melotti webhook-mailer at python.org
Sun May 29 21:43:36 EDT 2022


https://github.com/python/cpython/commit/8136606769661c103c46d142e52ecbbbb88803f6
commit: 8136606769661c103c46d142e52ecbbbb88803f6
branch: main
author: Kevin Locke <kevin at kevinlocke.name>
committer: ezio-melotti <ezio.melotti at gmail.com>
date: 2022-05-30T03:43:32+02:00
summary:

bpo-42272: fix misleading warning filter message/module docs (#23172)

* 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 <kevin at kevinlocke.name>

* 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 <kevin at kevinlocke.name>

* bpo-42272: add warning filter doc changes to NEWS

Signed-off-by: Kevin Locke <kevin at kevinlocke.name>

files:
A Misc/NEWS.d/next/Documentation/2022-05-26-11-33-23.gh-issue-86438.kEGGmK.rst
M Doc/library/warnings.rst

diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index f7a1f70833b7f..43708f8021ad2 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.
@@ -207,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:
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 0000000000000..75abfdd63b8b2
--- /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`.



More information about the Python-checkins mailing list