Merge pull request #24730 from timhoffm/rcparams-data-api

ksunden · web-flow · commit 488962a5d6f3 · 2022-12-23T12:42:36.000-06:00
Data access API for rcParams
diff --git a/doc/api/next_api_changes/deprecations/24730-TH.rst b/doc/api/next_api_changes/deprecations/24730-TH.rst
@@ -0,0 +1,24 @@
+rcParams type
+~~~~~~~~~~~~~
+Relying on ``rcParams`` being a ``dict`` subclass is deprecated.
+
+Nothing will change for regular users because ``rcParams`` will continue to
+be dict-like (technically fulfill the ``MutableMapping`` interface).
+
+The `.RcParams` class does validation checking on calls to
+``.RcParams.__getitem__`` and ``.RcParams.__setitem__``.  However, there are rare
+cases where we want to circumvent the validation logic and directly access the
+underlying data values.   Previously, this could be accomplished via  a call to
+the parent methods  ``dict.__getitem__(rcParams, key)`` and
+``dict.__setitem__(rcParams, key, val)``.
+
+Matplotlib 3.7 introduces ``rcParams._set(key, val)`` and
+``rcParams._get(key)`` as a replacement to calling the parent methods. They are
+intentionally marked private to discourage external use; However, if direct
+`.RcParams` data access is needed, please switch from the dict functions to the
+new ``_get()`` and ``_set()``. Even though marked private, we guarantee API
+stability for these methods and they are subject to Matplotlib's API and
+deprecation policy.
+
+Please notify the Matplotlib developers if you rely on ``rcParams`` being a
+dict subclass in any other way, for which there is no migration path yet.
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -620,7 +620,7 @@ def gen_candidates():
 )
 class RcParams(MutableMapping, dict):
     """
-    A dictionary object including validation.
+    A dict-like key-value store for config parameters, including validation.
 
     Validating functions are defined and associated with rc parameters in
     :mod:`matplotlib.rcsetup`.
@@ -640,6 +640,47 @@ class RcParams(MutableMapping, dict):
     def __init__(self, *args, **kwargs):
         self.update(*args, **kwargs)
 
+    def _set(self, key, val):
+        """
+        Directly write data bypassing deprecation and validation logic.
+
+        Notes
+        -----
+        As end user or downstream library you almost always should use
+        ``rcParams[key] = val`` and not ``_set()``.
+
+        There are only very few special cases that need direct data access.
+        These cases previously used ``dict.__setitem__(rcParams, key, val)``,
+        which is now deprecated and replaced by ``rcParams._set(key, val)``.
+
+        Even though private, we guarantee API stability for ``rcParams._set``,
+        i.e. it is subject to Matplotlib's API and deprecation policy.
+
+        :meta public:
+        """
+        dict.__setitem__(self, key, val)
+
+    def _get(self, key):
+        """
+        Directly read data bypassing deprecation, backend and validation
+        logic.
+
+        Notes
+        -----
+        As end user or downstream library you almost always should use
+        ``val = rcParams[key]`` and not ``_get()``.
+
+        There are only very few special cases that need direct data access.
+        These cases previously used ``dict.__getitem__(rcParams, key, val)``,
+        which is now deprecated and replaced by ``rcParams._get(key)``.
+
+        Even though private, we guarantee API stability for ``rcParams._get``,
+        i.e. it is subject to Matplotlib's API and deprecation policy.
+
+        :meta public:
+        """
+        return dict.__getitem__(self, key)
+
     def __setitem__(self, key, val):
         try:
             if key in _deprecated_map:
@@ -664,7 +705,7 @@ def __setitem__(self, key, val):
                 cval = self.validate[key](val)
             except ValueError as ve:
                 raise ValueError(f"Key {key}: {ve}") from None
-            dict.__setitem__(self, key, cval)
+            self._set(key, cval)
         except KeyError as err:
             raise KeyError(
                 f"{key} is not a valid rc parameter (see rcParams.keys() for "
@@ -675,27 +716,27 @@ def __getitem__(self, key):
             version, alt_key, alt_val, inverse_alt = _deprecated_map[key]
             _api.warn_deprecated(
                 version, name=key, obj_type="rcparam", alternative=alt_key)
-            return inverse_alt(dict.__getitem__(self, alt_key))
+            return inverse_alt(self._get(alt_key))
 
         elif key in _deprecated_ignore_map:
             version, alt_key = _deprecated_ignore_map[key]
             _api.warn_deprecated(
                 version, name=key, obj_type="rcparam", alternative=alt_key)
-            return dict.__getitem__(self, alt_key) if alt_key else None
+            return self._get(alt_key) if alt_key else None
 
         # In theory, this should only ever be used after the global rcParams
         # has been set up, but better be safe e.g. in presence of breakpoints.
         elif key == "backend" and self is globals().get("rcParams"):
-            val = dict.__getitem__(self, key)
+            val = self._get(key)
             if val is rcsetup._auto_backend_sentinel:
                 from matplotlib import pyplot as plt
                 plt.switch_backend(rcsetup._auto_backend_sentinel)
 
-        return dict.__getitem__(self, key)
+        return self._get(key)
 
     def _get_backend_or_none(self):
         """Get the requested backend, if any, without triggering resolution."""
-        backend = dict.__getitem__(self, "backend")
+        backend = self._get("backend")
         return None if backend is rcsetup._auto_backend_sentinel else backend
 
     def __repr__(self):
@@ -738,7 +779,7 @@ def copy(self):
         """Copy this RcParams instance."""
         rccopy = RcParams()
         for k in self:  # Skip deprecations and revalidation.
-            dict.__setitem__(rccopy, k, dict.__getitem__(self, k))
+            rccopy._set(k, self._get(k))
         return rccopy
 
 
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -202,10 +202,10 @@ def _get_backend_mod():
     This is currently private, but may be made public in the future.
     """
     if _backend_mod is None:
