Simplify _api.warn_external on Python 3.12+

Python 3.12 added the `skip_file_prefixes` argument, which essentially
does what this helper function does for us.

Technically, I think the old implementation would set the stack level to
the tests, if called in one, but this one doesn't. However, that
shouldn't be a problem, as either 1) warnings are errors, or 2), we
catch the warning with `pytest.warns` and don't see the stack level.

Author: QuLogic

lib/matplotlib/_api/__init__.py

@@ -12,6 +12,7 @@
 
 import functools
 import itertools
+import pathlib
 import re
 import sys
 import warnings
@@ -366,16 +367,25 @@ def warn_external(message, category=None):
     warnings.warn`` (or ``functools.partial(warnings.warn, stacklevel=2)``,
     etc.).
     """
-    frame = sys._getframe()
-    for stacklevel in itertools.count(1):
-        if frame is None:
-            # when called in embedded context may hit frame is None
-            break
-        if not re.match(r"\A(matplotlib|mpl_toolkits)(\Z|\.(?!tests\.))",
-                        # Work around sphinx-gallery not setting __name__.
-                        frame.f_globals.get("__name__", "")):
-            break
-        frame = frame.f_back
-    # preemptively break reference cycle between locals and the frame
-    del frame
-    warnings.warn(message, category, stacklevel)
+    kwargs = {}
+    if sys.version_info[:2] >= (3, 12):
+        # Go to Python's `site-packages` or `lib` from an editable install.
+        basedir = pathlib.Path(__file__).parents[2]
+        kwargs['skip_file_prefixes'] = (str(basedir / 'matplotlib'),
+                                        str(basedir / 'mpl_toolkits'))
+    else:
+        frame = sys._getframe()
+        for stacklevel in itertools.count(1):
+            if frame is None:
+                # when called in embedded context may hit frame is None
+                kwargs['stacklevel'] = stacklevel
+                break
+            if not re.match(r"\A(matplotlib|mpl_toolkits)(\Z|\.(?!tests\.))",
+                            # Work around sphinx-gallery not setting __name__.
+                            frame.f_globals.get("__name__", "")):
+                kwargs['stacklevel'] = stacklevel
+                break
+            frame = frame.f_back
+        # preemptively break reference cycle between locals and the frame
+        del frame
+    warnings.warn(message, category, **kwargs)

lib/matplotlib/tests/test_cbook.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
-import sys
 import itertools
+import pathlib
 import pickle
+import sys
 
 from typing import Any
 from unittest.mock import patch, Mock
@@ -478,6 +479,22 @@ def test_normalize_kwargs_pass(inp, expected, kwargs_to_norm):
         assert expected == cbook.normalize_kwargs(inp, **kwargs_to_norm)
 
 
+def test_warn_external(recwarn):
+    _api.warn_external("oops")
+    assert len(recwarn) == 1
+    if sys.version_info[:2] >= (3, 12):
+        # With Python 3.12, we let Python figure out the stacklevel using the
+        # `skip_file_prefixes` argument, which cannot exempt tests, so just confirm
+        # the filename is not in the package.
+        basedir = pathlib.Path(__file__).parents[2]
+        assert not recwarn[0].filename.startswith((str(basedir / 'matplotlib'),
+                                                   str(basedir / 'mpl_toolkits')))
+    else:
+        # On older Python versions, we manually calculated the stacklevel, and had an
+        # exception for our own tests.
+        assert recwarn[0].filename == __file__
+
+
 def test_warn_external_frame_embedded_python():
     with patch.object(cbook, "sys") as mock_sys:
         mock_sys._getframe = Mock(return_value=None)
@@ -784,12 +801,6 @@ def test_safe_first_element_pandas_series(pd):
     assert actual == 0
 
 
-def test_warn_external(recwarn):
-    _api.warn_external("oops")
-    assert len(recwarn) == 1
-    assert recwarn[0].filename == __file__
-
-
 def test_array_patch_perimeters():
     # This compares the old implementation as a reference for the
     # vectorized one.