8000 MNT: Add provisional get_backend(resolve=False) flag · matplotlib/matplotlib@e13b9e4 · GitHub
[go: up one dir, main page]
Skip to content

Commit e13b9e4

Browse files
timhoffmtimhoffm
committed
MNT: Add provisional get_backend(resolve=False) flag
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.
1 parent 202a277 commit e13b9e4

File tree

3 files changed

+30
-4
lines changed

3 files changed

+30
-4
lines changed

‎lib/matplotlib/__init__.py

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1296,15 +1296,37 @@ def use(backend, *, force=True):
12961296
rcParams['backend'] = os.environ.get('MPLBACKEND')
12971297

12981298

1299-
def get_backend():
1299+
def get_backend(*, auto_select=True):
13001300
"""
13011301
Return the name of the current backend.
13021302
1303+
Parameters
1304+
----------
1305+
auto_select : bool, default: True
1306+
Whether to trigger backend resolution if no backend has been
1307+
selected so far. If True, this ensures that a valid backend
1308+
is returned. If False, this returns None if no backend has been
1309+
selected so far.
1310+
1311+
.. versionadded:: 3.10
1312+
1313+
.. admonition:: Provisional
1314+
1315+
The *auto_select* flag is provisional. It may be changed or removed
1316+
without prior warning.
1317+
13031318
See Also
13041319
--------
13051320
matplotlib.use
13061321
"""
1307-
return rcParams['backend']
1322+
if auto_select:
1323+
return rcParams['backend']
1324+
else:
1325+
backend = rcParams._get('backend')
1326+
if backend is rcsetup._auto_backend_sentinel:
1327+
return None
1328+
else:
1329+
return backend
13081330

13091331

13101332
def interactive(b):

‎lib/matplotlib/__init__.pyi

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ import contextlib
3737
from packaging.version import Version
3838

3939
from matplotlib._api import MatplotlibDeprecationWarning
40-
from typing import Any, NamedTuple
40+
from typing import Any, Literal, NamedTuple, overload
4141

4242
class _VersionInfo(NamedTuple):
4343
major: int
@@ -104,7 +104,10 @@ def rc_context(
104104
rc: dict[str, Any] | None = ..., fname: str | Path | os.PathLike | None = ...
105105
) -> Generator[None, None, None]: ...
106106
def use(backend: str, *, force: bool = ...) -> None: ...
107-
def get_backend() -> str: ...
107+
@overload
108+
def get_backend(*, auto_select: Literal[True] = True) -> str: ...
109+
@overload
110+
def get_backend(*, auto_select: Literal[False]) -> str | None: ...
108111
def interactive(b: bool) -> None: ...
109112
def is_interactive() -> bool: ...
110113

‎lib/matplotlib/tests/test_rcparams.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -554,6 +554,7 @@ def test_backend_fallback_headful(tmp_path):
554554
# Check that access on another instance does not resolve the sentinel.
555555
"assert mpl.RcParams({'backend': sentinel})['backend'] == sentinel; "
556556
"assert mpl.rcParams._get('backend') == sentinel; "
557+
"assert mpl.get_backend(auto_select=False) is None; "
557558
"import matplotlib.pyplot; "
558559
"print(matplotlib.get_backend())"],
559560
env=env, text=True, check=True, capture_output=True).stdout

0 commit comments

Comments
 (0)
0