Add BackendRegistry singleton class

Author: ianthomas23

lib/matplotlib/backend_bases.py

@@ -104,16 +104,12 @@ def _safe_pyplot_import():
         current_framework = cbook._get_running_interactive_framework()
         if current_framework is None:
             raise  # No, something else went wrong, likely with the install...
-        backend_mapping = {
-            'qt': 'qtagg',
-            'gtk3': 'gtk3agg',
-            'gtk4': 'gtk4agg',
-            'wx': 'wxagg',
-            'tk': 'tkagg',
-            'macosx': 'macosx',
-            'headless': 'agg',
-        }
-        backend = backend_mapping[current_framework]
+
+        from matplotlib.backends.registry import backendRegistry
+        backend = backendRegistry.framework_to_backend(current_framework)
+        if backend is None:
+            raise KeyError(backend)
+
         rcParams["backend"] = mpl.rcParamsOrig["backend"] = backend
         import matplotlib.pyplot as plt  # Now this should succeed.
     return plt

lib/matplotlib/backends/meson.build

@@ -33,6 +33,7 @@ python_sources = [
   'backend_wxagg.py',
   'backend_wxcairo.py',
   'qt_compat.py',
+  'registry.py',
 ]
 
 typing_sources = [

lib/matplotlib/backends/registry.py

@@ -0,0 +1,61 @@
+from enum import Enum
+
+
+class BackendFilter(Enum):
+    INTERACTIVE = 0
+    INTERACTIVE_NON_WEB = 1
+    NON_INTERACTIVE = 2
+
+
+class BackendRegistry:
+    """
+    Registry of backends available within Matplotlib.
+
+    This is the single source of truth for available backends.
+    """
+    def __init__(self):
+        # Built-in backends are those which are included in the Matplotlib repo.
+        # A backend with name 'name' is located in the module
+        # f'matplotlib.backends.backend_{name.lower()}'
+
+        # The capitalized forms are needed for ipython at present; this may
+        # change for later versions.
+        self._builtin_interactive = [
+            "GTK3Agg", "GTK3Cairo", "GTK4Agg", "GTK4Cairo",
+            "MacOSX",
+            "nbAgg",
+            "QtAgg", "QtCairo", "Qt5Agg", "Qt5Cairo",
+            "TkAgg", "TkCairo",
+            "WebAgg",
+            "WX", "WXAgg", "WXCairo",
+        ]
+        self._builtin_not_interactive = [
+            "agg", "cairo", "pdf", "pgf", "ps", "svg", "template",
+        ]
+        self._framework_to_backend_mapping = {
+            "qt": "qtagg",
+            "gtk3": "gtk3agg",
+            "gtk4": "gtk4agg",
+            "wx": "wxagg",
+            "tk": "tkagg",
+            "macosx": "macosx",
+            "headless": "agg",
+        }
+
+    def framework_to_backend(self, interactive_framework):
+        return self._framework_to_backend_mapping.get(interactive_framework)
+
+    def list_builtin(self, filter_=None):
+        if filter_ == BackendFilter.INTERACTIVE:
+            return self._builtin_interactive
+        elif filter_ == BackendFilter.INTERACTIVE_NON_WEB:
+            return list(filter(lambda x: x.lower() not in ("webagg", "nbagg"),
+                               self._builtin_interactive))
+        elif filter_ == BackendFilter.NON_INTERACTIVE:
+            return self._builtin_not_interactive
+
+        return self._builtin_interactive + self._builtin_not_interactive
+
+
+# Singleton
+backendRegistry = BackendRegistry()

lib/matplotlib/backends/registry.pyi

@@ -0,0 +1,16 @@
+from enum import Enum
+
+
+class BackendFilter(Enum):
+    INTERACTIVE: int
+    INTERACTIVE_NON_WEB: int
+    NON_INTERACTIVE: int
+
+
+class BackendRegistry:
+    def __init__(self) -> None: ...
+    def framework_to_backend(self, interactive_framework: str) -> str | None: ...
+    def list_builtin(self, filter_: BackendFilter | None) -> list[str]: ...
+
+
+backendRegistry: BackendRegistry

lib/matplotlib/pyplot.py

@@ -69,6 +69,7 @@
 from matplotlib.artist import Artist
 from matplotlib.axes import Axes
 from matplotlib.axes import Subplot  # noqa: F401
+from matplotlib.backends.registry import BackendFilter, backendRegistry
 from matplotlib.projections import PolarAxes
 from matplotlib import mlab  # for detrend_none, window_hanning
 from matplotlib.scale import get_scale_names  # noqa: F401
@@ -301,16 +302,10 @@ def switch_backend(newbackend: str) -> None:
 
     if newbackend is rcsetup._auto_backend_sentinel:
         current_framework = cbook._get_running_interactive_framework()
-        mapping = {'qt': 'qtagg',
-                   'gtk3': 'gtk3agg',
-                   'gtk4': 'gtk4agg',
-                   'wx': 'wxagg',
-                   'tk': 'tkagg',
-                   'macosx': 'macosx',
-                   'headless': 'agg'}
-
-        if current_framework in mapping:
-            candidates = [mapping[current_framework]]
+
+        if (current_framework and
+                (backend := backendRegistry.framework_to_backend(current_framework))):
+            candidates = [backend]
         else:
             candidates = []
         candidates += [
@@ -2509,10 +2504,10 @@ def polar(*args, **kwargs) -> list[Line2D]:
 # requested, ignore rcParams['backend'] and force selection of a backend that
 # is compatible with the current running interactive framework.
 if (rcParams["backend_fallback"]
-        and rcParams._get_backend_or_none() in (  # type: ignore[attr-defined]
-            set(rcsetup.interactive_bk) - {'WebAgg', 'nbAgg'})
-        and cbook._get_running_interactive_framework()):
-    rcParams._set("backend", rcsetup._auto_backend_sentinel)
+        and rcParams._get_backend_or_none() in (  # type: ignore
+            set(backendRegistry.list_builtin(BackendFilter.INTERACTIVE_NON_WEB)))
+        and cbook._get_running_interactive_framework()):  # type: ignore
+    rcParams._set("backend", rcsetup._auto_backend_sentinel)  # type: ignore
 
 # fmt: on
 

lib/matplotlib/rcsetup.py

@@ -23,6 +23,7 @@
 import numpy as np
 
 from matplotlib import _api, cbook
+from matplotlib.backends.registry import BackendFilter, backendRegistry
 from matplotlib.cbook import ls_mapper
 from matplotlib.colors import Colormap, is_color_like
 from matplotlib._fontconfig_pattern import parse_fontconfig_pattern
@@ -32,20 +33,34 @@
 from cycler import Cycler, cycler as ccycler
 
 
-# The capitalized forms are needed for ipython at present; this may
-# change for later versions.
-interactive_bk = [
-    'GTK3Agg', 'GTK3Cairo', 'GTK4Agg', 'GTK4Cairo',
-    'MacOSX',
-    'nbAgg',
-    'QtAgg', 'QtCairo', 'Qt5Agg', 'Qt5Cairo',
-    'TkAgg', 'TkCairo',
-    'WebAgg',
-    'WX', 'WXAgg', 'WXCairo',
-]
-non_interactive_bk = ['agg', 'cairo',
-                      'pdf', 'pgf', 'ps', 'svg', 'template']
-all_backends = interactive_bk + non_interactive_bk
+# Deprecation of module-level attributes using PEP 562
+_deprecated_interactive_bk = backendRegistry.list_builtin(BackendFilter.INTERACTIVE)
+_deprecated_non_interactive_bk = backendRegistry.list_builtin(
+    BackendFilter.NON_INTERACTIVE)
+_deprecated_all_backends = backendRegistry.list_builtin()
+
+_deprecated_names_and_args = {
+    "interactive_bk": "matplotlib.backends.registry.BackendFilter.INTERACTIVE",
+    "non_interactive_bk": "matplotlib.backends.registry.BackendFilter.NON_INTERACTIVE",
+    "all_backends": "",
+}
+
+
+def __getattr__(name):
+    if name in _deprecated_names_and_args:
+        arg = _deprecated_names_and_args[name]
+        _api.warn_deprecated(
+            "3.9.0",
+            name=name,
+            alternative="``matplotlib.backends.registry.backendRegistry"
+                f".list_builtin({arg})``",
+        )
+        return globals()[f"_deprecated_{name}"]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(globals().keys() | _deprecated_names_and_args.keys())
 
 
 class ValidateInStrings:
@@ -256,7 +271,7 @@ def validate_fonttype(s):
 
 
 _validate_standard_backends = ValidateInStrings(
-    'backend', all_backends, ignorecase=True)
+    'backend', backendRegistry.list_builtin(), ignorecase=True)
 _auto_backend_sentinel = object()
 
 

