8000 bpo-42272: fix misleading warning filter message/module docs (#23172) · coderanger/cpython@8136606 · GitHub
[go: up one dir, main page]

Skip to content

Commit 8136606

Browse files
authored
bpo-42272: fix misleading warning filter message/module docs (python#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@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@kevinlocke.name> * bpo-42272: add warning filter doc changes to NEWS Signed-off-by: Kevin Locke <kevin@kevinlocke.name>
1 parent 4f195f9 commit 8136606

File tree

2 files changed

+13
-6
lines changed

2 files changed

+13
-6
lines changed

Doc/library/warnings.rst

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -154,14 +154,19 @@ the disposition of the match. Each entry is a tuple of the form (*action*,
154154
+---------------+----------------------------------------------+
155155

156156
* *message* is a string containing a regular expression that the start of
157-
the warning message must match. The expression is compiled to always be
158-
case-insensitive.
157+
the warning message must match, case-insensitively. In :option:`-W` and
158+
:envvar:`PYTHONWARNINGS`, *message* is a literal string that the start of the
159+
warning message must contain (case-insensitively), ignoring any whitespace at
160+
the start or end of *message*.
159161

160162
* *category* is a class (a subclass of :exc:`Warning`) of which the warning
161163
category must be a subclass in order to match.
162164

163-
* *module* is a string containing a regular expression that the module name must
164-
match. The expression is compiled to be case-sensitive.
165+
* *module* is a string containing a regular expression that the start of the
166+
fully-qualified module name must match, case-sensitively. In :option:`-W` and
167+
:envvar:`PYTHONWARNINGS`, *module* is a literal string that the
168+
fully-qualified module name must be equal to (case-sensitively), ignoring any
169+
whitespace at the start or end of *module*.
165170

166171
* *lineno* is an integer that the line number where the warning occurred must
167172
match, or ``0`` to match all line numbers.
@@ -207,8 +212,7 @@ Some examples::
207212
error::ResourceWarning # Treat ResourceWarning messages as errors
208213
default::DeprecationWarning # Show DeprecationWarning messages
209214
ignore,default:::mymodule # Only report warnings triggered by "mymodule"
210-
error:::mymodule[.*] # Convert warnings to errors in "mymodule"
211-
# and any subpackages of "mymodule"
215+
error:::mymodule # Convert warnings to errors in "mymodule"
212216

213217

214218
.. _default-warning-filter:
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Clarify that :option:`-W` and :envvar:`PYTHONWARNINGS` are matched literally
2+
and case-insensitively, rather than as regular expressions, in
3+
:mod:`warnings`.

0 commit comments

Comments
 (0)
0