gh-103109: Document ignore_warnings() test support helper (GH-103110)

(cherry picked from commit 32937d6aa414ec7db5c63ef277f21db1880b3af4)

Co-authored-by: Charlie Zhao <zhaoyu_hit@qq.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 8e05ff39c109455549baf9759326f47b366198d7..0bddd31ae259d6ff49c1343a2e480898243ef45b 100644 (file)
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -1631,6 +1631,21 @@ The :mod:`test.support.warnings_helper` module provides support for warnings tes
 .. versionadded:: 3.10
 
 
+.. function:: ignore_warnings(*, category)
+
+   Suppress warnings that are instances of *category*,
+   which must be :exc:`Warning` or a subclass.
+   Roughly equivalent to :func:`warnings.catch_warnings`
+   with :meth:`warnings.simplefilter('ignore', category=category) <warnings.simplefilter>`.
+   For example::
+
+      @warning_helper.ignore_warnings(category=DeprecationWarning)
+      def test_suppress_warning():
+          # do something
+
+   .. versionadded:: 3.8
+
+
 .. function:: check_no_resource_warning(testcase)
 
    Context manager to check that no :exc:`ResourceWarning` was raised.  You

diff --git a/Lib/test/support/warnings_helper.py b/Lib/test/support/warnings_helper.py
index 28e96f88b24441d3ce631e0be5c1992d8e9ecef7..c1bf05623006784d4d09345a2017bcade20c8d29 100644 (file)
--- a/Lib/test/support/warnings_helper.py
+++ b/Lib/test/support/warnings_helper.py
@@ -44,7 +44,7 @@ def check_syntax_warning(testcase, statement, errtext='',
 
 
 def ignore_warnings(*, category):
-    """Decorator to suppress deprecation warnings.
+    """Decorator to suppress warnings.
 
     Use of context managers to hide warnings make diffs
     more noisy and tools like 'git blame' less useful.