lib/matplotlib/tests/test_backend_registry.py

@@ -0,0 +1,59 @@
+from collections.abc import Sequence
+from typing import Any
+
+import pytest
+
+from matplotlib.backends.registry import BackendFilter, backendRegistry
+
+
+def has_duplicates(seq: Sequence[Any]) -> bool:
+    return len(seq) > len(set(seq))
+
+
+@pytest.mark.parametrize(
+    'framework,expected',
+    [
+        ('qt', 'qtagg'),
+        ('gtk3', 'gtk3agg'),
+        ('gtk4', 'gtk4agg'),
+        ('wx', 'wxagg'),
+        ('tk', 'tkagg'),
+        ('macosx', 'macosx'),
+        ('headless', 'agg'),
+        ('does not exist', None),
+    ]
+)
+def test_framework_to_backend(framework, expected):
+    assert backendRegistry.framework_to_backend(framework) == expected
+
+
+def test_list_builtin():
+    backends = backendRegistry.list_builtin()
+    assert not has_duplicates(backends)
+    # Compare using sets as order is not important
+    assert set(backends) == set((
+        'GTK3Agg', 'GTK3Cairo', 'GTK4Agg', 'GTK4Cairo', 'MacOSX', 'nbAgg', 'QtAgg',
+        'QtCairo', 'Qt5Agg', 'Qt5Cairo', 'TkAgg', 'TkCairo', 'WebAgg', 'WX', 'WXAgg',
+        'WXCairo', 'agg', 'cairo', 'pdf', 'pgf', 'ps', 'svg', 'template',
+    ))
+
+
+@pytest.mark.parametrize(
+    'filter,expected',
+    [
+        (BackendFilter.INTERACTIVE,
+         ['GTK3Agg', 'GTK3Cairo', 'GTK4Agg', 'GTK4Cairo', 'MacOSX', 'nbAgg', 'QtAgg',
+          'QtCairo', 'Qt5Agg', 'Qt5Cairo', 'TkAgg', 'TkCairo', 'WebAgg', 'WX', 'WXAgg',
+           'WXCairo']),
+        (BackendFilter.INTERACTIVE_NON_WEB,
+         ['GTK3Agg', 'GTK3Cairo', 'GTK4Agg', 'GTK4Cairo', 'MacOSX', 'QtAgg', 'QtCairo',
+          'Qt5Agg', 'Qt5Cairo', 'TkAgg', 'TkCairo', 'WX', 'WXAgg', 'WXCairo']),
+        (BackendFilter.NON_INTERACTIVE,
+         ['agg', 'cairo', 'pdf', 'pgf', 'ps', 'svg', 'template']),
+    ]
+)
+def test_list_builtin_with_filter(filter, expected):
+    backends = backendRegistry.list_builtin(filter)
+    assert not has_duplicates(backends)
+    # Compare using sets as order is not important
+    assert set(backends) == set(expected)

lib/matplotlib/tests/test_matplotlib.py

@@ -57,10 +57,12 @@ def parse(key):
             backends += [e.strip() for e in line.split(',') if e]
         return backends
 
+    from matplotlib.backends.registry import BackendFilter, backendRegistry
+
     assert (set(parse('- interactive backends:\n')) ==
-            set(matplotlib.rcsetup.interactive_bk))
+            set(backendRegistry.list_builtin(BackendFilter.INTERACTIVE)))
     assert (set(parse('- non-interactive backends:\n')) ==
-            set(matplotlib.rcsetup.non_interactive_bk))
+            set(backendRegistry.list_builtin(BackendFilter.NON_INTERACTIVE)))
 
 
 def test_importable_with__OO():