-        # Use __getitem__ here to avoid going through the fallback logic (which
-        # will (re)import pyplot and then call switch_backend if we need to
-        # resolve the auto sentinel)
-        switch_backend(dict.__getitem__(rcParams, "backend"))
+        # Use rcParams._get("backend") to avoid going through the fallback
+        # logic (which will (re)import pyplot and then call switch_backend if
+        # we need to resolve the auto sentinel)
+        switch_backend(rcParams._get("backend"))
     return _backend_mod
 
 
@@ -2241,7 +2241,7 @@ def polar(*args, **kwargs):
         and rcParams._get_backend_or_none() in (
             set(_interactive_bk) - {'WebAgg', 'nbAgg'})
         and cbook._get_running_interactive_framework()):
-    dict.__setitem__(rcParams, "backend", rcsetup._auto_backend_sentinel)
+    rcParams._set("backend", rcsetup._auto_backend_sentinel)
 
 
 ################# REMAINING CONTENT GENERATED BY boilerplate.py ##############
diff --git a/lib/matplotlib/tests/test_backends_interactive.py b/lib/matplotlib/tests/test_backends_interactive.py
@@ -249,13 +249,13 @@ def _impl_test_lazy_auto_backend_selection():
     import matplotlib
     import matplotlib.pyplot as plt
     # just importing pyplot should not be enough to trigger resolution
-    bk = dict.__getitem__(matplotlib.rcParams, 'backend')
+    bk = matplotlib.rcParams._get('backend')
     assert not isinstance(bk, str)
     assert plt._backend_mod is None
     # but actually plotting should
     plt.plot(5)
     assert plt._backend_mod is not None
-    bk = dict.__getitem__(matplotlib.rcParams, 'backend')
+    bk = matplotlib.rcParams._get('backend')
     assert isinstance(bk, str)
 
 
diff --git a/lib/matplotlib/tests/test_rcparams.py b/lib/matplotlib/tests/test_rcparams.py
@@ -544,7 +544,7 @@ def test_backend_fallback_headful(tmpdir):
          "sentinel = mpl.rcsetup._auto_backend_sentinel; "
          # Check that access on another instance does not resolve the sentinel.
          "assert mpl.RcParams({'backend': sentinel})['backend'] == sentinel; "
-         "assert dict.__getitem__(mpl.rcParams, 'backend') == sentinel; "
+         "assert mpl.rcParams._get('backend') == sentinel; "
          "import matplotlib.pyplot; "
          "print(matplotlib.get_backend())"],
         env=env, universal_newlines=True)
diff --git a/lib/matplotlib/tests/test_widgets.py b/lib/matplotlib/tests/test_widgets.py
@@ -967,7 +967,7 @@ def test_CheckButtons(ax):
 @pytest.mark.parametrize("toolbar", ["none", "toolbar2", "toolmanager"])
 def test_TextBox(ax, toolbar):
     # Avoid "toolmanager is provisional" warning.
-    dict.__setitem__(plt.rcParams, "toolbar", toolbar)
+    plt.rcParams._set("toolbar", toolbar)
 
     submit_event = mock.Mock(spec=noop, return_value=None)
     text_change_event = mock.Mock(spec=noop, return_value=None)
