Fixed #35666 -- Documented stacklevel usage and testing, and adjusted test suite accordingly.

Over the years we've had multiple instances of hit and misses when
emitting warnings: either setting the wrong stacklevel or not setting
it at all.

This work adds assertions for the existing warnings that were declaring
the correct stacklevel, but were lacking tests for it.

tests/deprecation/tests.py

@@ -20,12 +20,14 @@ class RenameMethodsTests(SimpleTestCase):
         the faulty method.
         """
         msg = "`Manager.old` method should be renamed `new`."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
 
             class Manager(metaclass=RenameManagerMethods):
                 def old(self):
                     pass
 
+        self.assertEqual(ctx.filename, __file__)
+
     def test_get_new_defined(self):
         """
         Ensure `old` complains and not `new` when only `new` is defined.
@@ -43,20 +45,23 @@ class RenameMethodsTests(SimpleTestCase):
         self.assertEqual(len(recorded), 0)
 
         msg = "`Manager.old` is deprecated, use `new` instead."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
             manager.old()
+        self.assertEqual(ctx.filename, __file__)
 
     def test_get_old_defined(self):
         """
         Ensure `old` complains when only `old` is defined.
         """
         msg = "`Manager.old` method should be renamed `new`."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
 
             class Manager(metaclass=RenameManagerMethods):
                 def old(self):
                     pass
 
+        self.assertEqual(ctx.filename, __file__)
+
         manager = Manager()
 
         with warnings.catch_warnings(record=True) as recorded:
@@ -65,8 +70,9 @@ class RenameMethodsTests(SimpleTestCase):
         self.assertEqual(len(recorded), 0)
 
         msg = "`Manager.old` is deprecated, use `new` instead."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
             manager.old()
+        self.assertEqual(ctx.filename, __file__)
 
     def test_deprecated_subclass_renamed(self):
         """
@@ -79,21 +85,25 @@ class RenameMethodsTests(SimpleTestCase):
                 pass
 
         msg = "`Deprecated.old` method should be renamed `new`."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
 
             class Deprecated(Renamed):
                 def old(self):
                     super().old()
 
+        self.assertEqual(ctx.filename, __file__)
+
         deprecated = Deprecated()
 
         msg = "`Renamed.old` is deprecated, use `new` instead."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
             deprecated.new()
+        self.assertEqual(ctx.filename, __file__)
 
         msg = "`Deprecated.old` is deprecated, use `new` instead."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
             deprecated.old()
+        self.assertEqual(ctx.filename, __file__)
 
     def test_renamed_subclass_deprecated(self):
         """
@@ -101,12 +111,14 @@ class RenameMethodsTests(SimpleTestCase):
         `old` subclass one that didn't.
         """
         msg = "`Deprecated.old` method should be renamed `new`."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
 
             class Deprecated(metaclass=RenameManagerMethods):
                 def old(self):
                     pass
 
+        self.assertEqual(ctx.filename, __file__)
+
         class Renamed(Deprecated):
             def new(self):
                 super().new()
@@ -119,8 +131,9 @@ class RenameMethodsTests(SimpleTestCase):
         self.assertEqual(len(recorded), 0)
 
         msg = "`Renamed.old` is deprecated, use `new` instead."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
             renamed.old()
+        self.assertEqual(ctx.filename, __file__)
 
     def test_deprecated_subclass_renamed_and_mixins(self):
         """
@@ -142,20 +155,24 @@ class RenameMethodsTests(SimpleTestCase):
                 super().old()
 
         msg = "`DeprecatedMixin.old` method should be renamed `new`."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
 
             class Deprecated(DeprecatedMixin, RenamedMixin, Renamed):
                 pass
 
+        self.assertEqual(ctx.filename, __file__)
+
         deprecated = Deprecated()
 
         msg = "`RenamedMixin.old` is deprecated, use `new` instead."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
             deprecated.new()
+        self.assertEqual(ctx.filename, __file__)
 
         msg = "`DeprecatedMixin.old` is deprecated, use `new` instead."
-        with self.assertWarnsMessage(DeprecationWarning, msg):
+        with self.assertWarnsMessage(DeprecationWarning, msg) as ctx:
             deprecated.old()
+        self.assertEqual(ctx.filename, __file__)
 
     def test_removedafternextversionwarning_pending(self):
         self.assertTrue(