MNT: Add provisional get_backend(resolve=False) flag

timhoffm · timhoffm · commit d33a44b1ea9d · 2024-10-29T16:39:27.000+01:00
The default is `resolve=True` for now, so that this introduction is completely backward-compatible. The provisional introduction anticipates planned changes for the backend resolution (#26406 (comment)). If all plays out as intended, this prolongs the range of releases for the migration: If we start deprecating `rcParams._get("backend")` say in 3.11, people can immediately switch to `get_backend(resolve=False)` and their code still runs on 3.10 without version gating. The worst that can happen is that the introduced flag was not helpful and we remove it again, which is easy because it's provisional.
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1296,15 +1296,37 @@ def use(backend, *, force=True):
     rcParams['backend'] = os.environ.get('MPLBACKEND')
 
 
-def get_backend():
+def get_backend(*, resolve: bool = True):
     """
     Return the name of the current backend.
 
+    Parameters
+    ----------
+    resolve : bool, default: True
+        Whether to trigger backend resolution if no backend has been
+        selected so far. If True, this ensures that a valid backend
+        is returned. If False, this returns None if no backend has been
+        selected so far.
+
+        .. admonition:: Provisional resolve flag
+
+           The *resolve* flag is introduced provisionally in the anticipation
+           of backend resolution refactoring. We don't guarantee API stability
+           for now, but if all plays out well, the provisional availability
+           will prolong the range of supported releases for the migration period.
+
     See Also
     --------
     matplotlib.use
     """
-    return rcParams['backend']
+    if resolve:
+        return rcParams['backend']
+    else:
+        backend = rcParams._get('backend')
+        if backend is rcsetup._auto_backend_sentinel():
+            return None
+        else:
+            return backend
 
 
 def interactive(b):
diff --git a/lib/matplotlib/__init__.pyi b/lib/matplotlib/__init__.pyi
@@ -37,7 +37,7 @@ import contextlib
 from packaging.version import Version
 
 from matplotlib._api import MatplotlibDeprecationWarning
-from typing import Any, NamedTuple
+from typing import Any, Literal, NamedTuple, overload
 
 class _VersionInfo(NamedTuple):
     major: int
@@ -104,7 +104,10 @@ def rc_context(
     rc: dict[str, Any] | None = ..., fname: str | Path | os.PathLike | None = ...
 ) -> Generator[None, None, None]: ...
 def use(backend: str, *, force: bool = ...) -> None: ...
-def get_backend() -> str: ...
+@overload
+def get_backend(*, resolve: Literal[True] = True) -> str: ...
+@overload
+def get_backend(*, resolve: Literal[False]) -> str | None: ...
 def interactive(b: bool) -> None: ...
 def is_interactive() -> bool: ...
 
diff --git a/lib/matplotlib/tests/test_rcparams.py b/lib/matplotlib/tests/test_rcparams.py
@@ -554,6 +554,7 @@ def test_backend_fallback_headful(tmp_path):
          # Check that access on another instance does not resolve the sentinel.
          "assert mpl.RcParams({'backend': sentinel})['backend'] == sentinel; "
          "assert mpl.rcParams._get('backend') == sentinel; "
+         "assert matplotlib.get_backend(resolve=False) is None; "
          "import matplotlib.pyplot; "
          "print(matplotlib.get_backend())"],
         env=env, text=True, check=True, capture_output=True).stdout
