[Python-checkins] gh-103109: Document ignore_warnings() test support helper (#103110)

[erlend-aasland]

https://github.com/python/cpython/commit/32937d6aa414ec7db5c63ef277f21db1880b3af4
commit: 32937d6aa414ec7db5c63ef277f21db1880b3af4
branch: main
author: Charlie Zhao <zhaoyu_hit at qq.com>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2023-04-03T00:18:25+02:00
summary:

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

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach at Gerlach.CAM>

files:
M Doc/library/test.rst
M Lib/test/support/warnings_helper.py

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index c60b4da75d1a..20f633b8f569 100644
--- 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
index 28e96f88b244..c1bf05623006 100644
--- 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.