gh-93343: Expand warning filter examples #106618

daniel-shimon · 2023-07-11T08:53:29Z

Add examples of warning filters and the difference between programatic and environmental filters.

Issue: Add more examples in the warnings docs #93343

📚 Documentation preview 📚: https://cpython-previews--106618.org.readthedocs.build/

ghost · 2023-07-11T08:53:56Z

All commit authors signed the Contributor License Agreement.

ezio-melotti

Thanks for the PR!
This is a step in the right direction, but there are more subtleties in pytest-dev/pytest#8759 (comment) that are not described here.

In particular:

Where/when can I uses regexes vs plain text? This applies to both different types of filters (filterwarnings()/-W/PYTHONWARNINGS) and different fields within a filter (message/package/module).
How to match part of a message with the different types of filters (beginning of the message vs substring).
How to filter messages coming from specific packages/modules/submodules with the different types of filters.

I think this would be better covered in a new section of the warnings docs -- either a generic Examples section that includes these alongside with comments and explanations, or a more specific section that focuses on the differences between the different warnings types. A mini-howto might also be an option, but we can start with a single section and expand it later.

In addition, since you would have to test different filters to ensure that the behavior you are documenting is correct, it might be worth adding some of these examples to the warnings tests in Lib/test.

ezio-melotti · 2023-07-11T09:12:04Z

Doc/library/warnings.rst


+Note that :func:`filterwarnings` filters have subtle differences from :option:`-W` and :envvar:`PYTHONWARNINGS`::
+
+   filterwarnings("ignore", message=".*generic", module=r"yourmodule\.submodule")


Suggested change

filterwarnings("ignore", message=".*generic", module=r"yourmodule\.submodule")

filterwarnings("ignore", message="\.*generic", module="yourmodule\.submodule")

Shouldn't this be escaped as well? The r here is not necessary, and its usage should be consistent between the two args (assuming they are both regexes).

No since the first arg wants to capture strings that contain 'generic' so that the '.' catches everything, while the first arg want to capture 'yourmodule.submodule' specifically, meaning that the '.' actually captures dot and should be escaped

Well, it sounds to me you should put that explanation into the docs, @daniel-shimon; if it is unclear for a reviewer, it is not going to be clear for the average docs reader ;)

Doc/library/warnings.rst

Misc/NEWS.d/next/Documentation/2023-07-11-08-46-13.gh-issue-93343.fw_eyw.rst

Doc/library/warnings.rst

Add examples of warning filters and the difference between programatic and environmental filters.

daniel-shimon · 2023-07-12T14:11:15Z

Hi @ezio-melotti, thanks for the fast review!
I moved the examples to a separate section and elaborated a bit on the explanations.

Where/when can I uses regexes vs plain text? This applies to both different types of filters (filterwarnings()/-W/PYTHONWARNINGS) and different fields within a filter (message/package/module).
How to match part of a message with the different types of filters (beginning of the message vs substring).

I've linked to the warning filter definitions since I think they explain this concisely and don't think we need to add another section repeating the same info. What do you think?

erlend-aasland · 2023-07-12T20:44:50Z

FYI, @daniel-shimon: please don't force push; it does not play well with the GitHub UI, and especially not with review remarks and CI. You can use git pull --no-ff main instead. See also https://devguide.python.org/getting-started/pull-request-lifecycle/

erlend-aasland · 2023-07-12T20:53:53Z

Oh, it seems like none of the example code in Doc/library/warnings.rst is checked by doctest :( That is unfortunate! I don't remember the doctest specifics, but if it is possible, please make is so that at least the added examples are run through doctest. If not, adding doctests to this .rst file is out of scope for this PR, but it should be done.

daniel-shimon · 2023-07-12T23:16:10Z

@erlend-aasland so actually this was because I amended the commit, cause I thought it was weird to have "pr fixes" in the main Python repo after accepting the pr.
So should I add new commits and squash before merge? What is the practice here?

daniel-shimon · 2023-07-14T10:54:40Z

Ok I see and understand that now, thanks guys 🙌

erlend-aasland · 2023-07-14T11:38:35Z

Ok I see and understand that now, thanks guys 🙌

np, and thanks for improving the docs! I recommend spending some hours with the devguide; there's a lot of useful information there :) Also, if you find sections in the devguide that are hard to grasp, or just worded badly, don't hesitate to open an issue over at the devguide repo; fixing devguide bugs is one of the most important things we can do :)

hugovk · 2024-07-14T08:58:03Z

Hello from +1 year! Where are we up to on this PR? It looks like there's still some suggestions for @daniel-shimon to address, would you like update the PR? Thanks!

hugovk

Ping :)

bedevere-app · 2024-10-24T17:56:18Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

donbarbos · 2025-04-29T21:01:25Z

another half year has passed :)
I don't know how long it should take after adding pending label, but I suggest waiting the last 2 weeks (another attempt @daniel-shimon)

daniel-shimon · 2025-04-30T14:17:31Z

