[3.14] gh-139837: Document attributes of objects recorded by warnings.catch_warnings...

* gh-139837: Document attributes of objects recorded by warnings.catch_warnings (GH-139893)
(cherry picked from commit 47b7dc788c9bcf3d5ea69a2ea0aed3d5883647a8)

Co-authored-by: Aniket <148300120+Aniketsy@users.noreply.github.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
* Apply suggestions from code review

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
---------

Co-authored-by: Aniket <148300120+Aniketsy@users.noreply.github.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index 01c316bbfd39fca7246fd1957e9d0c317bca98c6..b04302821e0a2af668d7d12b32fe111596620184 100644 (file)
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -611,9 +611,23 @@ 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``
+
+    .. versionchanged:: 3.6
+      The ``source`` 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