gh-117146: Expose/document warnings.WarningMessage

Doc/library/warnings.rst

@@ -581,10 +581,9 @@ Available Context Managers
     and the :func:`showwarning` function.
     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`.
+    returned that is progressively populated with :class:`WarningMessage` objects
+    as seen by a custom :func:`showwarning` function (which also suppresses output
+    to ``sys.stdout``).
 
     The *module* argument takes a module that will be used instead of the
     module returned when you import :mod:`warnings` whose filter will be
@@ -606,3 +605,15 @@ Available Context Managers
     .. versionchanged:: 3.11
 
         Added the *action*, *category*, *lineno*, and *append* parameters.
+
+:class:`WarningMessage` Objects
+-------------------------------
+
+A :class:`WarningMessage` object represents a warning along with information about its emission. It
+is primarily used by :class:`catch_warnings` with *record* set to :const:`True` to record warnings.
+
+.. class:: WarningMessage(message, category, filename, lineno, file=None, line=None, source=None)
+
+   *message*, *category*, *filename*, *lineno*, *file* and *line* have the same meaning as
+   in :func:`showwarning`. *source* is optionally given to indicate the destroyed object which
+   emitted a :exc:`ResourceWarning`.

Lib/test/test_warnings/__init__.py

@@ -93,7 +93,8 @@ def test_module_all_attribute(self):
         self.assertTrue(hasattr(self.module, '__all__'))
         target_api = ["warn", "warn_explicit", "showwarning",
                       "formatwarning", "filterwarnings", "simplefilter",
-                      "resetwarnings", "catch_warnings", "deprecated"]
+                      "resetwarnings", "catch_warnings", "deprecated",
+                      "WarningMessage"]
         self.assertSetEqual(set(self.module.__all__),
                             set(target_api))
 

Lib/warnings.py

@@ -5,7 +5,8 @@
 
 __all__ = ["warn", "warn_explicit", "showwarning",
            "formatwarning", "filterwarnings", "simplefilter",
-           "resetwarnings", "catch_warnings", "deprecated"]
+           "resetwarnings", "catch_warnings", "deprecated",
+           "WarningMessage"]
 
 def showwarning(message, category, filename, lineno, file=None, line=None):
     """Hook to write a warning to a file; replace if you like."""

Misc/NEWS.d/next/Documentation/2024-03-22-03-45-21.gh-issue-117146.--QGtr.rst

@@ -0,0 +1 @@
+Expose and document :class:`warnings.WarningMessage`.