Hi!
Wow somehow I've missed the emails about this PR and was sure it was long forgotten 😅
I'll address the comments in the upcoming days, thanks for the ping!

daniel-shimon · 2025-05-07T08:00:03Z

Hi @erlend-aasland , I added clarifications regarding escaping and regexes.
Could you take a look?
Thanks!

picnixz · 2025-11-15T18:05:04Z

Doc/library/warnings.rst

+      #   in order to match a literal dot character.
+   filterwarnings("ignore", message="generic", module=r"yourmodule\.submodule")


I think those examples should be separated by a new line for clarity purposes.

picnixz · 2025-11-15T18:06:19Z

Lib/test/test_warnings/__init__.py


+    def test_string_literals(self):
+        # Ensure message/module are treated as string literals
+        rc, stdout, stderr = assert_python_ok("-c",


If you use rc, check its value as well. Otherwise use _, stdout, stderr = ...

daniel-shimon

Fix CR Comments

daniel-shimon · 2025-11-23T09:23:38Z

Hi @picnixz, thanks for the review! I've fixed your comments 🙏

bedevere-bot added awaiting review docs Documentation in the Doc dir labels Jul 11, 2023

bedevere-bot mentioned this pull request Jul 11, 2023

Add more examples in the warnings docs #93343

Open

ezio-melotti reviewed Jul 11, 2023

View reviewed changes

ezio-melotti requested review from CAM-Gerlach, erlend-aasland and hugovk July 11, 2023 09:24

daniel-shimon force-pushed the gh-93343-extra-warning-examples branch from 5c2f95e to 826cd01 Compare July 12, 2023 13:52

pythongh-93343: Expand warning filter examples

e43adf8

Add examples of warning filters and the difference between programatic and environmental filters.

daniel-shimon force-pushed the gh-93343-extra-warning-examples branch from 826cd01 to e43adf8 Compare July 12, 2023 14:08

pythongh-93343: Add warning filters tests

f3684a6

This comment was marked as resolved.

Sign in to view

hugovk requested changes Oct 24, 2024

View reviewed changes

bedevere-app bot added awaiting changes and removed awaiting review labels Oct 24, 2024

hugovk added the pending The issue will be closed if no feedback is provided label Oct 24, 2024

daniel-shimon added 2 commits May 7, 2025 00:08

Clarify escaped dots in regexes

f16ae2d

Merge branch 'main' into pythongh-93343-extra-warning-examples

e6251be

picnixz removed the pending The issue will be closed if no feedback is provided label Nov 15, 2025

picnixz reviewed Nov 15, 2025

View reviewed changes

daniel-shimon commented Nov 23, 2025

View reviewed changes

Fix CR Comments

53a8662


		Note that :func:`filterwarnings` filters have subtle differences from :option:`-W` and :envvar:`PYTHONWARNINGS`::

		filterwarnings("ignore", message=".*generic", module=r"yourmodule\.submodule")

	filterwarnings("ignore", message=".*generic", module=r"yourmodule\.submodule")
	filterwarnings("ignore", message="\.*generic", module="yourmodule\.submodule")

		# in order to match a literal dot character.
		filterwarnings("ignore", message="generic", module=r"yourmodule\.submodule")

Uh oh!

gh-93343: Expand warning filter examples #106618

Are you sure you want to change the base?

gh-93343: Expand warning filter examples #106618

Uh oh!

Conversation

daniel-shimon commented Jul 11, 2023 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ghost commented Jul 11, 2023 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ezio-melotti left a comment

Choose a reason for hiding this comment

Uh oh!

ezio-melotti Jul 11, 2023

Choose a reason for hiding this comment

Uh oh!

daniel-shimon Jul 12, 2023

Choose a reason for hiding this comment

Uh oh!

erlend-aasland Jul 12, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

daniel-shimon commented Jul 12, 2023

Uh oh!

erlend-aasland commented Jul 12, 2023

Uh oh!

erlend-aasland commented Jul 12, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

daniel-shimon commented Jul 12, 2023

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

daniel-shimon commented Jul 14, 2023

Uh oh!

erlend-aasland commented Jul 14, 2023

Uh oh!

hugovk commented Jul 14, 2024

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

bedevere-app bot commented Oct 24, 2024

Uh oh!

donbarbos commented Apr 29, 2025

Uh oh!

daniel-shimon commented Apr 30, 2025

Uh oh!

daniel-shimon commented May 7, 2025

Uh oh!

picnixz Nov 15, 2025

Choose a reason for hiding this comment

Uh oh!

picnixz Nov 15, 2025

Choose a reason for hiding this comment

Uh oh!

daniel-shimon left a comment

Choose a reason for hiding this comment

Uh oh!

daniel-shimon commented Nov 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

daniel-shimon commented Jul 11, 2023 •

edited by github-actions bot

Loading

ghost commented Jul 11, 2023 •

edited by ghost

Loading

erlend-aasland commented Jul 12, 2023 •

edited

Loading