Move towards having get_shared_{x,y}_axes return immutable views.

anntzer · anntzer · commit 0b836ed18b5d · 2022-03-16T20:39:38.000+01:00
Directly calling join() on the Groupers is not sufficient to share axes,
anyways, so don't let users do that.
diff --git a/doc/api/next_api_changes/deprecations/21584-AL.rst b/doc/api/next_api_changes/deprecations/21584-AL.rst
@@ -0,0 +1,6 @@
+Modifications to the Groupers returned by ``get_shared_x_axes`` and ``get_shared_y_axes``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... are deprecated.  In the future, these methods will return immutable views
+on the grouper structures.  Note that previously, calling e.g. ``join()``
+would already fail to set up the correct structures for sharing axes; use
+`.Axes.sharex` or `.Axes.sharey` instead.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -4603,9 +4603,9 @@ def twiny(self):
         return ax2
 
     def get_shared_x_axes(self):
-        """Return a reference to the shared axes Grouper object for x axes."""
-        return self._shared_axes["x"]
+        """Return an immutable view on the shared x-axes Grouper."""
+        return cbook.GrouperView(self._shared_axes["x"])
 
     def get_shared_y_axes(self):
-        """Return a reference to the shared axes Grouper object for y axes."""
-        return self._shared_axes["y"]
+        """Return an immutable view on the shared y-axes Grouper."""
+        return cbook.GrouperView(self._shared_axes["y"])
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -3180,9 +3180,9 @@ def release_zoom(self, event):
         for i, ax in enumerate(self._zoom_info.axes):
             # Detect whether this Axes is twinned with an earlier Axes in the
             # list of zoomed Axes, to avoid double zooming.
-            twinx = any(ax.get_shared_x_axes().joined(ax, prev)
+            twinx = any(ax._shared_axes["x"].joined(ax, prev)
                         for prev in self._zoom_info.axes[:i])
-            twiny = any(ax.get_shared_y_axes().joined(ax, prev)
+            twiny = any(ax._shared_axes["y"].joined(ax, prev)
                         for prev in self._zoom_info.axes[:i])
             ax._set_view_from_bbox(
                 (start_x, start_y, event.x, event.y),
diff --git a/lib/matplotlib/backend_tools.py b/lib/matplotlib/backend_tools.py
@@ -835,9 +835,9 @@ def _release(self, event):
             twinx, twiny = False, False
             if last_a:
                 for la in last_a:
-                    if a.get_shared_x_axes().joined(a, la):
+                    if a._shared_axes["x"].joined(a, la):
                         twinx = True
-                    if a.get_shared_y_axes().joined(a, la):
+                    if a._shared_axes["y"].joined(a, la):
                         twiny = True
             last_a.append(a)
 
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -902,6 +902,34 @@ def get_siblings(self, a):
         return [x() for x in siblings]
 
 
+class GrouperView:
+    """Immutable view over a `.Grouper`."""
+
+    def __init__(self, grouper):
+        self._grouper = grouper
+
+    class _GrouperMethodForwarder:
+        def __init__(self, deprecated_kw=None):
+            self._deprecated_kw = deprecated_kw
+
+        def __set_name__(self, owner, name):
+            wrapped = getattr(Grouper, name)
+            forwarder = functools.wraps(wrapped)(
+                lambda self, *args, **kwargs: wrapped(
+                    self._grouper, *args, **kwargs))
+            if self._deprecated_kw:
+                forwarder = _api.deprecated(**self._deprecated_kw)(forwarder)
+            setattr(owner, name, forwarder)
+
+    __contains__ = _GrouperMethodForwarder()
+    __iter__ = _GrouperMethodForwarder()
+    joined = _GrouperMethodForwarder()
+    get_siblings = _GrouperMethodForwarder()
+    clean = _GrouperMethodForwarder(deprecated_kw=dict(since="3.6"))
+    join = _GrouperMethodForwarder(deprecated_kw=dict(since="3.6"))
+    remove = _GrouperMethodForwarder(deprecated_kw=dict(since="3.6"))
+
+
 def simple_linear_interpolation(a, steps):
     """
     Resample an array with ``steps - 1`` points between original point pairs.
