gh-93343: Expand warning filter examples

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

Author: daniel-shimon

Doc/library/warnings.rst

@@ -214,6 +214,34 @@ 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:
 

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.