gh-139837: Document attributes of objects recorded by warnings.catch_warnings (GH...

Co-authored-by: Victor Stinner <vstinner@python.org>

diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index b25384dbfce54bbde28649fbe50cc7daef65d97a..9063bea96ccb0ac37703d55cd7f5025266067787 100644 (file)
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -626,9 +626,28 @@ Available Context Managers
     If the *record* argument is :const:`False` (the default) the context manager
     returns :class:`None` on entry. If *record* is :const:`True`, a list is
     returned that is progressively populated with objects as seen by a custom
-    :func:`showwarning` function (which also suppresses output to ``sys.stdout``).
-    Each object in the list has attributes with the same names as the arguments to
-    :func:`showwarning`.
+    :func:`showwarning` function (which also suppresses output to ``sys.stderr``).
+    Each object in the list is guaranteed to have the following attributes:
+
+      - ``message``: the warning message (an instance of :exc:`Warning`)
+      - ``category``: the warning category (a subclass of :exc:`Warning`)
+      - ``filename``: the file name where the warning occurred (:class:`str`)
+      - ``lineno``: the line number in the file (:class:`int`)
+      - ``file``: the file object used for output (if any), or ``None``
+      - ``line``: the line of source code (if available), or ``None``
+      - ``source``: the original object that generated the warning (if
+        available), or ``None``
+      - ``module``: the module name where the warning occurred
+        (:class:`str`), or ``None``
+
+    .. versionchanged:: 3.6
+      The ``source`` attribute was added.
+
+    .. versionchanged:: 3.15
+      The ``module`` attribute was added.
+
+    The type of these objects is not specified and may change; only the
+    presence of these attributes is guaranteed.
 
     The *module* argument takes a module that will be used instead of the
     module returned when you import :mod:`!warnings` whose filter will be