From f25782f3db65a453cf6ea5500dae7a3e1f6e6208 Mon Sep 17 00:00:00 2001
From: Antony Lee <anntzer.lee@gmail.com>
Date: Wed, 10 Nov 2021 19:05:27 +0100
Subject: [PATCH] Move towards having get_shared_{x,y}_axes return immutable
 views.

Directly calling join() on the Groupers is not sufficient to share axes,
anyways, so don't let users do that.
---
 .../deprecations/21584-AL.rst                 |  6 ++++
 lib/matplotlib/axes/_base.py                  |  8 +++---
 lib/matplotlib/cbook/__init__.py              | 28 +++++++++++++++++++
 3 files changed, 38 insertions(+), 4 deletions(-)
 create mode 100644 doc/api/next_api_changes/deprecations/21584-AL.rst

diff --git a/doc/api/next_api_changes/deprecations/21584-AL.rst b/doc/api/next_api_changes/deprecations/21584-AL.rst
new file mode 100644
index 000000000000..c6f47530cddb
--- /dev/null
+++ 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
index c299fb3b0f94..663245523ffc 100644
--- a/lib/matplotlib/axes/_base.py
+++ b/lib/matplotlib/axes/_base.py
@@ -4595,9 +4595,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/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
index 340eb8db7ed9..b78cb775b59d 100644
--- a/lib/matplotlib/cbook/__init__.py
+++ b/lib/matplotlib/cbook/__init__.py
@@ -907,6 +907,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.