gh-93343: Expand warning filter examples

daniel-shimon · daniel-shimon · commit 826cd017615b · 2023-07-12T13:52:00.000Z
Add examples of warning filters and the difference between programatic and environmental filters.
diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
@@ -214,6 +214,30 @@ Some examples::
    ignore,default:::mymodule    # Only report warnings triggered by "mymodule"
    error:::mymodule             # Convert warnings to errors in "mymodule"
 
+.. _warning-filter-examples:
+
+Warning Filter Examples
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some complex examples for filtering warnings.
+
+Note that :func:`filterwarnings` filters have subtle differences
+from :option:`-W` and :envvar:`PYTHONWARNINGS` regarding the *message* and *module*
+parts of the filter (as described in :ref:`warning-filter`).
+
+   filterwarnings("ignore", message=".*generic", module=r"yourmodule\.submodule")
+      # Ignore warnings in "yourmodule.submodule" which contain "generic"
+   filterwarnings("ignore", message="generic", module=r"yourmodule\.submodule")
+      # Ignore warnings in "yourmodule.submodule" which START with "generic"
+   filterwarnings("ignore", module="yourmodule.*")
+      # Ignore all warnings in "yourmodule" and its submodules
+
+   -W "ignore:generic::yourmodule.submodule:"
+      # Ignore warnings in "yourmodule.submodule" which START with "generic" (but not those containing it).
+      # Also note that the '.' in the module does not need to be escaped since it is not a regex
+   -W "ignore:::yourmodule:"
+      # Ignore all warnings in "yourmodule", but NOT in its submodules
+
 
 .. _default-warning-filter:
 
diff --git a/Misc/NEWS.d/next/Documentation/2023-07-11-08-46-13.gh-issue-93343.fw_eyw.rst b/Misc/NEWS.d/next/Documentation/2023-07-11-08-46-13.gh-issue-93343.fw_eyw.rst
@@ -0,0 +1,2 @@
+Add examples of warning filters and the difference between programmatic and
+environmental filters.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Add examples of warning filters and the difference between programmatic and`
	`2`	`+environmental filters.`