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

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
python · Apr 2, 2023 · 32937d6 · 32937d6
1 parent 6883007
commit 32937d6
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 1 deletion.
diff --git a/Doc/library/test.rst b/Doc/library/test.rst
@@ -1691,6 +1691,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
@@ -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.