From f7056eaff23b02aa081034cf21e9d918b4874484 Mon Sep 17 00:00:00 2001
From: Zac Hatfield-Dodds <zac.hatfield.dodds@gmail.com>
Date: Mon, 18 Apr 2022 20:07:39 -0700
Subject: [PATCH] gh-91435: docs review responses

---
 Doc/library/warnings.rst | 8 ++++++++
 Doc/whatsnew/3.11.rst    | 7 +++++++
 Lib/warnings.py          | 7 ++-----
 3 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index 289b28229e1a00..05a29627392c8f 100644
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -507,6 +507,10 @@ Available Context Managers
     protected. This argument exists primarily for testing the :mod:`warnings`
     module itself.
 
+    If the *action* argument is not None, the remaining arguments are passed
+    to :func:`simplefilter` as if it were called immediately on entering the
+    context.
+
     .. note::
 
         The :class:`catch_warnings` manager works by replacing and
@@ -514,3 +518,7 @@ Available Context Managers
         :func:`showwarning` function and internal list of filter
         specifications.  This means the context manager is modifying
         global state and therefore is not thread-safe.
+
+    .. versionchanged:: 3.11
+
+        Added the *action*, *category*, *lineno*, and *append* parameters.
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index 6540a255a0ed82..e037ea57f9ef34 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -521,6 +521,13 @@ venv
   Third party code that also creates new virtual environments should do the same.
   (Contributed by Miro Hrončok in :issue:`45413`.)
 
+warnings
+--------
+
+* :func:`warnings.catch_warnings` now accepts arguments for :func:`warnings.simplefilter`,
+  providing a more concise way to locally ignore warnings or convert them to errors.
+  (Contributed by Zac Hatfield-Dodds in :issue:`47074`.)
+
 zipfile
 -------
 
diff --git a/Lib/warnings.py b/Lib/warnings.py
index aa41932d343f84..7d8c4400127f7f 100644
--- a/Lib/warnings.py
+++ b/Lib/warnings.py
@@ -433,11 +433,8 @@ class catch_warnings(object):
     when testing the warnings module itself.
 
     If the 'action' argument is not None, the remaining arguments are passed
-    to warnings.simplefilter() as if it that call was the first line of the
-    with-statement.
-
-    .. versionchanged:: 3.11
-       Added the action, category, lineno, and append arguments.
+    to warnings.simplefilter() as if it were called immediately on entering the
+    context.
     """
 
     def __init__(self, *, record=False, module=None,